Charging per Mandate - חיוב לפי הרשאה

Scope of this release

This version supports charging mandates established through Feezback's Direct Debit Mandate flow only.

Prerequisites

Before submitting a charge:

• The debtor's mandate must be in valid status. Confirm this via a MandateStatusChanged webhook with currentStatus: "valid" from the Direct Debit Mandate flow.
• Store the customerId the debtor entered during mandate authorization — this is what you'll use to reference them when submitting charges. You never need to hold or transmit their bank account details yourself.
• Your organizationCode must be whitelisted for charging with Feezback. Contact your integration contact to confirm this is set up.

Environments

1. Create a token
2. Send the request with the token

Method: POST · Auth: Bearer token

See Configuring Environments & Security for token issuance:

Use the TPP domain when you call Feezback APIs with a bearer token.

How it works

1. Once a mandate is valid, store the debtor's customerId against your internal billing record.
2. The business day before you want to charge, submit a batch of charges to the endpoint above.
3. Feezback validates the batch and responds synchronously — this response reflects file-level and line-level validity only, not the outcome at Masav.
4. Feezback forwards valid charge lines to Masav for execution on executionDate.
5. Feezback sends a MandateBatchStatusUpdate webhook as the batch progresses through Masav.
6. Within 6 business days of executionDate, any charge line Masav rejects triggers a MandateChargeNotExecuted webhook. If no such webhook arrives for a line within that window, treat it as executed successfully.

A charge can be rejected at three points:

1. Synchronously at submission (invalid line/request).
2. Asynchronously at the file level — Masav rejects the whole batch.
3. Asynchronously at the individual charge level, up to 6 business days after executionDate (reported via MandateChargeNotExecuted). If a charge isn't rejected within that 6-day window, treat it as executed.

Submitting a charge batch

Request

{
  "context": "STRAUSS-CHG-20260716-001",
  "executionDate": "2026-07-16",
  "organizationCode": "24580",
  "charges": [
    {
      "chargeContext": "chg-00087421",
      "customerId": "8834215",
      "amount": "149.90",
      "companyName": "חברה 2",
      "remittanceInfo": "חיוב חודשי - קפסולות קפה"
    },
    {
      "chargeContext": "chg-00087422",
      "customerId": "8834298",
      "companyName": "חברה 3",
      "amount": "89.00"
    }
  ]
}

executionDate rules

• Cannot be earlier than the current date.
• Same-day execution is allowed only if the batch is submitted before 17:00 Israel time. Submissions after that cutoff for a same-day date are rejected.
• Cannot be more than 2 weeks from the current date.

Response

Feezback validates structure and per-line business rules and responds immediately — this does not wait for Masav.

There's no partial-success status, and no partial forwarding: if any charge line is invalid, the entire batch is rejected. Nothing in that batch is forwarded to Masav — errors tells you which line(s) caused the rejection so you can fix and resubmit (with a new context).

Full success:

{ "statusCode": 2000, "status": "Validated", "context": "STRAUSS-CHG-20260716-001" }

Contains invalid lines — entire batch rejected, errors identifies the offending lines:

{
  "statusCode": 2003,
  "status": "Rejected",
  "context": "STRAUSS-CHG-20260716-001",
  "errors": [
    { "chargeContext": "chg-00087422", "customerId": "8834298", "statusCode": 20032, "reason": "Mandate is not valid" },
    { "chargeContext": "chg-00087423", "customerId": "8834111", "statusCode": 20033, "reason": "customerId not found" },
    { "chargeContext": "chg-00087425", "statusCode": 20031, "reason": "Missing required field: amount" }
  ]
}

Whole-batch rejection (structural error — applies to the whole request, no specific charge line):

{
  "statusCode": 2001,
  "status": "Rejected",
  "context": "STRAUSS-CHG-20260716-001",
  "errors": [ { "reason": "organizationCode is missing from the request" } ]
}

Sub-codes returned inside errors when the top-level status is 2003:

Standard HTTP errors (401, 403, 429, 500) apply before business validation and don't carry a statusCode.

Resubmitting a batch

context must always be unique. If you submit a request with a context you've used before, it's rejected — regardless of what happened to the original batch, whether it was executed, still in progress, rejected, or never sent to Masav. There is no reuse path.

If a batch needs to be retried (for example, after fixing an invalid line), generate a new context for the retry rather than resubmitting the original.

Tracking execution

There are two webhook events for this flow. Both follow Feezback's standard envelope:

{ "timestamp": "2026-07-16T09:12:03.104Z", "event": "EventName", "payload": { ... } }

Your webhook endpoint must return HTTP 200 within 3 seconds. Don't validate against a strict schema — parse only the fields you need and ignore anything else, since fields may be added over time.

MandateBatchStatusUpdate — file-level status at Masav

{
  "timestamp": "2026-07-15T14:02:11.500Z",
  "event": "MandateBatchStatusUpdate",
  "payload": { "context": "STRAUSS-CHG-20260716-001", "status": "Sent" }
}

MandateChargeNotExecuted — per-line rejection

Fires for an individual charge line if Masav rejects it, any time up to 6 business days after executionDate. Treat a line as pending until either this webhook arrives or the 6-day window closes.

{
  "timestamp": "2026-07-18T10:41:22.019Z",
  "event": "MandateChargeNotExecuted",
  "payload": {
    "context": "STRAUSS-CHG-20260716-001",
    "chargeContext": "chg-00087423",
    "customerId": "8834350",
    "amount": "236.50",
    "executionDate": "2026-07-16",
    "reasonCode": "INSUFFICIENT_FUNDS"
  }
}

By default, only rejected lines trigger a webhook — there's no separate success notification. If you need explicit confirmation of successful charges as well, ask your integration contact; this can be enabled per account.

Charge line status reference

Note: Received describes different things at the batch level (file received by Masav) and the charge-line level (individual charge received, outcome pending) — check which object a given status appears on.

Constraints

• amount must be greater than 0, numeric, ILS only.
• organizationCode must be whitelisted for your account with Feezback.
• customerId must resolve to a mandate in valid status at time of submission — otherwise that line is rejected with 20032.
• context must be unique — see Resubmitting a batch.
• Maximum charges per batch is not yet published — check with your integration contact if you're submitting large batches.

Coming later

• Charging independently-established mandates using a raw account number instead of customerId — planned for a future release.
• Status/query API (GET batch and per-charge status) — planned, not yet available. For now, rely on MandateBatchStatusUpdate and MandateChargeNotExecuted webhooks to track outcomes.