> For the complete documentation index, see [llms.txt](https://docs.spendl.money/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.spendl.money/spendl-api-documentation/spendl-ingest-api-integration-guide.md).

# Spendl Ingest API - Integration Guide

Version: 1.108

> **Last Updated:** November 17, 2026

Use the Spendl Ingest API to connect your system to Spendl. This guide describes user ingestion, KYC, debt obligations, wallets, vouchers, payouts, remittances, crypto, cards, and the journal (your ledger).

***

## Base URLs

| Environment    | URL                                   |
| -------------- | ------------------------------------- |
| **Production** | `https://ingest.spendl.money`         |
| **Staging**    | `https://ingest.staging.spendl.money` |

Ask your Spendl account manager for credentials for the required environment.

***

## Quick Start

Complete these three steps:

```
1. Authenticate    →    2. Ingest Users    →    3. Upload KYC Documents
   POST /auth/token      POST /api/ingest        POST /api/kyc/:userId/...
```

1. **Authenticate** — Exchange your API key and secret for a JSON Web Token (JWT).
2. **Ingest users** — Send one user or a batch of users to Spendl.
3. **Upload KYC documents** — Upload each user's identity documents.

After KYC is complete, Spendl processes the user. Spendl then sends the user's bank account details by [webhook](#webhooks).

***

## Account Types

Each user has a **product type**. The product type controls which features are available after KYC approval.

| Product Type | Value      | Description                                                                    |
| ------------ | ---------- | ------------------------------------------------------------------------------ |
| **Wallet**   | `"Wallet"` | Wallet-only account — deposits, transfers, vouchers, EFT. No card provisioned. |
| **Smart**    | `"Smart"`  | Wallet + debit card — basic card tier (non-SA residents only)                  |
| **Savvy**    | `"Savvy"`  | Wallet + debit card — standard card tier                                       |
| **Guru**     | `"Guru"`   | Wallet + debit card — premium card tier                                        |

In the standard format, set `productType`. In the [flat format](#flat-format), set `spendl_product_type_id`.

In flat-format payloads, `spendl_product_type_id` defaults to `"Wallet"` when you omit it. This default does not apply when you supply an identity type. If you supply an identity type, you must also supply a product type. See [Required Fields](#required-fields).

For standard-format payloads, send `productType` explicitly.

> **Upgrading:** Wallet-only users can upgrade to a card tier in the Spendl Money App. The API does not support upgrades. Contact your Spendl account manager if you need an upgrade.

### FICA Identity Requirements

Each product type permits specific identity types. During ingestion, the API validates the combination. An invalid combination returns `422 INVALID_FICA_COMBINATION`.

| Product Type | Allowed Identity Types                                                 | Proof of Residence | Work Permit                     |
| ------------ | ---------------------------------------------------------------------- | ------------------ | ------------------------------- |
| **Wallet**   | `ID_CARD`, `GREEN_BOOK`, `PASSPORT`, `ASYLUM_SEEKER`, `REFUGEE_PERMIT` | No                 | No                              |
| **Smart**    | `PASSPORT` only                                                        | No                 | No                              |
| **Savvy**    | `ID_CARD`, `GREEN_BOOK`, `PASSPORT`, `ASYLUM_SEEKER`, `REFUGEE_PERMIT` | No                 | No                              |
| **Guru**     | `ID_CARD`, `GREEN_BOOK`, `PASSPORT`                                    | Optional           | **Yes** (passport holders only) |

**Identity type values:** In [KYC Data Fields](#kyc-data-fields), set `identityType`. In [flat format](#flat-format), set `identity_type`.

**Required KYC documents per combination:**

| Identity Type                      | Primary Document(s)            | Additional (Guru only)      |
| ---------------------------------- | ------------------------------ | --------------------------- |
| `ID_CARD`                          | `idProofFront` + `idProofBack` | —                           |
| `GREEN_BOOK`                       | `idProofFront`                 | —                           |
| `PASSPORT`                         | `proofPassport`                | `proofPermit` (work permit) |
| `ASYLUM_SEEKER` / `REFUGEE_PERMIT` | `proofPassport`                | — (not valid for Guru)      |

**ID card front only:** Spendl can set up your tenant so that an `ID_CARD` user needs only `idProofFront`. `idProofBack` is then optional for KYC and for a card, and every other requirement is unchanged. This does not apply to a user created from a [Sumsub share token](#create-user-from-sumsub-share-token): their identity documents come from Sumsub, which must hold both sides. Ask your Spendl account manager if your users' identity is verified without the back of the ID card.

A Guru user does not need a proof of residence (`proofRes`), but you can still upload one. To be issued a card, a Guru user still needs the residential address fields `addressLine1`, `suburb`, `city`, `province` and `postalCode`, as every card tier does. See [Card readiness](#card-readiness).

> **Note:** Upload each document through `POST /api/kyc/:userId/:documentType/:category/:filename`. The KYC submission stays `not_ready` until all required FICA documents are present.

#### Verification fields

Identity verification also needs the user's **gender** (`M` or `F`). The API does not require this field at ingestion. It accepts a record without it. Verification then behaves as follows:

| Identity Type                                 | `gender` omitted                                                                                                       |
| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `ID_CARD`, `GREEN_BOOK`                       | The API derives the value from the South African ID number                                                             |
| `PASSPORT`, `ASYLUM_SEEKER`, `REFUGEE_PERMIT` | Verification cannot complete. The user goes to manual review. You receive [`kyc.review_required`](#kycreview_required) |

Send `gender` for every user. Submit it with the KYC data (`kycDetails.kycData.gender` or flat `gender`). You can also add it later with [`PATCH /api/ingest/:id/kyc`](#replace-kyc-details). That route runs verification again when the data changes.

***

## Conventions

### Authentication Header

All endpoints under `/api/*` require a Bearer token:

```
Authorization: Bearer <accessToken>
```

Get the token from [POST /auth/token](#authentication). Tokens expire after **1 hour**. Call `/auth/token` again before the token expires.

Authentication failures return HTTP `401` with one of these stable types:

| Type                  | Cause                                    |
| --------------------- | ---------------------------------------- |
| `NO_AUTH_HEADER`      | The `Authorization` header is missing    |
| `INVALID_AUTH_FORMAT` | The header does not use `Bearer <token>` |
| `INVALID_TOKEN`       | The Bearer token is invalid or expired   |

### Content Types

| Endpoint Type      | Content-Type          |
| ------------------ | --------------------- |
| JSON endpoints     | `application/json`    |
| File uploads (KYC) | `multipart/form-data` |

### Error Format

All errors follow a consistent envelope:

```json
{
  "error": {
    "code": 422,
    "type": "VALIDATION_ERROR",
    "message": "Human-readable error description",
    "data": { }
  }
}
```

The stable `type` field uses `SCREAMING_SNAKE_CASE`. Use `type` for programmatic error handling.

The `message` field contains readable text and can change. The optional `data` field contains structured details. These details include field failures and FICA matrix violations.

### Temporary Errors

`404 SERVICE_NOT_AVAILABLE` and `404 SERVICE_NOT_FOUND` mean part of Spendl was briefly unavailable, for example while it restarted. It is temporary and says nothing about the user or resource you asked for. Retry after a few seconds, waiting longer between each attempt. On a money route, retry with the same idempotency key (see [Error Outcomes](#error-outcomes)).

A `404` can also be permanent, such as `USER_NOT_FOUND`, so check `type`, not the status code alone.

These temporary errors, and `REQUEST_TIMEOUT` (`504`), `REQUEST_REJECTED` (`503`) and `REQUEST_SKIPPED` (`514`) when Spendl raises them internally, have a plain `message` and no `data`. A timed-out, interrupted or skipped request may still have completed: retry it with the same idempotency key.

### Error Outcomes

For `POST /api/wallet/transfer` and `POST /api/wallet/send-to-bank`, the rule of thumb is: a `4xx` other than `409` means that request moved nothing; a `5xx` means it may have moved, except `PAYACCSYS_LOAD_FAILED` (debited, then refunded).

* **Nothing moved:** `VALIDATION_ERROR`, `INSUFFICIENT_FUNDS`, `ACCOUNT_RESTRICTED`, `KYC_REQUIRED`, `SELF_TRANSFER`, `WALLET_SUSPENDED`, `BENEFICIARY_NOT_FOUND`, `BENEFICIARY_NOT_REGISTERED`, `BANK_NOT_ELIGIBLE_FOR_IMMEDIATE`, `SERVICE_NOT_AVAILABLE` (retry later with the same key), every other `4xx` except `409`, `PAYACCSYS_LOAD_FAILED` (debited, then refunded: `data.reversed: true`), and a `409` whose `result.status` is `failed` (it never went through; send again with a new key). Fix the cause and send again. `PAYACCSYS_LOAD_FAILED` spends the key: start a new payment with a new key
* **May have moved:** `PAYACCSYS_EFT_AMBIGUOUS`, `WALLET_TRANSFER_FAILED`, `WALLET_SEND_TO_BANK_FAILED`, `REQUEST_TIMEOUT`, `REQUEST_REJECTED`, `REQUEST_SKIPPED`, `UPSTREAM_NETWORK_ERROR`, `INTERNAL_ERROR`, a plain-text `503` or `504` from the network edge, a `409` without `data.result`, or no response. Retry with the same key, which never pays twice, or check [Transaction History](#transaction-history)
* **Moved:** a `409` with `data.result` whose `result.status` is `posted`, and `PAYACCSYS_EFT_REVERSAL_FAILED` (debited but not paid; contact support). Do not send it again. A `409` whose `result.status` is `pending` is still running: retry later with the same key. One whose `result.status` is `reversed` was later reversed by Spendl (the money went back to the wallet): confirm in [Transaction History](#transaction-history) before sending a new payment with a new key

The rule describes the request it answers. On a same-key retry, an error such as `ACCOUNT_RESTRICTED`, `KYC_REQUIRED`, `USER_NOT_FOUND`, a `429` or an authentication error is returned before the key is checked, so it says nothing about the first attempt: treat that attempt as unknown.

Other money routes have their own outcome rules: some `4xx` errors follow a debit, mean the request is still running, or spend the key. See each route's errors: [load card](#load-card) (`422 CARD_NOT_FUNDABLE` follows a debit that was refunded, and spends the key), [Zapper withdrawal](#post-apiwalletwithdrawalzapper), [Voucher Payout Errors](#voucher-payout-errors), [remittance send](#initiate-send), [crypto](#error-envelope) and [disburse](#disburse-from-tenant-wallet).

Treat a timeout, an edge `503` or `504`, or no response as unknown, not failed: the request may still complete. Retry with the same key (see [Idempotency](#idempotency)). [Transaction History](#transaction-history) may not show a request that is still running, so an empty history alone is no reason to use a new key.

### Amounts & Currency

The Wallet API expresses amounts in **ZAR cents**. Send amounts as **positive integers**. Fields whose names end in `Itt`, such as `availableItt` or `dailyLimitItt`, also hold ZAR cents.

| Amount (cents) | Equivalent (ZAR) |
| -------------- | ---------------- |
| `50000`        | R500.00          |
| `1500`         | R15.00           |
| `100`          | R1.00            |

> **Note:** Wallet balances for liability accounts use negative values. A balance of `-50000` means the user has R500.00 available.

### Idempotency

Every money-moving endpoint accepts one idempotency key. A key prevents duplicate processing during retries. The same contract applies on every route:

Pass the key via **either**:

* Request body field: `"idempotencyKey": "your-unique-key"`
* HTTP header: `X-Idempotency-Key: your-unique-key`

If you send both, the values must match. A mismatch returns `422 IDEMPOTENCY_KEY_MISMATCH` before any money moves. A route that requires a key and receives none returns `422 MISSING_IDEMPOTENCY_KEY`. A key outside the route's length bounds returns `422 VALIDATION_ERROR`.

Some key prefixes are reserved for Spendl. On the wallet money routes, Zapper withdrawals and remittance sends, a key that starts with a reserved prefix is rejected with `422 VALIDATION_ERROR` before anything moves. A [disburse](#disburse-from-tenant-wallet) key with a reserved prefix fails every recipient inside a `200` (`status: "failed"`). Use UUIDs, which never start with a reserved prefix.

| Route family                                                                                          | Key                                                                             | Bounds                                                                                                                                   | Reused key                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /api/wallet/deposit`, `transfer`, `load-card`, `send-to-bank`, `purchase-voucher`, `repay-debt` | Required                                                                        | No bound is enforced. Keep keys at or below 200 characters: Spendl does not send the completion webhook for a request with a longer key. | `409 DUPLICATE_IDEMPOTENCY_KEY` with `data.existingEntryId` and `data.result`: act on its `status` (see [Idempotency](#idempotency): `posted` is processed; `pending` is still running, so retry later with the same key; `reversed` was later reversed, so check before trying again; `failed` moved nothing). Without `data.result`, the key was first used in another request: check the transaction history. A deposit retried with a different `amount` or `sourceWallet` (or with a `sourceWallet` when the first request had none, or the reverse) returns `409 IDEMPOTENCY_KEY_MISMATCH` and credits nothing. A failed or unconfirmed `load-card` or `send-to-bank` returns its first error again (a [held `fund_card` load](#held-fund_card-loads) returns its current outcome). A retry sent while the first request is still waiting for the payment provider returns `502 PAYACCSYS_LOAD_AMBIGUOUS` (load-card) or `502 PAYACCSYS_EFT_AMBIGUOUS` (send-to-bank) with `data.reversed: false`, not a `409`: retry later with the same key |
| `POST /api/wallet/beneficiary`; Pay@ and Zapper deposits                                              | Optional. Spendl generates a key for Pay@ and Zapper deposits when you omit it. | as above                                                                                                                                 | Pay@ and Zapper deposits return the original result once the first request has finished. While it is still running, or if it failed, they return a `409` (see [Pay@ deposit](#post-apiwalletdepositpayat) and [Zapper deposit](#post-apiwalletdepositzapper)). `POST /api/wallet/beneficiary` does not replay: a retry for a bank account the user already has returns `409` (see [Add Beneficiary](#add-beneficiary))                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `POST /api/wallet/disburse`                                                                           | Required                                                                        | 1–200 characters                                                                                                                         | Per-recipient keys derive as `${idempotencyKey}:${email}`. A same-key retry completes the remaining recipients; already-paid recipients return their original `journalEntryId` as `posted` or `escrowed` and are not paid again. The same key with a different sender, recipients or amounts returns `409 IDEMPOTENCY_KEY_MISMATCH`. Use a new key for a new disbursement. See [Disburse from tenant wallet](#disburse-from-tenant-wallet)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `POST /api/vouchers/perform`                                                                          | Required                                                                        | 1–200 characters                                                                                                                         | Recover with `GET /api/vouchers/status`. `422 VOUCHER_PAYOUT_FAILED` spends the key; every other `422` leaves it unused. See [Voucher Payout Errors](#voucher-payout-errors)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `POST /api/remittance/send`                                                                           | Required                                                                        | 1–256 characters                                                                                                                         | Replay of the original send                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `POST /api/remittance/transactions/:transactionId/retry-edit`                                         | Required                                                                        | 1–256 characters                                                                                                                         | Once a retry has been made with the key: returns the transfer as it is now, with `duplicate: true`; retries nothing                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `POST /api/crypto/withdrawals`, `POST /api/crypto/place-order`                                        | Required                                                                        | 8–128 characters                                                                                                                         | Replay of the original order                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `POST /api/wallet/withdrawal/payat`, `POST /api/wallet/withdrawal/zapper`                             | `withdrawalRequestId` in the body is the durable token                          | see each section                                                                                                                         | Pay@ cash withdrawal is [not available](#pay-integration) yet and returns `403 PAYAT_PAYOUT_NOT_ENABLED`; once available, Pay@ returns `409 PAYOUT_PIN_ALREADY_ISSUED`; Zapper replays a paid payment with `idempotentReplay: true`, one still processing as `429 SEND_IN_PROGRESS`, and a failed one as its `422` error                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |

Reuse the key after a lost response or a pending or ambiguous result. Check the status before you submit again. Do not reuse a key for a different request. `409 DUPLICATE_IDEMPOTENCY_KEY` means a request with this key was already accepted: never treat it as a failure. On the wallet routes that return `data.result` (below), it is your request's outcome only when `data.result` is present: act on its `status`, as described below (`posted` is processed; `pending` means retry later with the same key; `reversed` was later reversed, so check before trying again; `failed` moved nothing). Without `data.result`, the key was first used in another request and the 409 says nothing about this one: check the [Transaction History](#transaction-history) or contact support.

For the wallet routes in the first row, the 409's `data.result` holds the first request's outcome, so you can finish a retry without another lookup. It is included only when the key was first used in a request of yours for the same operation and the same user. It uses the field names and units (integer cents) of that route's success response, without the payment reference and fee fields of load-card and send-to-bank (`payaccsysRef`, `payaccsysFee`, `payaccsysFeeItt`). `journalEntryId` equals `data.existingEntryId`. `status` is the transaction's current status, and says what to do: `posted`: it went through, so treat it as processed; `pending`: the first request is still running, so retry later with the same key; `reversed`: Spendl later reversed it (a debit's money went back to the wallet; a deposit's credit was taken back), so it did not stand: confirm in the transaction history and contact support before trying again; `failed`: it never went through and moved nothing, so a new attempt needs a new key. A field the original transaction does not have is omitted.

| Route                                             | `data.result` fields                                                                                                    |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `POST /api/wallet/deposit`                        | `journalEntryId`, `userId`, `amount`, `feeAmount`, `netAmount`, `status`, and `sourceWallet` when the deposit named one |
| `POST /api/wallet/transfer`                       | `journalEntryId`, `senderUserId`, `receiverUserId`, `amount`, `feeAmount`, `netAmount`, `status`                        |
| `POST /api/wallet/purchase-voucher`, `repay-debt` | `journalEntryId`, `userId`, `amount`, `feeAmount`, `status`                                                             |
| `POST /api/wallet/load-card`                      | `journalEntryId`, `userId`, `amount`, `feeAmount`, `grossDebit`, `paymentMethod`, `status`, `channel`, `cardCredited`   |
| `POST /api/wallet/send-to-bank`                   | `journalEntryId`, `userId`, `amount`, `feeAmount`, `grossDebit`, `paymentMethod`, `status`                              |

On load-card, `channel` is the channel the load used, and `cardCredited` is `true` only once the card has been credited: a settled `fund_card` load reads `channel: "fund_card"`, `cardCredited: true`; an `eft` load, or a `fund_card` load that never posted, reads `cardCredited: false`. A same-key retry of a `fund_card` load that failed or is held gets the first attempt's error instead: its `502`, or `422 CARD_NOT_FUNDABLE` for a closed or expired card (see [held loads](#held-fund_card-loads)). If `data.result` has neither field, treat the load as `eft`. A `409` with no `data.result` (the key was first used in another request) says nothing about this load: check [Transaction History](#transaction-history).

A same-key retry of a [Send to Bank](#send-to-bank-eft) payment that went through:

```json
{
  "error": {
    "code": 409,
    "type": "DUPLICATE_IDEMPOTENCY_KEY",
    "message": "Duplicate idempotency key: eft-2026-10-14-0001",
    "data": {
      "key": "eft-2026-10-14-0001",
      "existingEntryId": "6641...",
      "result": {
        "journalEntryId": "6641...",
        "userId": "507f...",
        "amount": 50000,
        "feeAmount": 449,
        "grossDebit": 50449,
        "paymentMethod": "SAME_DAY",
        "status": "posted"
      }
    }
  }
}
```

***

## Endpoint Summary

### Public Endpoints (No Authentication)

| Method | Path          | Description                                                                             |
| ------ | ------------- | --------------------------------------------------------------------------------------- |
| GET    | `/health`     | Health check: `200` `{"ok": true}`, or `503` `{"ok": false}` while starting or stopping |
| POST   | `/auth/token` | Exchange API credentials for a JWT                                                      |

### Protected Endpoints (Require `Authorization: Bearer <JWT>`)

| Method | Path                                                     | Description                                                                                                    |
| ------ | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| POST   | `/api/ingest`                                            | Ingest single user or batch                                                                                    |
| POST   | `/api/ingest/sumsub`                                     | Create a user from a Sumsub Reusable KYC share token                                                           |
| PATCH  | `/api/ingest/:id/details`                                | Update mutable account details                                                                                 |
| PATCH  | `/api/ingest/:id/kyc`                                    | Replace KYC data and restart KYC verification                                                                  |
| PATCH  | `/api/ingest/:id/kyc/fill`                               | Fill an approved user's empty `phone`, `city` or `identityIssueCountry` without restarting KYC                 |
| POST   | `/api/validate`                                          | Validate payload without inserting                                                                             |
| GET    | `/api/ingest/status/:id`                                 | Check user ingestion and sync status                                                                           |
| POST   | `/api/kyc/:userId/:documentType/:category/:filename`     | Upload a KYC document                                                                                          |
| POST   | `/api/debt/ingest`                                       | Submit a debt obligation                                                                                       |
| POST   | `/api/debt/eligibility`                                  | Record a debt-offer eligibility notification                                                                   |
| POST   | `/api/debt/decision`                                     | Record your final decision on a debt offer                                                                     |
| POST   | `/api/decision-callback`                                 | Same as `POST /api/debt/decision`, under a second path                                                         |
| GET    | `/api/debt/status/:guid`                                 | Check debt obligation status                                                                                   |
| GET    | `/api/debt/audit-logs`                                   | List tenant-scoped debt audit logs                                                                             |
| GET    | `/api/wallet/balance/:userId`                            | Get wallet balance                                                                                             |
| GET    | `/api/wallet/history/:userId`                            | Get transaction history                                                                                        |
| GET    | `/api/wallet/:userId/depositRef`                         | Get a user's deposit reference                                                                                 |
| POST   | `/api/wallet/tenant-wallets`                             | Create a tenant wallet (**tenant\_wallet** scope)                                                              |
| POST   | `/api/wallet/disburse`                                   | Disburse from a tenant wallet to several recipients (**tenant\_wallet** scope)                                 |
| POST   | `/api/wallet/deposit`                                    | Deposit funds (**deposit** scope)                                                                              |
| POST   | `/api/wallet/transfer`                                   | Transfer between wallets                                                                                       |
| POST   | `/api/wallet/load-card`                                  | Top up a card                                                                                                  |
| POST   | `/api/wallet/send-to-bank`                               | EFT to external bank account                                                                                   |
| POST   | `/api/wallet/purchase-voucher`                           | **Deprecated.** Purchase a voucher. Use `/api/vouchers/*` instead                                              |
| GET    | `/api/vouchers/providers`                                | List enabled voucher and payout products                                                                       |
| GET    | `/api/vouchers/providers/:providerCode/limits`           | Get live amount limits and recipient fields for a voucher product                                              |
| POST   | `/api/vouchers/quote`                                    | Quote a voucher payout fee and total wallet debit                                                              |
| POST   | `/api/vouchers/perform`                                  | Issue a voucher, airtime product, cash payout, or bank payout                                                  |
| GET    | `/api/vouchers/status`                                   | Recover an owner-scoped voucher payout status                                                                  |
| POST   | `/api/wallet/repay-debt`                                 | Repay a debt obligation                                                                                        |
| POST   | `/api/wallet/beneficiary`                                | Register a bank beneficiary                                                                                    |
| GET    | `/api/wallet/beneficiaries/:userId`                      | List beneficiaries                                                                                             |
| DELETE | `/api/wallet/beneficiary/:userId/:beneficiaryId`         | Remove a beneficiary                                                                                           |
| GET    | `/api/wallet/bank-options`                               | List available banks                                                                                           |
| GET    | `/api/wallet/account-types`                              | List bank account types                                                                                        |
| GET    | `/api/wallet/supplier-types`                             | List supplier types                                                                                            |
| GET    | `/api/wallet/participating-banks`                        | List participating banks                                                                                       |
| POST   | `/api/wallet/deposit/payat`                              | Initiate a Pay@ deposit (top-up)                                                                               |
| POST   | `/api/wallet/withdrawal/payat`                           | **Not available.** Initiate a Pay@ withdrawal (issue cash-at-till PIN). Returns `403 PAYAT_PAYOUT_NOT_ENABLED` |
| GET    | `/api/payat/account/:userId`                             | Get a user's Pay@ deposit & payout account numbers (the payout number cannot be used yet)                      |
| GET    | `/api/payat/transactions`                                | Paginated Pay@ deposit transaction history (per-user)                                                          |
| GET    | `/api/payat/transactions/:id`                            | Single Pay@ deposit transaction detail                                                                         |
| GET    | `/api/payat/withdrawal/status/:withdrawalRequestId`      | Pay@ withdrawal PIN lifecycle status (PINs issued earlier only)                                                |
| GET    | `/api/payat/withdrawal/list/:userId`                     | Paginated Pay@ withdrawal history (per-user) (PINs issued earlier only)                                        |
| POST   | `/api/wallet/deposit/zapper`                             | Initiate a Zapper deposit (HPP wallet top-up)                                                                  |
| POST   | `/api/wallet/withdrawal/zapper/decode`                   | Decode a Zapper merchant QR code                                                                               |
| POST   | `/api/wallet/withdrawal/zapper`                          | Initiate a Zapper withdrawal (scan-to-pay)                                                                     |
| GET    | `/api/zapper/deposit/status/:sessionId`                  | Zapper deposit session status by sessionId                                                                     |
| GET    | `/api/zapper/deposit/status-by-order/:merchantOrderId`   | Zapper deposit session status by merchantOrderId                                                               |
| GET    | `/api/zapper/withdrawal/status/:paymentReference`        | Zapper scan-to-pay payment status                                                                              |
| POST   | `/api/wallet/deposit/checkout`                           | Create a hosted checkout deposit (wallet top-up by card, Capitec Pay or bank transfer on a hosted page)        |
| GET    | `/api/wallet/deposit/checkout/status/:sessionId`         | Hosted checkout deposit status                                                                                 |
| GET    | `/api/remittance/corridors`                              | List destinations, payment types, partner codes, and limits                                                    |
| GET    | `/api/remittance/banks`                                  | List destination banks for a country                                                                           |
| POST   | `/api/remittance/quote`                                  | Get an indicative remittance quote (remittances must be enabled)                                               |
| POST   | `/api/remittance/name-check`                             | Check a mobile-wallet recipient name (remittances must be enabled)                                             |
| POST   | `/api/remittance/validate`                               | Validate destination recipient details (remittances must be enabled)                                           |
| POST   | `/api/remittance/send`                                   | Initiate a cross-border transfer (remittances must be enabled)                                                 |
| GET    | `/api/remittance/transactions`                           | List a user's remittance transactions                                                                          |
| GET    | `/api/remittance/transactions/:transactionId`            | Get remittance transaction details                                                                             |
| GET    | `/api/remittance/transactions/:transactionId/status`     | Check remittance transaction status                                                                            |
| POST   | `/api/remittance/transactions/:transactionId/cancel`     | Always refused with `422 NOT_CANCELLABLE`: customers cannot cancel a remittance                                |
| POST   | `/api/remittance/transactions/:transactionId/retry-edit` | Retry a failed transfer, correcting the recipient (remittances must be enabled)                                |
| GET    | `/api/remittance/stats`                                  | Get a user's remittance statistics                                                                             |
| GET    | `/api/remittance/user-limits`                            | Get a user's remaining daily and monthly remittance headroom                                                   |
| GET    | `/api/crypto/market-data`                                | List market data for supported pairs                                                                           |
| GET    | `/api/crypto/market-data/:pair`                          | Get market data for one pair                                                                                   |
| GET    | `/api/crypto/deposit-addresses`                          | Get a user's crypto deposit addresses                                                                          |
| GET    | `/api/crypto/deposits`                                   | List a user's crypto deposits                                                                                  |
| GET    | `/api/crypto/balances`                                   | List a user's crypto balances                                                                                  |
| GET    | `/api/crypto/service-providers`                          | List withdrawal service providers                                                                              |
| GET    | `/api/crypto/withdrawals-config/:currency`               | Get withdrawal min, fee, and decimals                                                                          |
| POST   | `/api/crypto/withdrawals`                                | Create a crypto withdrawal                                                                                     |
| GET    | `/api/crypto/withdrawals`                                | List a user's crypto withdrawals                                                                               |
| GET    | `/api/crypto/withdrawals/:withdrawalId`                  | Get a crypto withdrawal                                                                                        |
| GET    | `/api/crypto/withdrawal-addresses`                       | List saved crypto withdrawal addresses                                                                         |
| GET    | `/api/crypto/transactions`                               | List a user's crypto transactions                                                                              |
| POST   | `/api/crypto/estimate-trade`                             | Estimate a market sell                                                                                         |
| POST   | `/api/crypto/place-order`                                | Place a market sell                                                                                            |
| GET    | `/api/crypto/order-status/:orderId`                      | Get sell order status                                                                                          |
| GET    | `/api/cards/:userId`                                     | List a user's cards with issuer state                                                                          |
| GET    | `/api/cards/:userId/limits`                              | Get monthly card funding limit and usage                                                                       |
| GET    | `/api/cards/:userId/funding-account`                     | Get the bank account used to load the card                                                                     |
| GET    | `/api/cards/:userId/readiness`                           | Check what a user still needs before a card can be issued                                                      |
| GET    | `/api/cards/:userId/card/:cardId`                        | Get masked card details                                                                                        |
| GET    | `/api/cards/:userId/card/:cardId/balance`                | Get card balance                                                                                               |
| GET    | `/api/cards/:userId/card/:cardId/transactions`           | Get card transactions (max 90-day window)                                                                      |
| GET    | `/api/journal/entries`                                   | List and filter your journal entries                                                                           |
| GET    | `/api/journal/entries/:journalId`                        | Get one journal entry by its ID                                                                                |
| GET    | `/api/journal/summary`                                   | Get journal activity totals for a period                                                                       |
| GET    | `/api/journal/trial-balance`                             | Get your ledger's trial balance                                                                                |

***

## Authentication

Exchange your API key and secret for a short-lived JSON Web Token (JWT).

### Request

```
POST /auth/token
Content-Type: application/json
```

```json
{
  "apiKey": "ak_xxx",
  "apiSecret": "sk_xxx"
}
```

### Response

```json
{
  "accessToken": "<JWT>",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}
```

### Usage

Include the token in all subsequent requests:

```
Authorization: Bearer <accessToken>
```

### Scopes

Each API key has scopes that decide which requests its tokens can make:

| Scope           | Allows                                                                                                                                |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `read`          | `GET` requests                                                                                                                        |
| `write`         | `POST`, `PATCH`, `PUT`, and `DELETE` requests                                                                                         |
| `deposit`       | [Direct deposits](#deposit-funds) into a user's wallet from one of your tenant wallets. The key also needs `write`                    |
| `tenant_wallet` | [Creating tenant wallets](#create-tenant-wallet) and [disbursing from them](#disburse-from-tenant-wallet). The key also needs `write` |

Ask your Spendl account manager for the `deposit` or `tenant_wallet` scope. Spendl adds it to your existing key; your API key and secret do not change. A token carries the scopes its key had when the token was issued, so call `/auth/token` again once the scope is added. The scope belongs to that key: a replacement key starts without it, so ask again when you rotate your key.

A request without the `read`, `write`, `deposit`, or `tenant_wallet` scope it needs returns `403 INSUFFICIENT_SCOPE`, and `data.requiredScope` names the missing scope. Suspense funding on a [deposit](#deposit-funds) needs the `admin` scope and is refused the same way, with `data.requiredScope: "admin"`.

### Important Notes

* Tokens expire after **1 hour**. The API does not provide refresh tokens. Call `/auth/token` again for a new token.
* Store your `apiKey` and `apiSecret` securely. Never expose them in client-side code.
* If your credentials are compromised, contact your Spendl account manager immediately. Ask them to revoke and reissue the credentials.

### Errors

| Code | Type                  | Description                        |
| ---- | --------------------- | ---------------------------------- |
| 401  | `INVALID_CREDENTIALS` | API key or secret is incorrect     |
| 401  | `API_KEY_EXPIRED`     | API key has passed its expiry date |
| 401  | `API_KEY_REVOKED`     | API key has been deactivated       |

### Example

```bash
curl -X POST "https://ingest.spendl.money/auth/token" \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "ak_xxx", "apiSecret": "sk_xxx"}'
```

***

## User Ingestion

### Ingest Users

Create Spendl user records. Send one user, a user batch, or a flat-format payload.

```
POST /api/ingest
Authorization: Bearer <accessToken>
Content-Type: application/json
```

### Required Fields

Each record must contain the following fields. For one insert, missing fields cause `422 VALIDATION_ERROR`. For a batch, the API adds the record to `failed` with `reason: "VALIDATION_ERROR"`.

| Field         | Standard format                   | Flat format              | Notes                                                                 |
| ------------- | --------------------------------- | ------------------------ | --------------------------------------------------------------------- |
| Email         | `userDetails.email`               | `email`                  | Always required. Stored trimmed and lowercase — see [Emails](#emails) |
| First name    | `kycDetails.kycData.name`         | `name`                   | Always required                                                       |
| Surname       | `kycDetails.kycData.surname`      | `surname`                | Always required                                                       |
| Date of birth | `kycDetails.kycData.dob`          | `birth_date`             | Always required                                                       |
| Product type  | `kycDetails.kycData.productType`  | `spendl_product_type_id` | Required **only if** an identity type is supplied                     |
| Identity type | `kycDetails.kycData.identityType` | `identity_type`          | Required **only if** a product type is supplied                       |

Supply `productType` and `identityType` **together**, or omit both fields. The API rejects a record that contains only one field.

When both fields are present, the API validates them against the [FICA matrix](#fica-identity-requirements). The API accepts records with **neither** field. You can add the identity type and KYC documents later.

A standard-format record can set only `userDetails.email`, `userDetails.status`, `kycDetails.kycData`, `clientNo`, and `preferences`. Any other field is ignored and the request is still accepted; for example, send the phone as `kycDetails.kycData.phone`, not `userDetails.phone`. Spendl sets account, KYC and compliance state as the user moves through registration and verification.

KYC documents are recorded only when you upload them with [`POST /api/kyc/:userId/:documentType/:category/:filename`](#kyc-document-upload). The API ignores `kycDetails.s3Keys` (the upload records) in an ingest record. It also ignores `debtOffer`, which only Spendl writes.

### Emails

* The API trims and lowercases every email (`userDetails.email` and `kycData.email`) when it stores it, and returns the stored value in responses and webhooks.
* `DUPLICATE_EMAIL` and `EMAIL_ALREADY_REGISTERED` both mean that this email cannot be used for a new user. The API never links a new user to an existing account. Do not re-send a user you already ingested.
* If an account with the email is created after the ingest is accepted, or the check cannot be completed at ingest, registration fails instead: [`GET /api/ingest/status/:id`](#check-ingestion-status) shows `registrationStatus: "failed"`, and `registrationError` says an account with that email already exists. Changing the user's email with [`PATCH /api/ingest/:id/details`](#update-account-details) to one that is free starts registration again. If the existing account is one your user created in your app and never used (for example, an abandoned sign-up), contact your Spendl account manager.
* A `PATCH /api/ingest/:id/details` that sends a user's email stores it trimmed and lowercase. Leave `email` out of a PATCH that does not change it.
* In a batch's `failed[]` and in `POST /api/validate`'s `errors[]`, each entry's `email` is the email as you sent it (`"unknown"` when the record has none, and `""` when you sent an empty one), so you can match it to your record.
* Match users to your records on `_id` / `userId`, not on email.

### Payload Formats

#### Standard Format — Single User

```json
{
  "data": {
    "userDetails": {
      "email": "user@example.com"
    },
    "kycDetails": {
      "kycData": {
        "name": "John",
        "surname": "Doe",
        "dob": "1990-01-15"
      }
    }
  }
}
```

**Response:**

```json
{
  "success": true,
  "user": {
    "_id": "507f1f77bcf86cd799439011",
    "userDetails": {
      "email": "user@example.com",
      "status": "pending"
    },
    "kycDetails": {
      "status": "Not Started"
    },
    "createdByApiKeyId": "id_abc123def456",
    "createdByTenant": "Your Company Name",
    "createdAt": "2026-01-28T10:30:00.000Z",
    "updatedAt": "2026-01-28T10:30:00.000Z"
  }
}
```

#### Standard Format — Batch

```json
{
  "data": [
    {
      "userDetails": { "email": "user1@example.com" },
      "kycDetails": { "kycData": { "name": "Jane", "surname": "Smith", "dob": "1988-03-22" } }
    },
    {
      "userDetails": { "email": "user2@example.com" },
      "kycDetails": { "kycData": { "name": "Sam", "surname": "Jones", "dob": "1992-07-11" } }
    }
  ]
}
```

**Response:**

```json
{
  "inserted": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "userDetails": { "email": "user1@example.com" },
      "createdByApiKeyId": "id_abc123def456",
      "createdByTenant": "Your Company Name"
    },
    {
      "_id": "507f1f77bcf86cd799439012",
      "userDetails": { "email": "user2@example.com" },
      "createdByApiKeyId": "id_abc123def456",
      "createdByTenant": "Your Company Name"
    }
  ],
  "insertedCount": 2,
  "failed": [
    {
      "email": "duplicate@example.com",
      "reason": "DUPLICATE_EMAIL"
    },
    {
      "email": "incomplete@example.com",
      "reason": "VALIDATION_ERROR",
      "errors": [
        "kycData.name is required",
        "kycData.surname is required",
        "kycData.dob is required"
      ]
    }
  ],
  "failedCount": 2
}
```

> **Batch behaviour:** The API processes each record independently. It inserts valid records when other records fail. Check `failed` for record-specific errors. Each entry has a `reason`. Validation failures also have an `errors` list. The request still returns HTTP `200`.

#### Flat Format

This format maps directly to KYC fields. Use the format when your system stores user data in a flat structure.

```json
{
  "data": {
    "email": "user@example.com",
    "name": "John",
    "surname": "Doe",
    "birth_date": "1990-01-15",
    "phone": "+27821234567",
    "identity_type": "ID_CARD",
    "id_number": "9001155000085",
    "country_id": "ZA",
    "city_id": "Cape Town",
    "zip": "8001",
    "street": "123 Main Street",
    "company_type": "Acme Inc",
    "employment_status": "employed",
    "accept_terms_and_conditions": "2026-01-01T12:00:00Z",
    "client_no": "00000000123456",
    "spendl_product_type_id": "Savvy"
  }
}
```

The API detects this format and maps it to the standard user structure. The response has the standard single-user response format.

> **Flat format with batch:** Wrap multiple flat objects in an array under `data` to submit a batch.

> **Product type (flat format only):** If you omit both `spendl_product_type_id` and `identity_type`, `spendl_product_type_id` defaults to `"Wallet"`. The API also changes unrecognised values to `"Wallet"`. If you supply one field, you **must** supply both. See [Required Fields](#required-fields) and [Account Types](#account-types).

> **Identity type (flat format):** Set `identity_type` to one of these values: `ID_CARD`, `GREEN_BOOK`, `PASSPORT`, `ASYLUM_SEEKER`, `REFUGEE_PERMIT`. The value must form a valid combination with `spendl_product_type_id`. See [FICA Identity Requirements](#fica-identity-requirements).

#### Flat Format Field Mapping

| Flat Field                    | Maps To                         | Notes                                                       |
| ----------------------------- | ------------------------------- | ----------------------------------------------------------- |
| `spendl_product_type_id`      | `productType`                   | Defaults to `"Wallet"`                                      |
| `identity_type`               | `identityType`                  | FICA-validated against product type                         |
| `email`                       | `email`                         |                                                             |
| `name`                        | `name`                          |                                                             |
| `surname`                     | `surname`                       |                                                             |
| `birth_date`                  | `dob`                           |                                                             |
| `phone`                       | `phone`                         |                                                             |
| `mobile`                      | `altPhone`                      |                                                             |
| `id_number`                   | `idNumber`                      |                                                             |
| `id_issue_date`               | `idIssue`                       |                                                             |
| `id_expiry_date`              | `idExpiry`                      |                                                             |
| `identity_issue_country`      | `identityIssueCountry`          |                                                             |
| `nationality_id`              | `nationality`                   |                                                             |
| `gender`                      | `gender`                        | `M` or `F`; see [Verification fields](#verification-fields) |
| `title`                       | `title`                         |                                                             |
| `preferred_language_id`       | `languageIndicator`             |                                                             |
| `contact_time`                | `suitableContactTime`           | 24-hour `HH:mm`; defaults to `"12:00"`                      |
| `residence_indicator`         | `residenceIndicator`            |                                                             |
| `residence_country_id`        | `residenceCountry`              |                                                             |
| `pep_pip_declaration`         | `pepPip`                        |                                                             |
| `permit_type`                 | `permitType`                    |                                                             |
| `permit_number`               | `permitNumber`                  |                                                             |
| `permit_issue_date`           | `permitIssue`                   |                                                             |
| `permit_expiry_date`          | `permitExpiry`                  |                                                             |
| `street`                      | `streetNumber` + `addressLine1` | Auto-split on leading number                                |
| `street2`                     | `addressLine1` (fallback)       |                                                             |
| `suburb` / `street3`          | `suburb`                        | `suburb` preferred, `street3` as fallback                   |
| `city_id`                     | `city`                          |                                                             |
| `state_id`                    | `province`                      |                                                             |
| `zip`                         | `postalCode`                    |                                                             |
| `country_id`                  | `country`                       |                                                             |
| `company_type`                | `company`                       |                                                             |
| `employment_status`           | `employmentStatus`              |                                                             |
| `spendl_source_of_funds_id`   | `sourceOfFunds`                 |                                                             |
| `spendl_account_purpose`      | `intendedPurposeOfAccount`      |                                                             |
| `accept_terms_and_conditions` | `tncAccepted` + `tncAcceptedAt` | ISO datetime → boolean + timestamp                          |
| `client_no`                   | `clientNo`                      | Used for debt obligation matching                           |

### Errors

| Code | Type                       | Description                                                                                                                                                                                                                                                                                                                                                                                                       |
| ---- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401  | `INVALID_TOKEN`            | Missing or invalid authentication token                                                                                                                                                                                                                                                                                                                                                                           |
| 409  | `DUPLICATE_EMAIL`          | This email cannot be used for a new user (see [Emails](#emails)). For batch inserts, the record is returned in `failed` with this `reason`                                                                                                                                                                                                                                                                        |
| 409  | `EMAIL_ALREADY_REGISTERED` | This email cannot be used for a new user (see [Emails](#emails)). The user is not created. For batch inserts, the record is returned in `failed` with this `reason`                                                                                                                                                                                                                                               |
| 422  | `VALIDATION_ERROR`         | Missing or invalid required fields — email, name, surname, dob, or an unpaired `productType`/`identityType`. For single inserts, `data` contains `{ errors, missingFields }`. For batch inserts, invalid records are returned per-record in the `failed` array, each with an `errors` list. See [Required Fields](#required-fields).                                                                              |
| 422  | `INVALID_FICA_COMBINATION` | The `productType` + `identityType` combination is not allowed — see [FICA Identity Requirements](#fica-identity-requirements). For single inserts only; `data` contains `{ productType, identityType, errors }`. For batch inserts, FICA combination errors are folded into the per-record `failed[]` entry: the `reason` is `VALIDATION_ERROR` and the FICA error message appears in the record's `errors` list. |

**Single user (cURL):**

```bash
curl -X POST "https://ingest.spendl.money/api/ingest" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "data": {
      "userDetails": { "email": "user@example.com" },
      "kycDetails": { "kycData": { "name": "John", "surname": "Doe", "dob": "1990-01-15" } }
    }
  }'
```

**Batch (cURL):**

```bash
curl -X POST "https://ingest.spendl.money/api/ingest" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "data": [
      { "userDetails": { "email": "user1@example.com" }, "kycDetails": { "kycData": { "name": "Jane", "surname": "Smith", "dob": "1988-03-22" } } },
      { "userDetails": { "email": "user2@example.com" }, "kycDetails": { "kycData": { "name": "Sam", "surname": "Jones", "dob": "1992-07-11" } } }
    ]
  }'
```

***

### Update Account Details

Update mutable details for an ingested user. Spendl then applies the update to the user's account.

```
PATCH /api/ingest/:id/details
Authorization: Bearer <accessToken>
Content-Type: application/json
```

Any API key for the same tenant may update the record. A missing user or an ID owned by another tenant returns `404 USER_NOT_FOUND`.

```json
{
  "data": {
    "userDetails": {
      "email": "new.email@example.com",
      "status": "pending"
    },
    "clientNo": "CLIENT-1002",
    "preferences": {
      "twoFactor": true
    }
  }
}
```

The update merges only the leaf fields that you supply. You can change `userDetails.email`, `userDetails.status`, `clientNo`, and `preferences`.

You cannot change system-owned fields through this route; to change KYC data, use [Replace KYC Details](#replace-kyc-details). A protected or unsupported field returns `422 PROTECTED_FIELDS`.

**Response:**

```json
{
  "success": true,
  "updateId": "1ec16b55-f92d-4c5a-bb26-830599f57425",
  "userId": "507f1f77bcf86cd799439011",
  "updateType": "details",
  "changedFields": [
    "userDetails.email",
    "userDetails.status",
    "clientNo",
    "preferences.twoFactor"
  ],
  "syncStatus": "synced",
  "callbackStatus": "enqueued",
  "retryScheduled": false,
  "updatedAt": "2026-07-30T10:00:00.000Z"
}
```

Spendl saves the accepted update before it applies it to the user's account. If Spendl cannot apply the update or queue its webhook straight away, the response can contain `syncStatus: "failed"`. It can also contain `callbackStatus: "pending"` with `retryScheduled: true`.

The update stays accepted. Spendl retries it later, applying the user's updates in the order it accepted them. Use `updateId` to match the related [`account.updated`](#accountupdated) webhook.

A new `userDetails.email` is stored trimmed and lowercase, and must be free as described in [Emails](#emails). Common errors are `INVALID_USER_ID` (422), `EMPTY_UPDATE` (422), `PROTECTED_FIELDS` (422), `VALIDATION_ERROR` (422), `INVALID_EMAIL` (422), `USER_NOT_FOUND` (404), `DUPLICATE_EMAIL` (409), `EMAIL_ALREADY_REGISTERED` (409), `DUPLICATE_CLIENT_NO` (409), `ACCOUNT_HELD` (409), and `ACCOUNT_UPDATE_CONFLICT` (409). `ACCOUNT_UPDATE_CONFLICT` means the account changed while the update ran, and nothing was applied. Retry the same request. `ACCOUNT_HELD` means Spendl compliance has suspended or deleted the account, so only Spendl can change its status: a request that sends `userDetails.status` is refused and nothing is applied. Contact Spendl support. An update without `userDetails.status` is accepted as usual. A malformed `userDetails.email` usually returns `VALIDATION_ERROR`; `INVALID_EMAIL` covers an address that passes that first check but is still not valid, such as one with two `@`.

Changing `userDetails.email` to a different address (not only a change of case) signs the user out on every device and removes the sign-in they set up: password, passkeys and linked social sign-in. Two-factor authentication stays on, so they will still need their authenticator app. A set-password link sent to the old address stops working. The user signs in again with an email code sent to the new address. Unless the account is `suspended`, `inactive` or `deleted`, Spendl also emails a set-password invite to the new address, if your tenant sends Spendl's set-password emails. These are on by default, even when your tenant's other emails are switched off. If emails are switched on for your tenant, Spendl also emails the previous address to say the sign-in email changed; that email doesn't show the new address. If the account now belongs to someone else and they can't pass two-factor authentication, contact Spendl support to clear it. The response and the [`account.updated`](#accountupdated) webhook are unchanged.

### Replace KYC Details

Replace a user's KYC data. Spendl applies the new data to the user's account and then restarts KYC verification.

```
PATCH /api/ingest/:id/kyc
Authorization: Bearer <accessToken>
Content-Type: application/json
```

Use the same single-record `data` wrapper as `POST /api/ingest`. The API accepts standard `UserInput` and flat-format payloads. The API does not accept arrays. The payload email must match the target account, ignoring case.

> **Restarts KYC, even for an approved user:** every accepted change (a PATCH answered with `unchanged: true` changes nothing) sets KYC and the account to pending and lifts any compliance hold. Until verification approves the user again, money actions that need approved KYC are refused. A field you omit is removed. See **What a change does** below.

The examples below are shortened; a real request sends the user's complete KYC data.

**Standard format:**

```json
{
  "data": {
    "userDetails": { "email": "user@example.com" },
    "kycDetails": {
      "kycData": {
        "productType": "Savvy",
        "identityType": "ID_CARD",
        "name": "John",
        "surname": "Doe",
        "dob": "1990-01-15",
        "idNumber": "9001155000085",
        "phone": "+27821234567"
      }
    }
  }
}
```

**Flat format:**

```json
{
  "data": {
    "email": "user@example.com",
    "spendl_product_type_id": "Savvy",
    "identity_type": "ID_CARD",
    "name": "John",
    "surname": "Doe",
    "birth_date": "1990-01-15",
    "id_number": "9001155000085",
    "phone": "+27821234567"
  }
}
```

The API replaces the whole normalized `kycData` object, so send every field you want to keep: a field you omit is removed. There are two exceptions. The document fields (`idProofFrontFile`, `idProofBackFile`, `passportProofFile`, `permitProofFile`, `idProofFile`, `proofOfResidenceFile`) keep their stored values unless you send them, and KYC documents already uploaded are kept. A value you send in a document field is stored but is not a document: only an [upload](#kyc-document-upload) counts towards the [FICA documents](#fica-identity-requirements). For a user created from a Sumsub share token, the identity and permit fields are kept as Sumsub left them (see **Users created from a Sumsub share token** below). In flat format, an omitted or unrecognised field can also store a default: `productType` is stored as `"Wallet"` when you omit both `spendl_product_type_id` and `identity_type`, or send a `spendl_product_type_id` that is not exactly `Wallet`, `Smart`, `Savvy` or `Guru`; without `contact_time`, `suitableContactTime` is `"12:00"`; and without `accept_terms_and_conditions`, `tncAccepted` is `false`. Send `spendl_product_type_id` on every flat-format PATCH. Required-field and FICA validation are the same as for ingestion.

**What a change does.** Every accepted PATCH restarts KYC, except one answered with `unchanged: true`. This applies in any KYC status, `Approved` included:

* `kycStatus` becomes `Pending`, an earlier rejection reason is cleared, and the account status (`userStatus`, `userDetails.status`) becomes `pending`, even when it was `suspended` or `inactive`. An account Spendl compliance has suspended or deleted keeps that status in Spendl, although `userStatus` can show `pending` (see below).
* Compliance screening goes back to `pending`, and its screening date, notes, screener and flag reason are cleared. The screening history is kept. This lifts a compliance hold (for example `flagged`), normally without a `compliance.hold_cleared` event.
* The previous verification result is cleared. Spendl verifies the new data again. Verification runs only once the required fields and, when `productType` and `identityType` are both set, the [FICA documents](#fica-identity-requirements) for them are present. Until then the user stays `Pending`, even when the response says `syncStatus: "submitted"`; the [status endpoint](#check-ingestion-status) shows `syncDetails.kycSubmissionStatus: "not_ready"`. The new outcome can be an approval, a review or a rejection (`kyc.approved`, `kyc.review_required` or `kyc.rejected`). Approval sets the account status to `active`, whatever it was before the PATCH, `suspended` and `inactive` included, except on an account Spendl compliance has suspended or deleted. That account keeps its status, a verification that needs review can be approved only once Spendl changes it, and `userStatus` on the status endpoint can show `pending` for it after the replacement although its status is unchanged: for a short while when suspended, and until Spendl changes the status when deleted.
* You receive `kyc.superseded`, `kyc.submission_pending` and `kyc.validation_pending` with `trigger: "kyc_replacement"`, then the usual submission and validation events, each only if you have an endpoint configured for it. You also receive [`account.updated`](#accountupdated) with this `updateId`. These events and `account.updated` can arrive in any order. The API does not replay password invites, `user.created`, or `bank_account_created`.
* `account.status_changed` may also be sent, but not for every KYC replacement. To detect one, use `account.updated` with `updateType: "kyc"`, or `kyc.superseded` with `trigger: "kyc_replacement"`.
* From the time the change is applied until verification approves the user again, money actions that need approved KYC are refused, including hosted-checkout and Zapper deposits. A remittance send returns `403 KYC_NOT_APPROVED`, and other money actions return `403 KYC_REQUIRED`. Scheduled debt installments are not collected. A response with `syncStatus: "submitted"` means the change is already applied.

To add only `phone`, `city` or `identityIssueCountry` to an approved user without restarting KYC, use [Fill Missing KYC Details](#fill-missing-kyc-details) instead.

[`PATCH /api/ingest/:id/details`](#update-account-details) rejects `kycDetails`, and any `userDetails` field other than `email` and `status`, with `422 PROTECTED_FIELDS`. A [KYC document upload](#kyc-document-upload) sets only the document's own field. For a registered user it also restarts submission and verification, so `kycStatus` goes back to `Pending` until the new outcome, but it does not reset the account status or compliance screening.

The response uses the account-details response format with `updateType: "kyc"`. For an accepted update, `syncStatus` is `pending`, `submitted`, or `failed`. `pending` means Spendl has accepted the update and will apply it. The status endpoint reports required KYC fields and documents in `kycSubmissionStatus`. `changedFields` lists only the `kycData` fields whose value changed, including fields the new data no longer has. It can be empty on an update that still restarts verification (the failed-state exception below), so do not read an empty `changedFields` as "nothing happened": `unchanged: true` is the only signal of that.

**Sending the same KYC again.** A PATCH whose data and documents equal what we already hold does not restart verification; the response has `unchanged: true`. Nothing is written or queued: the KYC status, an approval or a rejection and the compliance screening stay as they are, a verification already running continues, and no webhook is sent. `changedFields` is `[]`, `syncStatus` is the account's current KYC submission status (`pending`, `submitted` or `failed`), `callbackStatus` is `enqueued` and `retryScheduled` is `false`, because this request queued nothing. `updateId` is the one of the KYC update that stored this data, when we still hold it, so a retry after a timeout gets the original update's id; otherwise it is a new id that no `account.updated` webhook carries. You can therefore retry this request safely after a timeout.

We compare your data with what we hold as we store it. A number sent for a text field is stored as text, and `tncAccepted` and `samePostal` store the true-like values `true`, `"true"`, `"yes"`, `1` and `"1"` as `true` and the false-like values `false`, `"false"`, `"no"`, `0` and `"0"` as `false`. So `27821234567` equals a held `"27821234567"`, and `"yes"` a held `true`. A PATCH that only changes the JSON type of a named KYC field (a text field, `tncAccepted` or `samePostal`; e.g. `false` for `"false"`) is unchanged. Any other difference in a value counts as a change, including case, spaces, a leading zero (`"07700"` is not `7700`) and a date written another way. Inside an object field we hold the values as you sent them, so there `6` is not `"6"`. A field you omit that we hold as empty (`null`) is not a change. One exception: while the account's KYC submission or verification has `failed` (an error, not a decision), the same data restarts submission and verification as before, so a resend still recovers it; that response has no `unchanged`, and its `changedFields` is `[]`. After a rejection, sending the same data does not run verification again: correct the data, or contact Spendl support to have it re-run.

```json
{
  "success": true,
  "updateId": "5b0a3c2e-41d7-4d43-9a57-0e1f6c1f2a90",
  "userId": "507f1f77bcf86cd799439011",
  "updateType": "kyc",
  "changedFields": [],
  "syncStatus": "submitted",
  "callbackStatus": "enqueued",
  "retryScheduled": false,
  "updatedAt": "2026-10-15T10:57:28.440Z",
  "unchanged": true
}
```

**Users created from a Sumsub share token.** Their identity was verified by Sumsub, so this endpoint keeps the stored `name`, `surname`, `dob`, `gender`, `nationality`, `identityType`, `idNumber`, `idIssue`, `idExpiry`, `identityIssueCountry`, `permitNumber`, `permitIssue` and `permitExpiry`. You can omit those fields or send the same values. The same applies to the document fields (`idProofFrontFile`, `idProofBackFile`, `passportProofFile`, `permitProofFile`, `idProofFile`, `proofOfResidenceFile`): use [KYC Document Upload](#kyc-document-upload) to add a document. A different value, including one for a field Sumsub left empty, is rejected with `422 SUMSUB_IDENTITY_LOCKED` and `data.fields` lists the fields. Other fields are replaced as usual.

Common errors are `INVALID_USER_ID` (422), `INVALID_UPDATE_DATA` (422), `UNSAFE_FIELDS` (422), `EMAIL_MISMATCH` (422), `VALIDATION_ERROR` (422), `INVALID_FICA_COMBINATION` (422), `SUMSUB_IDENTITY_LOCKED` (422), `USER_NOT_FOUND` (404), and `ACCOUNT_UPDATE_CONFLICT` (409).

`UNSAFE_FIELDS` means a field name is not allowed (for example, it starts with `$` or contains `.`); `data.fields` lists the paths. `ACCOUNT_UPDATE_CONFLICT` means the account changed while the update ran, and nothing was applied. Retry the same request.

### Fill Missing KYC Details

Add `phone`, `city` or `identityIssueCountry` to an approved user's KYC data where it is empty, without restarting KYC. Use it for users approved before you collected these [Sender Profile](#sender-profile) fields.

```
PATCH /api/ingest/:id/kyc/fill
Authorization: Bearer <accessToken>
Content-Type: application/json
```

```json
{
  "data": {
    "kycData": {
      "phone": "27821234567",
      "city": "Johannesburg",
      "identityIssueCountry": "ZA"
    }
  }
}
```

| Field                          | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `kycData.phone`                | International number with its country code, 8 to 15 digits, optionally starting with `+`, for example `27821234567`. A South African number is `27` followed by 9 digits, without the leading `0`. A number with a leading `0` (`0821234567`), a South African mobile number without `27` (`821234567`), or one with spaces, dashes or brackets is refused. Always include the country code: other numbers without one are read as international numbers. Stored as digits, without the `+` |
| `kycData.city`                 | 2 to 100 characters, including a letter, with no control characters. Stored trimmed, with single spaces                                                                                                                                                                                                                                                                                                                                                                                     |
| `kycData.identityIssueCountry` | Two-letter ISO 3166-1 code of the country that issued the user's identity document, stored in capitals. For a South African ID card or green book it must be `ZA`, and the user's ID number must be a valid South African ID number that matches `dob`. For an asylum-seeker or refugee permit it must be `ZA`. For a passport it must be the user's `nationality`. For any other identity type, or none, it cannot be filled                                                               |
| `dryRun`                       | Optional boolean. `true` runs every check and answers with what would be filled, without changing anything                                                                                                                                                                                                                                                                                                                                                                                  |

Send one or more of the three fields, as strings, under these names. Any other field (including the flat-format names) returns `422 PROTECTED_FIELDS`; to change other KYC data, use [Replace KYC Details](#replace-kyc-details).

* Only empty fields are filled. A field that already holds the same value is left as it is. If a field holds a different value, the whole request is refused with `409 KYC_FIELD_ALREADY_SET` and nothing changes. A filled value can only be changed with Replace KYC Details, which restarts KYC, so check your values first with `dryRun: true`.
* The user's KYC must be `Approved`, and not being updated or verified at the time.
* KYC status, account status and compliance screening stay as they are, verification does not run again, and no webhook is sent. After a `200`, the filled fields count for the user's next remittance send at once; a send needs every [Sender Profile](#sender-profile) field.
* Sending the same request again is safe. When every field you send already holds that value, the response has `unchanged: true`.
* Every error except `409 ACCOUNT_UPDATE_CONFLICT` and `503 KYC_FILL_UNAVAILABLE` means nothing changed. After those two, some fields may already be filled: retry with the same values, which completes the fill.

To fill many users, run each request with `dryRun: true` first and resolve any refusal, then send the same body without `dryRun`. Retry a `409 ACCOUNT_UPDATE_CONFLICT`, a `503` or a timeout with the same body.

**Response:**

```json
{
  "success": true,
  "userId": "507f1f77bcf86cd799439011",
  "fillId": "3f1c2a9e-8b4d-4f6a-9c2e-7d5b1a0e4c83",
  "changedFields": ["kycData.phone", "kycData.city", "kycData.identityIssueCountry"],
  "unchanged": false,
  "dryRun": false,
  "updatedAt": "2026-11-10T08:00:00.000Z"
}
```

`changedFields` lists the fields this request filled, or would fill on a dry run. `fillId` identifies this request in Spendl's records; quote it if you contact support. `updatedAt` is the time the user's record last changed.

| Status | Type                                                                                          | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------ | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 422    | `INVALID_USER_ID`, `INVALID_UPDATE_DATA`, `UNSAFE_FIELDS`, `EMPTY_UPDATE`, `PROTECTED_FIELDS` | The request is malformed                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| 422    | `VALIDATION_ERROR`                                                                            | A value is not in the format above. `data.invalidFields` lists the field paths, such as `kycData.phone`, and `data.errors` gives the expected formats                                                                                                                                                                                                                                                                                                     |
| 422    | `IDENTITY_ISSUE_COUNTRY_MISMATCH`                                                             | The issuing country does not follow from the user's verified identity document, as described above. `data.reason` is `SA_DOCUMENT_REQUIRES_ZA`, `SA_ID_NUMBER_INVALID`, `PASSPORT_NATIONALITY_MISMATCH`, `NATIONALITY_UNRESOLVED` or `IDENTITY_TYPE_UNSUPPORTED`. Nothing was filled: send `phone` and `city` without `identityIssueCountry`, and set the issuing country with [Replace KYC Details](#replace-kyc-details), which verifies the user again |
| 422    | `SUMSUB_IDENTITY_LOCKED`                                                                      | The user was created from a [Sumsub share token](#create-user-from-sumsub-share-token), so `identityIssueCountry` cannot be filled; contact support. Send `phone` and `city` without it                                                                                                                                                                                                                                                                   |
| 403    | `KYC_NOT_APPROVED`                                                                            | The user's KYC is not `Approved`; `data.kycStatus` is its status (`none` when there is none). Fill the fields once the user is approved                                                                                                                                                                                                                                                                                                                   |
| 404    | `USER_NOT_FOUND`                                                                              | No such user for your tenant                                                                                                                                                                                                                                                                                                                                                                                                                              |
| 409    | `KYC_UPDATE_IN_PROGRESS`                                                                      | The user's KYC or an account update is still being processed. Retry later; contact support if it persists                                                                                                                                                                                                                                                                                                                                                 |
| 409    | `KYC_FIELD_ALREADY_SET`                                                                       | A field already holds a different value; `data.fields` lists the field paths. Nothing changed. To change a value, use [Replace KYC Details](#replace-kyc-details), which restarts KYC                                                                                                                                                                                                                                                                     |
| 409    | `KYC_RECORD_UNAVAILABLE`                                                                      | The user's KYC record cannot be filled. Contact support, quoting `data.fillId`                                                                                                                                                                                                                                                                                                                                                                            |
| 409    | `ACCOUNT_UPDATE_CONFLICT`                                                                     | The account changed while the request ran. Retry with the same values                                                                                                                                                                                                                                                                                                                                                                                     |
| 503    | `KYC_FILL_UNAVAILABLE`                                                                        | The fill could not be completed right now. Retry with the same values; if it persists, contact support, quoting `data.fillId`                                                                                                                                                                                                                                                                                                                             |

> **Later KYC replacements.** [Replace KYC Details](#replace-kyc-details) replaces all KYC data, so include `phone`, `city` and `identityIssueCountry` in any later replacement, with the values as stored (see the table above), or they are removed. A replacement that changes any value, including its format, restarts KYC.

For new users, send these fields when you ingest them, so no fill is needed.

***

### Create User from Sumsub Share Token

Create a user that you have already verified with Sumsub. Send only the details Sumsub does not hold, plus a Sumsub share token for the user's applicant. The API creates the user, redeems the token into Spendl's Sumsub account, and copies the verified identity details and identity documents into the user's KYC record. The user then follows the normal registration, KYC submission and validation pipeline, and the KYC decision is taken from the Sumsub review.

```
POST /api/ingest/sumsub
Authorization: Bearer <accessToken>
Content-Type: application/json
```

**Before you start.** Your Sumsub account must list Spendl as a Reusable KYC recipient. Generate the share token for each user immediately before this call:

```
POST https://api.sumsub.com/resources/accessTokens/shareToken
{ "applicantId": "<your applicant ID>", "forClientId": "<Spendl's Sumsub client ID>", "ttlInSecs": 600 }
```

A share token works once. Spendl cannot look up your applicants by any other identifier.

**Request:**

```json
{
  "data": {
    "userDetails": { "email": "user@example.com" },
    "kycDetails": {
      "kycData": {
        "productType": "Savvy",
        "title": "Mr",
        "employmentStatus": "Employed",
        "sourceOfFunds": "Salary",
        "intendedPurposeOfAccount": "Daily use",
        "tncAccepted": true
      }
    },
    "sumsub": {
      "shareToken": "_act-jwt-...",
      "donorApplicantId": "your-applicant-id"
    },
    "dryRun": false
  }
}
```

| Field                     | Required | Notes                                                                                                                                                                                                                 |
| ------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `userDetails.email`       | Yes      | Must match the email on the Sumsub applicant when the applicant has one                                                                                                                                               |
| `kycDetails.kycData`      | No       | Fields Sumsub does not hold: `productType`, `title`, `employmentStatus`, `sourceOfFunds`, `intendedPurposeOfAccount`, `tncAccepted`, contact preferences. Address and phone are optional; Sumsub values fill any gaps |
| `sumsub.shareToken`       | Yes      | Opaque, at most 1 KB. Never stored or returned                                                                                                                                                                        |
| `sumsub.donorApplicantId` | No       | Your applicant ID, kept for reconciliation only                                                                                                                                                                       |
| `dryRun`                  | No       | Boolean. `true` checks the token against Spendl's verification level without creating anything. Any non-boolean value is rejected with `422 VALIDATION_ERROR`                                                         |

Do not send `name`, `surname`, `dob`, `gender`, `nationality`, `identityType`, `idNumber`, `idIssue`, `idExpiry`, `identityIssueCountry` or the permit fields (`permitNumber`, `permitIssue`, `permitExpiry`). The API takes these only from what Sumsub extracted from the applicant's verified documents and residence permit, never from details the applicant typed in, and ignores any values you send. They are not stored, even if the share token then fails. A field Sumsub cannot supply is left empty and listed in `sumsub.unmappedIdentityFields`. It cannot be filled in through the API afterwards; contact support. One field is derived: when Sumsub holds no `gender` and the verified document is a South African ID with a valid ID number, the API reads the gender (`M` or `F`) from that number. For a passport or a foreign ID, a missing `gender` stays empty and is listed. The identity type comes from the verified document: an ID card (`ID_CARD`, or `GREEN_BOOK` for a South African ID with no back side) or a passport (`PASSPORT`). When the applicant has both, the ID card is used unless your `productType` accepts only a passport. A verified passport is always stored as `PASSPORT`. The `productType` and `identityType` pairing is checked against the [FICA matrix](#fica-identity-requirements) once the identity type is known.

**Response (200, details copied):**

```json
{
  "success": true,
  "user": { "_id": "665f1c2e8b3a4d0012ab34cd", "userDetails": { "email": "user@example.com" }, "kycDetails": { "status": "Pending" } },
  "sumsub": {
    "outcome": "hydrated",
    "applicantId": "68b0c0ffee0000000000abcd",
    "reviewStatus": "completed",
    "reviewAnswer": "GREEN",
    "documents": ["idProofFront", "idProofBack"],
    "skippedDocuments": [],
    "missingFields": [],
    "unmappedIdentityFields": [],
    "cardReadiness": { "productType": "Savvy", "cardEligible": true, "ready": true, "missingFields": [], "invalidFields": [], "missingDocuments": [] }
  }
}
```

`missingFields` lists required KYC fields that are still empty. Send non-identity fields with [Replace KYC Details](#replace-kyc-details) (or, for `phone` and `city` on an approved user, [Fill Missing KYC Details](#fill-missing-kyc-details)); for these users it keeps the Sumsub-verified identity and rejects changes to it. Identity documents also come only from Sumsub: uploading `idProofFront`, `idProofBack`, `proofPassport` or `proofPermit` returns `409 SUMSUB_IDENTITY_LOCKED`, while `proofRes` can be uploaded if Sumsub did not hold one. `cardReadiness` uses the same report as `GET /api/cards/:userId/readiness`.

**Response (202, review still running):** `sumsub.outcome` is `review_pending`. Sumsub is still checking the reused data. The API copies the details in automatically when the review finishes. Follow progress with [Check Ingestion Status](#check-ingestion-status) and the `kyc.*` webhooks.

Sumsub cannot finish the review when the shared verification does not satisfy Spendl's verification level: either the level needs a step that the shared verification does not include (for example a liveness check or a questionnaire), or a shared item fails Spendl's own check of it (for example an expired document or a document type Spendl does not accept). Sumsub then waits for the person to add or replace it, which they cannot do through this API. Spendl stops waiting, usually within a few minutes: you receive `kyc.review_required` with `reasonCode: "SUMSUB_DOCUMENTS_REQUESTED"`, and the status shows `lastErrorCode: "SUMSUB_DOCUMENTS_REQUESTED"`. Contact Spendl with the `userId`. Once the verification is completed in Sumsub, repeat this call with the same email to pick the user up again.

**Response (202, earlier attempt still being checked):** `sumsub.outcome` is `reconciling` and `applicantId` is `null`. An earlier call for this email may already have used a share token (status `reuseStatus: "reconciling"`), so the share token in this request is not used. Spendl finishes checking within about 10 to 15 minutes: the user then continues as for `review_pending`, or the status shows `SUMSUB_REUSE_NOT_CONFIRMED` and you send the call again.

**Retries.** Repeat the same request with the same email. A user created by an earlier attempt whose details were never copied in is picked up again, and its Sumsub applicant is reused rather than redeemed a second time. You can send a new share token if the earlier one expired.

**Lifecycle webhooks.** The API sends `user.created`, then `kyc.superseded`, `kyc.submission_pending` and `kyc.validation_pending` with `trigger: "sumsub_reuse"`, then the usual submission and validation events.

**Errors:**

| Code | Type                              | Description                                                                                                                                                                                                                                                                                                                           |
| ---- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 422  | `VALIDATION_ERROR`                | Missing email or share token, an unpaired `identityType` without `productType`, or a body that is not a single JSON object                                                                                                                                                                                                            |
| 422  | `UNSAFE_FIELDS`                   | A field name is not allowed (for example, it starts with `$` or contains `.`). `data.fields` lists the paths                                                                                                                                                                                                                          |
| 422  | `INVALID_FICA_COMBINATION`        | The verified identity type is not allowed for the `productType`. `data` contains `{ userId, productType, identityType, errors }`. Retry with an allowed `productType`                                                                                                                                                                 |
| 422  | `SUMSUB_DOCUMENTS_INCOMPLETE`     | Sumsub does not hold the identity documents Spendl needs for the verified identity type (for example both sides of an ID card). `data` contains `{ userId, applicantId, identityType, missingDocuments, skippedDocuments }`. Identity documents can only come from Sumsub, so complete them there and retry                           |
| 409  | `DUPLICATE_EMAIL`                 | This email cannot be used for a new user (see [Emails](#emails))                                                                                                                                                                                                                                                                      |
| 409  | `EMAIL_ALREADY_REGISTERED`        | This email cannot be used for a new user (see [Emails](#emails)). The user is not created and the share token is not used                                                                                                                                                                                                             |
| 409  | `SUMSUB_ALREADY_LINKED`           | This user's Sumsub details were already copied in. `data` contains `{ userId, applicantId }`                                                                                                                                                                                                                                          |
| 409  | `SUMSUB_REUSE_IN_PROGRESS`        | Another request for this user is running. Retry shortly                                                                                                                                                                                                                                                                               |
| 409  | `SUMSUB_EMAIL_MISMATCH`           | The Sumsub applicant's email differs from `userDetails.email`. Contact support                                                                                                                                                                                                                                                        |
| 409  | `SUMSUB_APPLICANT_MISMATCH`       | The Sumsub applicant Spendl read is not linked to this user, so nothing was copied in. Contact support                                                                                                                                                                                                                                |
| 409  | `SUMSUB_APPLICANT_ALREADY_LINKED` | The Sumsub applicant is linked to another user                                                                                                                                                                                                                                                                                        |
| 410  | `SHARE_TOKEN_EXPIRED`             | The share token is invalid, used or expired. Generate a new one and retry                                                                                                                                                                                                                                                             |
| 422  | `SHARE_TOKEN_INVALID`             | The token cannot be used: Spendl is not your recipient partner, Reusable KYC is disabled, or the token does not suit Spendl's level. `data.sumsubErrorCode` gives Sumsub's code                                                                                                                                                       |
| 422  | `REUSE_NOT_POSSIBLE`              | Sumsub cannot reuse this verification for Spendl's level, for example a document type, age, expiry or approval mismatch. `data.sumsubErrorCode` and `data.sumsubErrorName` give the reason                                                                                                                                            |
| 502  | `SUMSUB_UPSTREAM_ERROR`           | Sumsub returned an error or did not respond while Spendl was reading the applicant, its review, report or documents. Your share token is not the cause. If the share token was, or may have been, redeemed, Spendl keeps trying in the background and the user completes as for `review_pending`. Retrying the same call is also safe |
| 503  | `SUMSUB_NOT_CONFIGURED`           | Sumsub ingestion is not enabled in this environment                                                                                                                                                                                                                                                                                   |

Errors raised after the user was created include `data.userId`.

***

### Validate Without Inserting

Validate your payload without creating records.

```
POST /api/validate
Authorization: Bearer <accessToken>
Content-Type: application/json
```

Accepts the same request body as `/api/ingest`. It checks required fields, field types and allowed values, and FICA combinations only; it does not check an email's format or whether it is already taken, so `DUPLICATE_EMAIL` or `EMAIL_ALREADY_REGISTERED` can still follow on ingest. Each `errors[]` entry's `email` is the email as you sent it.

**Valid payload:**

```json
{
  "valid": true,
  "errors": []
}
```

**Invalid payload:**

```json
{
  "valid": false,
  "errors": [
    {
      "email": "user@example.com",
      "errors": [
        "kycData.name is required",
        "kycData.surname is required",
        "kycData.dob is required"
      ]
    }
  ]
}
```

***

### Check Ingestion Status

After ingestion, check the processing status of the user.

```
GET /api/ingest/status/:id
Authorization: Bearer <accessToken>
```

| Parameter | Type   | Description                                |
| --------- | ------ | ------------------------------------------ |
| `id`      | string | The `_id` returned from `POST /api/ingest` |

**Response:**

```json
{
  "_id": "507f1f77bcf86cd799439011",
  "email": "user@example.com",
  "userStatus": "active",
  "kycStatus": "Approved",
  "productType": "Wallet",
  "kycSource": "api",
  "sumsub": null,
  "syncDetails": {
    "registrationStatus": "registered",
    "registeredAt": "2026-01-29T10:05:00.000Z",
    "registrationError": null,
    "registrationAttempts": 1,
    "kycSubmissionStatus": "submitted",
    "kycSubmittedAt": "2026-01-29T10:06:00.000Z",
    "kycSubmissionError": null,
    "kycSubmissionAttempts": 1,
    "callbackStatus": "sent",
    "callbackSentAt": "2026-01-29T10:06:01.000Z",
    "callbackError": null,
    "callbackAttempts": 1,
    "detailsSyncStatus": "synced",
    "detailsSyncedAt": "2026-07-30T10:00:00.000Z",
    "detailsSyncError": null,
    "detailsSyncAttempts": 1,
    "kycValidation": {
      "status": "activated",
      "attempts": 1,
      "error": null,
      "rejectionReason": null,
      "completedAt": "2026-01-29T10:06:00.500Z",
      "provider": null,
      "reviewReasonCodes": []
    },
    "lastSyncAttempt": "2026-01-29T10:06:01.000Z"
  },
  "callbackUrl": "https://partner.example.com/webhook",
  "createdAt": "2026-01-29T10:00:00.000Z",
  "updatedAt": "2026-01-29T10:06:01.000Z"
}
```

A fully processed user has these values:

* `registrationStatus: "registered"`
* `kycSubmissionStatus: "submitted"`
* `callbackStatus: "sent"`

`userStatus` is the account status: `pending` until the account is activated, then `active`, `suspended` or `inactive`. It follows the account in Spendl, including activation when verification approves the user. `kycStatus` is `Not Started`, `Pending`, `Approved` or `Rejected`. Both are fixed values, never free text. Money actions need `kycStatus: Approved`.

`kycStatus` is `Pending` from KYC submission until verification completes. `syncDetails.kycValidation.status` reports the verification outcome. The value `tgpd_review` means that the user needs manual review. You also receive the [`kyc.review_required`](#kycreview_required) webhook. When the status is `tgpd_rejected`, `syncDetails.kycValidation.rejectionReason` gives the reason. The same text is sent in the [`kyc.rejected`](#kycrejected) webhook. `kycValidation.error` is only for processing failures, so it stays `null` for a rejection. If Spendl compliance later approves a user that verification rejected, `kycStatus` becomes `Approved`, `kycValidation.status` stays `tgpd_rejected` and `kycValidation.rejectionReason` is `null`; you also receive [`kyc.approved`](#kycapproved).

While the user is in review, `syncDetails.kycValidation.reviewReasonCodes` lists why, using the [review reason codes](#review-reason-codes). The same list is sent in the `kyc.review_required` webhook. A manual review decision does not change `kycValidation.status`, which stays `tgpd_review`, but the list becomes `[]` once Spendl sees the user approved or rejected (you also receive `kyc.approved` or `kyc.rejected`). It is `[]` for any other status. A review can also show `[]` when no reasons were recorded for it.

Spendl compliance may withdraw a KYC approval. `kycStatus` then changes from `Approved` to `Rejected`, and you receive [`kyc.rejected`](#kycrejected) with a `rejectionReason` you can show the user. If the account was `active`, `userStatus` returns to `pending` ([`account.status_changed`](#accountstatus_changed)), and you receive [`compliance.hold_set`](#compliancehold_set) unless a hold was already in place. `syncDetails.kycValidation` is unchanged: it keeps the automated outcome, so the reason is the one in the webhook. To verify the user again, replace their KYC data or a document ([Replace KYC Details](#replace-kyc-details); sending the same data again changes nothing). Spendl compliance reviews that verification before the user can be approved again.

> **Note:** `productType` can be `null` for some older records. It can also be `null` for standard-format ingestion when you did not supply the field.

`kycSource` is `sumsub` for users created with [Create User from Sumsub Share Token](#create-user-from-sumsub-share-token). Other users report `api` or `taskflow`, depending on how their KYC data arrived; treat any value other than `sumsub` as the standard KYC path. For those users, `sumsub` reports the link: `{ applicantId, reuseStatus, reviewStatus, reviewAnswer, reviewRejectType, reusedAt, hydratedAt, nextPollAt, lastErrorCode, lastErrorName }`. `hydratedAt` is set once the verified details are copied in. Until then the user is not created in your system (`registrationStatus` stays `pending`) and `kycSubmissionStatus` stays `pending`. `reuseStatus` is `pending`, `redeemed`, `failed` or `reconciling`. `reconciling` means the redemption call failed in a way that may still have used the token, so Spendl is checking with Sumsub; it becomes `redeemed`, or `failed` with `SUMSUB_REUSE_NOT_CONFIRMED` if Sumsub never shows the verification. `lastErrorCode` is set only when the work has stopped and needs action from you: a failed redemption (for example `SHARE_TOKEN_EXPIRED` or `SUMSUB_REUSE_NOT_CONFIRMED`, after which you send a share token again), a stopped copy (`SUMSUB_EMAIL_MISMATCH`, `SUMSUB_APPLICANT_MISMATCH`, `INVALID_FICA_COMBINATION` or `SUMSUB_DOCUMENTS_INCOMPLETE`), a review that cannot finish (`SUMSUB_DOCUMENTS_REQUESTED`), or `SUMSUB_REVIEW_TIMEOUT`. `nextPollAt` is then `null`. While Spendl is waiting on the review or retrying a temporary failure, `lastErrorCode` stays `null` and `nextPollAt` shows when the next attempt is due. For other users `sumsub` is `null`.

`syncDetails.kycValidation.provider` is `sumsub` when the Sumsub review decided the validation, and `null` when no identity check ran. The `kycValidation.status` values are the same for every user.

See [Sync Pipeline Statuses](#sync-pipeline-statuses) for all possible values.

**Errors:**

| Code | Type              | Description                             |
| ---- | ----------------- | --------------------------------------- |
| 401  | `INVALID_TOKEN`   | Missing or invalid authentication token |
| 404  | `USER_NOT_FOUND`  | No user found with the given `_id`      |
| 422  | `INVALID_USER_ID` | `id` is not in a valid user ID format   |

***

## KYC Document Upload

Upload the user's identity documents and, optionally, a proof of residence. Spendl stores the documents securely for KYC verification.

For a registered user, an upload restarts KYC submission and verification: `kycStatus` is `Pending` until the new outcome, and money actions that need approved KYC are refused until then. The account status and compliance screening are not reset. See [Replacing Documents After Registration](#replacing-documents-after-registration).

### Request

```
POST /api/kyc/:userId/:documentType/:category/:filename
Authorization: Bearer <accessToken>
Content-Type: multipart/form-data
```

### Path Parameters

| Parameter      | Type   | Required | Description                                               |
| -------------- | ------ | -------- | --------------------------------------------------------- |
| `userId`       | string | Yes      | The `_id` of the user (from `POST /api/ingest` response)  |
| `documentType` | string | Yes      | Document type (see table below)                           |
| `category`     | string | Yes      | `ID` for identity documents, `POR` for proof of residence |
| `filename`     | string | Yes      | Original filename (e.g., `id-front.jpg`)                  |

### Document Types

| Document Type   | Category | Description                                                       |
| --------------- | -------- | ----------------------------------------------------------------- |
| `idProofFront`  | `ID`     | Front of ID card                                                  |
| `idProofBack`   | `ID`     | Back of ID card                                                   |
| `proofPassport` | `ID`     | Passport photo page                                               |
| `proofPermit`   | `ID`     | Work or residence permit                                          |
| `proofRes`      | `POR`    | Proof of residence (utility bill, bank statement, etc.). Optional |

### Request Body

Send the file as `multipart/form-data` with a `file` field.

### Supported File Types

| MIME Type         | Extension       |
| ----------------- | --------------- |
| `image/jpeg`      | `.jpg`, `.jpeg` |
| `image/png`       | `.png`          |
| `application/pdf` | `.pdf`          |
| `image/heic`      | `.heic`         |
| `image/heif`      | `.heif`         |

**Maximum file size:** 10 MB. A PDF must also be 4 MB or smaller. Spendl compresses images to fit 4 MB.

> **Note:** Spendl converts every image (JPEG, PNG, HEIC, HEIF) to PDF on upload.

### Response

```json
{
  "success": true
}
```

### Errors

| Code | Type                          | Description                                                                                                                                                                                                                                                             |
| ---- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401  | `INVALID_TOKEN`               | Missing or invalid authentication token                                                                                                                                                                                                                                 |
| 404  | `USER_NOT_FOUND`              | User with given ID not found                                                                                                                                                                                                                                            |
| 413  | `FILE_TOO_LARGE`              | File exceeds 10 MB limit                                                                                                                                                                                                                                                |
| 415  | `UNSUPPORTED_MEDIA_TYPE`      | File type not supported                                                                                                                                                                                                                                                 |
| 409  | `SUMSUB_IDENTITY_LOCKED`      | The user was created from a Sumsub share token and this is an identity document (`idProofFront`, `idProofBack`, `proofPassport`, `proofPermit`), or a `proofRes` that Sumsub supplied. Those come only from Sumsub. `proofRes` is accepted when Sumsub did not hold one |
| 422  | `INVALID_DOCUMENT_TYPE`       | Invalid `documentType` parameter                                                                                                                                                                                                                                        |
| 422  | `INVALID_CATEGORY`            | `category` is not `ID` or `POR`                                                                                                                                                                                                                                         |
| 422  | `CATEGORY_MISMATCH`           | Category does not match the document type                                                                                                                                                                                                                               |
| 422  | `INVALID_USER_ID`             | Invalid user ID format                                                                                                                                                                                                                                                  |
| 422  | `EMPTY_FILE`                  | Uploaded file is empty                                                                                                                                                                                                                                                  |
| 422  | `MISSING_MIME_TYPE`           | Multipart upload does not include a file MIME type                                                                                                                                                                                                                      |
| 422  | `MISSING_FILE_STREAM`         | Multipart upload does not contain a readable file stream                                                                                                                                                                                                                |
| 422  | `USER_EMAIL_MISSING`          | The user has no `userDetails.email`. Add one with [Update Account Details](#update-account-details)                                                                                                                                                                     |
| 422  | `USER_NAME_MISSING`           | The user's KYC data has no `name` or `surname`. `data` contains `{ userId, hasFirstName, hasLastName }`                                                                                                                                                                 |
| 422  | `FILE_READ_ERROR`             | The uploaded file stream could not be read. Retry the upload                                                                                                                                                                                                            |
| 413  | `FILE_TOO_LARGE_FOR_UPSTREAM` | The image is still larger than 4 MB after Spendl converts and compresses it to PDF. Upload a smaller or lower-resolution file                                                                                                                                           |
| 500  | `PDF_CONVERSION_ERROR`        | The file could not be converted to PDF, or a PDF is larger than 4 MB. Upload a valid file, and keep PDFs to 4 MB or less                                                                                                                                                |
| 500  | `STORAGE_ERROR`               | Spendl could not confirm that the document was stored, and the user record was not changed. Retry the upload                                                                                                                                                            |
| 500  | `DATABASE_UPDATE_ERROR`       | The document was stored, but recording it on the user did not finish. The user record may be partly updated. `data.s3Key` names the stored file. Check [Check Ingestion Status](#check-ingestion-status) and contact support                                            |

### KYC Completion Requirements

A user's KYC is complete when all applicable items are present.

**All account types:**

1. **Personal data:** `name`, `surname`, `dob`, and `idNumber` (submitted via ingestion)
2. **Identity document matching the user's `identityType`:**
   * `ID_CARD` → requires `idProofFront` + `idProofBack` (only `idProofFront` if your tenant is set up for [ID card front only](#fica-identity-requirements))
   * `GREEN_BOOK` → requires `idProofFront`
   * `PASSPORT` / `ASYLUM_SEEKER` / `REFUGEE_PERMIT` → requires `proofPassport`

**Guru passport holders additionally require:**

3. **Work permit:** `proofPermit`

> **FICA-driven:** The `productType` and `identityType` combination determines the required documents. See [FICA Identity Requirements](#fica-identity-requirements). The user stays `not_ready` until you upload all required documents.

After KYC is complete, the system processes the user. It then sends the user's bank account details by [webhook](#webhooks).

### Replacing Documents After Registration

After a user is registered (`syncDetails.registrationStatus: "registered"`), a new document upload submits the KYC again. Verification then runs again against the new documents. This happens whether the previous verification completed or was still in progress. A verification of the old documents that is still in progress is superseded.

The following changes occur:

* `syncDetails.kycValidation.status` returns to `pending` on [`GET /api/ingest/status/:id`](#check-ingestion-status).
* `kycStatus` returns to `Pending`.
* A new outcome follows within about a minute, together with the applicable `kyc.*` [webhooks](#webhooks). These webhooks include a new [`kyc.review_required`](#kycreview_required) if the new verification needs manual review.

The user cannot transact while the new verification is in progress. Documents that you upload before registration completes join the initial submission.

### Example

```bash
curl -X POST "https://ingest.spendl.money/api/kyc/507f1f77bcf86cd799439011/idProofFront/ID/id-front.jpg" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/path/to/id-front.jpg"
```

***

## Debt Obligations

### Ingest Debt Obligation

Submit a debt obligation. The system uses `client_no` to find the user. It checks for duplicate `guid` and `(userId, loan_ref_no)` values. It stores the obligation. It then sends the result to your configured callback URL.

> **Prerequisite:** The payload `client_no` must identify an existing user, by the user's `clientNo` or by the user's Spendl ID (`_id`, 24 hexadecimal characters). First, ingest the user through [POST /api/ingest](#ingest-users). To match by `clientNo`, include `client_no` in the flat-format payload.

```
POST /api/debt/ingest
Authorization: Bearer <accessToken>
Content-Type: application/json
```

### Payload

```json
{
  "data": {
    "guid": "0123456789ABCDEF0123456789ABCDEF",
    "machine": "WINDOWS-PC",
    "client_no": "00000000123456",
    "loan_ref_no": "123456_12345",
    "first_dt": "20260331",
    "date_adj": 4,
    "frequency": 2,
    "track_cd": "03",
    "total_amt": 1800000,
    "inst_amt": 150000,
    "status": "0",
    "account_type": 0,
    "bank_acc_no": "1234567890",
    "bank_branch_cd": "470010",
    "pmt_stream": "ACOL",
    "inst_adj_amt": 0,
    "inst_adj_rate": 0,
    "allow_tracking": "T",
    "allow_date_chg": "T",
    "allow_max_inst": "F",
    "allow_any_cell_no": "T",
    "allow_scheduling": "T",
    "mode": "Realtime",
    "wait_response": "F"
  }
}
```

### Required Fields

| Field         | Type    | Description                                                                                                  |
| ------------- | ------- | ------------------------------------------------------------------------------------------------------------ |
| `guid`        | string  | Unique identifier — prevents duplicate submissions                                                           |
| `machine`     | string  | Originating machine identifier                                                                               |
| `client_no`   | string  | Client reference — an existing user's `clientNo`, or the user's Spendl ID (`_id`, 24 hexadecimal characters) |
| `loan_ref_no` | string  | Loan reference number                                                                                        |
| `first_dt`    | string  | First payment date (`YYYYMMDD` — must be a valid date)                                                       |
| `date_adj`    | integer | Date adjustment value                                                                                        |
| `frequency`   | integer | Payment frequency code                                                                                       |
| `track_cd`    | string  | Tracking code                                                                                                |
| `total_amt`   | integer | Total repayment amount in cents                                                                              |
| `inst_amt`    | integer | Instalment amount in cents                                                                                   |
| `status`      | string  | Obligation status                                                                                            |

`client_no` must be a string, and `guid` and `loan_ref_no` must not be objects or arrays. Otherwise the request returns `422 VALIDATION_ERROR`, and `data.invalidFields` names the fields.

### Bank Fields (All or None)

| Field            | Type    | Description         |
| ---------------- | ------- | ------------------- |
| `account_type`   | integer | Bank account type   |
| `bank_acc_no`    | string  | Bank account number |
| `bank_branch_cd` | string  | Bank branch code    |

Send all three bank fields, or none of them. If you send only some, the API returns `422 VALIDATION_ERROR` and names the missing ones.

You can leave all three out only if Spendl has set up your tenant to receive loan repayments into your [tenant wallet](#create-tenant-wallet). Otherwise an obligation without them is refused with `422 VALIDATION_ERROR` naming the three fields, as before. Once Spendl sets this up, repayments on obligations you send from then on are paid into your tenant wallet, whether or not you send bank fields. Ask your Spendl account manager to set it up.

If Spendl has set you up and an obligation without bank fields is still refused with `422 VALIDATION_ERROR` naming the three fields, send it again shortly.

### Optional Fields

| Field               | Type    | Description                                    |
| ------------------- | ------- | ---------------------------------------------- |
| `pmt_stream`        | string  | Payment stream identifier                      |
| `inst_adj_amt`      | integer | Instalment adjustment amount (defaults to `0`) |
| `inst_adj_rate`     | integer | Instalment adjustment rate (defaults to `0`)   |
| `allow_tracking`    | string  | `"T"` or `"F"`                                 |
| `allow_date_chg`    | string  | `"T"` or `"F"`                                 |
| `allow_max_inst`    | string  | `"T"` or `"F"`                                 |
| `allow_any_cell_no` | string  | `"T"` or `"F"`                                 |
| `allow_scheduling`  | string  | `"T"` or `"F"`                                 |
| `mode`              | string  | Processing mode (e.g., `Realtime`)             |
| `wait_response`     | string  | `"T"` or `"F"`                                 |

> **Note:** All `allow_*` flags and `wait_response` accept `"T"` or `"F"`. Values are not case-sensitive. If you omit a flag, the API uses `"F"`.
>
> **`client_no` format:** Send either the user's `clientNo` (for example, `00000000123456`) or the user's Spendl ID (`_id`, 24 hexadecimal characters; for example, `507f1f77bcf86cd799439011`). The API first looks for a user you ingested with that `clientNo`. If none matches, a 24-character hexadecimal value is looked up as the user's `_id`, and any other value as the `clientNo` of any user in your tenant. A `clientNo` that is itself 24 hexadecimal characters therefore matches only a user you ingested.
>
> **Callbacks:** The system sends the processing-result callback to a preconfigured endpoint for your tenant. The ingest payload may accept an `api_callback` field for compatibility. However, the system does **not** use that field to select the callback destination. See [Webhooks](#webhooks).

### Response

```json
{
  "success": true,
  "obligation": {
    "_id": "507f1f77bcf86cd799439011",
    "guid": "0123456789ABCDEF0123456789ABCDEF",
    "clientNo": "00000000123456",
    "loanRefNo": "123456_12345",
    "processingStatus": "callback_sent",
    "replyCd": "207",
    "replyStr": "Successful",
    "createdAt": "2026-02-24T10:00:00.000Z"
  }
}
```

### Errors

| Code | Type                     | Description                                                                                                                                                                                                                                                                                   |
| ---- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401  | `INVALID_TOKEN`          | Missing or invalid authentication token                                                                                                                                                                                                                                                       |
| 409  | `DUPLICATE_GUID`         | Debt obligation with this `guid` already exists                                                                                                                                                                                                                                               |
| 409  | `DUPLICATE_LOAN_REF`     | Debt obligation with this `loan_ref_no` already exists for the resolved user                                                                                                                                                                                                                  |
| 422  | `VALIDATION_ERROR`       | Missing or invalid required fields, or only some of the three bank fields                                                                                                                                                                                                                     |
| 422  | `USER_NOT_FOUND`         | No user found with matching `client_no`                                                                                                                                                                                                                                                       |
| 502  | `TENANT_DB_WRITE_ERROR`  | Spendl recorded the obligation, but processing it failed. Do not resend it: the same `guid` returns `409 DUPLICATE_GUID`. Spendl usually retries the processing. See [Check Debt Obligation Status](#check-debt-obligation-status), and contact support if it is still `failed` after an hour |
| 502  | `BACKEND_FORWARD_ERROR`  | Same as `TENANT_DB_WRITE_ERROR`: Spendl recorded the obligation, but processing it failed. Do not resend it. Spendl usually retries the processing. See [Check Debt Obligation Status](#check-debt-obligation-status), and contact support if it is still `failed` after an hour              |
| 502  | `CALLBACK_ENQUEUE_ERROR` | Spendl stored the obligation but could not schedule the processing-result callback. Spendl retries the callback. Do not resend the obligation. See [Check Debt Obligation Status](#check-debt-obligation-status)                                                                              |

## Debt Eligibility Notification

`POST /api/debt/eligibility` records an eligibility notification for a debt offer. It is an intake endpoint only: the Public API does not calculate an offer, perform affordability or credit checks, create a loan, or move money.

The request requires a Bearer JWT with `write` or `admin` scope. User lookup is restricted to the tenant in that token. Supply exactly one of `client_no` or `user_id`; both accept the user's `clientNo` or the user's Spendl ID (`_id`, 24 hexadecimal characters).

### Request

```json
{
  "data": {
    "uuid": "offer-4aa3d888",
    "client_no": "C001",
    "product_type": "payday_loan",
    "eligibility_signal": true,
    "capital_range": { "min": 500, "max": 5000 },
    "offer_capital_max": 3200,
    "offer_sizing": {
      "offer_percentage_min": 50,
      "offer_percentage_max": 75,
      "offer_basis_months": 3,
      "offer_weighting_method": "weighted_average",
      "slider_increment": 100,
      "product_max_capital": 5000
    },
    "timestamp": "2026-09-14T10:00:00.000Z"
  }
}
```

| Field                    | Type            | Description                                                                                     |
| ------------------------ | --------------- | ----------------------------------------------------------------------------------------------- |
| `uuid`                   | string          | Your stable identifier for this eligibility offer. Reuse it for retries.                        |
| `client_no` or `user_id` | string          | Exactly one required user identifier, resolved within the authenticated tenant.                 |
| `product_type`           | string          | Product identifier, such as `payday_loan`.                                                      |
| `eligibility_signal`     | boolean         | Eligibility result.                                                                             |
| `capital_range.min`      | number          | Required product minimum capital amount.                                                        |
| `capital_range.max`      | number          | Optional product maximum capital amount. When present, it must be at least `capital_range.min`. |
| `offer_capital_max`      | number          | Optional maximum offer calculated by Spendl, retained as an offer snapshot.                     |
| `offer_sizing`           | object          | Optional product sizing configuration snapshot.                                                 |
| `timestamp`              | ISO 8601 string | Time the eligibility notification was sent.                                                     |

### Response

New notifications and equivalent retries return `200 OK`:

```json
{
  "status": "acknowledged"
}
```

The unique key is the authenticated tenant and `uuid`. Reusing a UUID with different user, product, eligibility signal, capital range, offer maximum, offer sizing, or timestamp returns `409 DUPLICATE_ELIGIBILITY_UUID`. Invalid payloads and unknown users return `422 VALIDATION_ERROR` and `422 USER_NOT_FOUND` respectively.

### Example

```bash
curl -X POST "https://ingest.spendl.money/api/debt/eligibility" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "data": {
      "uuid": "offer-4aa3d888",
      "client_no": "C001",
      "product_type": "payday_loan",
      "eligibility_signal": true,
      "capital_range": { "min": 500, "max": 5000 },
      "offer_capital_max": 3200,
      "timestamp": "2026-09-14T10:00:00.000Z"
    }
  }'
```

### Offer Window

The customer can claim an offer for 48 hours from its `timestamp`. When the customer claims it, Spendl sends you a loan-decision request, and your final answer arrives on [Debt Offer Decision](#debt-offer-decision). An offer that nobody claims in time expires; Spendl sends you nothing when it does.

A decision for a claim made inside the window can arrive after the window has closed, because the credit check can finish late. It is accepted until the later of the window closing and 24 hours after Spendl last sent you the loan-decision request for the claim. After that the claim expires, normally within a minute, and a final decision then returns `409 OFFER_EXPIRED`. Spendl sends you nothing when a claim expires either; the `409` is how you find out. The customer can sign the loan agreement and accept the loan until the window closes, or until 24 hours after the approval when that is later.

### Debt Offer Decision

`POST /api/debt/decision` records your final decision on an offer that `POST /api/debt/eligibility` created. When the customer claims the offer, Spendl sends you a loan-decision request; you answer it with `declined` or `pending` straight away, and send the approve or decline that follows the credit-bureau check to this endpoint.

`POST /api/decision-callback` is the same endpoint under a second path. Both paths accept the same request and return the same responses.

Like the eligibility endpoint, this is intake only: Spendl makes no decision, runs no check, creates no loan, and moves no money. A successful call stores the decision on the offer.

The request requires a Bearer JWT with `write` or `admin` scope. The offer is looked up by `uuid` within the tenant in that token. Send the `uuid` of the loan-decision request Spendl sent you for the offer; the `uuid` of the eligibility offer itself is also accepted. Whichever lookup finds the offer, a final decision is refused with `409 OFFER_NOT_CLAIMED`, `OFFER_EXPIRED` or `OFFER_CONSENT_MISSING` unless the customer claimed the offer inside its window with credit-check consent and the decision arrives before the claim expires (see [Offer Window](#offer-window)); the lookup never marks an offer claimed.

Spendl records every decision it receives, including one it refuses, in the debt audit log, so a callback you send once can be traced. The record holds the decision fields only, never `affordability_summary`.

#### Request

```json
{
  "data": {
    "uuid": "offer-4aa3d888",
    "status": "approved",
    "product_type": "payday_loan",
    "request_id": "spendl-req-7f3a2c",
    "assessment_id": "8d0f2b1e-5f1a-4c3d-9a7b-2e6c4f8a1b90",
    "description": "Approved",
    "capital": 2000,
    "initiation_fee": 150,
    "repayment_total": 2150,
    "term": 1,
    "due_date": "2026-09-28",
    "affordability_summary": {
      "assessment_id": "8d0f2b1e-5f1a-4c3d-9a7b-2e6c4f8a1b90",
      "income": 9000,
      "expenses": 5500,
      "surplus_after_repayment": 1350,
      "assessed_at": "2026-09-14T10:04:30.000Z"
    }
  }
}
```

| Field                   | Type    | Description                                                                                                                                                                    |
| ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `uuid`                  | string  | Required. The `uuid` of the loan-decision request this decision answers, or the `uuid` of the eligibility offer.                                                               |
| `status`                | string  | Required. `approved`, `declined`, or `pending`.                                                                                                                                |
| `product_type`          | string  | Optional. Rejected when it does not match the offer.                                                                                                                           |
| `request_id`            | string  | Optional. Spendl's decision-request identifier, stored for the audit trail.                                                                                                    |
| `assessment_id`         | string  | Required for an approval. UUID of the affordability assessment. At most 200 characters, like every text field in the request.                                                  |
| `description`           | string  | Customer-safe message. Never include a bureau-derived reason. At most 200 characters.                                                                                          |
| `loan_id`               | string  | Optional. The loan reference is issued in the answer to the loan acceptance, not on the decision.                                                                              |
| `capital`               | number  | Required for an approval. Approved loan capital. Greater than zero, at most R8,000, and inside the offer's `capital_range`.                                                    |
| `initiation_fee`        | number  | Required for an approval. Flat initiation fee. At most R1,050.                                                                                                                 |
| `repayment_total`       | number  | Required for an approval. Must equal `capital` plus `initiation_fee`.                                                                                                          |
| `term`                  | integer | Optional. Loan term in instalments, from 1 to 6. Must be `1` for a `payday_loan`.                                                                                              |
| `due_date`              | string  | Required for an approval. Loan due date. Must be a valid ISO 8601 date (`YYYY-MM-DD`, optionally with a time and offset) naming a day that exists, so `2026-02-30` is refused. |
| `affordability_summary` | object  | Optional. Income, expenses, and surplus, for display only. Each at most R10,000,000.                                                                                           |

A decision for a product other than a payday loan sends only the fields that apply to it.

**Amounts.** Send amounts in rand with at most two decimals. An amount with more decimals cannot be paid and returns `422 VALIDATION_ERROR`. Spendl converts each amount to integer cents on receipt and stores cents, so totals are exact: `capital: 2000.10` with `initiation_fee: 150.20` and `repayment_total: 2150.30` is accepted. An amount above its ceiling, or a `capital` of `0`, returns `422 VALIDATION_ERROR`. An approved `capital` outside the offer's `capital_range` returns `422 CAPITAL_OUTSIDE_OFFER_RANGE`.

**Offer state.** An `approved` or `declined` answers the customer's claim, so the offer must have been claimed inside its 48-hour window and must hold the customer's credit-check consent. Otherwise the decision returns `409` with `OFFER_NOT_CLAIMED`, `OFFER_EXPIRED` or `OFFER_CONSENT_MISSING`. The window governs the claim, not the answer: an answer that arrives after the window for a claim made inside it is accepted until the window closes or 24 hours after Spendl last sent you the loan-decision request, whichever is later. After that the claim expires and the answer returns `409 OFFER_EXPIRED`. The customer gets 24 hours from the approval to sign and accept (see [Offer Window](#offer-window)). A `pending` that fails these rules (the offer was never claimed, its window closed before it was claimed, or the claim has expired) is acknowledged and not stored.

#### Response

New decisions and exact repeats return `200 OK`:

```json
{
  "status": "acknowledged"
}
```

A repeat that carries the same decision changes nothing on the offer and returns `acknowledged`, so a retry is safe. The repeat is checked before the offer state, so it is acknowledged even after the offer's window has closed.

`pending` is not an answer. A `pending` already stored against the offer is replaced by the `approved` or `declined` that follows it. A `pending` that arrives *after* an answer is late, not contradictory: it returns `acknowledged`, changes nothing, and the answer stands.

Once an `approved` or a `declined` is stored, a **different** `approved` or `declined` for the same offer returns `409 DUPLICATE_DECISION`; Spendl does not choose between two final answers.

#### Errors

| Code | Type                          | Description                                                                                                                                |
| ---- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| 401  | `INVALID_TOKEN`               | Missing or invalid authentication token                                                                                                    |
| 403  | `INSUFFICIENT_SCOPE`          | The token does not carry `write` or `admin` scope                                                                                          |
| 409  | `DUPLICATE_DECISION`          | The offer already holds a different final decision                                                                                         |
| 409  | `OFFER_NOT_CLAIMED`           | A final decision for an offer the customer has not claimed                                                                                 |
| 409  | `OFFER_EXPIRED`               | A final decision for an offer not claimed inside its 48-hour window, or for a claim that has expired (see [Offer Window](#offer-window))   |
| 409  | `OFFER_CONSENT_MISSING`       | A final decision for an offer without the customer's credit-check consent                                                                  |
| 422  | `VALIDATION_ERROR`            | Missing or invalid fields, a text field longer than 200 characters, an amount finer than cents, or an approval that omits a required field |
| 422  | `OFFER_NOT_FOUND`             | No eligibility offer in this tenant has that `uuid`                                                                                        |
| 422  | `PRODUCT_TYPE_MISMATCH`       | `product_type` does not match the offer                                                                                                    |
| 422  | `CAPITAL_OUTSIDE_OFFER_RANGE` | The approved `capital` is outside the offer's `capital_range`                                                                              |
| 503  | `DECISION_WRITE_CONTENTION`   | The decision was not stored because the offer was being updated at the same time. Retry the request                                        |

#### Example

```bash
curl -X POST "https://ingest.spendl.money/api/debt/decision" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "data": {
      "uuid": "offer-4aa3d888",
      "status": "declined",
      "product_type": "payday_loan",
      "description": "We cannot offer you a loan at this time."
    }
  }'
```

***

#### Check Debt Obligation Status

Get the processing status of a submitted debt obligation.

```
GET /api/debt/status/:guid
Authorization: Bearer <accessToken>
```

| Parameter | Type   | Description                                  |
| --------- | ------ | -------------------------------------------- |
| `guid`    | string | The unique identifier of the debt obligation |

**Response:**

```json
{
  "obligation": {
    "_id": "507f1f77bcf86cd799439011",
    "guid": "0123456789ABCDEF0123456789ABCDEF",
    "clientNo": "00000000123456",
    "processingStatus": "callback_sent",
    "replyCd": "207",
    "replyStr": "Successful",
    "callbackSentAt": "2026-02-24T10:00:01.000Z",
    "createdAt": "2026-02-24T10:00:00.000Z"
  }
}
```

See [Debt Processing Statuses](#debt-processing-statuses) for all possible values.

An obligation sent without bank fields comes back without `accountType`, `bankAccNo` and `bankBranchCd`, both here and in the [ingest](#ingest-debt-obligation) response.

**Errors:**

| Code | Type                   | Description                               |
| ---- | ---------------------- | ----------------------------------------- |
| 401  | `INVALID_TOKEN`        | Missing or invalid authentication token   |
| 404  | `OBLIGATION_NOT_FOUND` | No obligation found with the given `guid` |

**Example:**

```bash
curl -X GET "https://ingest.spendl.money/api/debt/status/0123456789ABCDEF0123456789ABCDEF" \
  -H "Authorization: Bearer $TOKEN"
```

***

#### List Debt Audit Logs

Get paginated audit logs for debt ingestion, callbacks, and retries. You can filter results by obligation `guid`.

```
GET /api/debt/audit-logs
Authorization: Bearer <accessToken>
```

| Parameter  | Type   | Description                            |
| ---------- | ------ | -------------------------------------- |
| `page`     | number | Page number (default: 1, min: 1)       |
| `pageSize` | number | Items per page (default: 25, max: 100) |
| `guid`     | string | Filter by obligation guid              |

**Response:**

```json
{
  "items": [
    {
      "_id": "507f1f77bcf86cd799439099",
      "action": "debt_ingest",
      "timestamp": "2026-06-04T10:00:00.000Z",
      "recordData": { "guid": "0123456789ABCDEF0123456789ABCDEF" }
    }
  ],
  "total": 42,
  "page": 1,
  "pageSize": 25
}
```

**Errors:**

| Code | Type            | Description                             |
| ---- | --------------- | --------------------------------------- |
| 401  | `INVALID_TOKEN` | Missing or invalid authentication token |

**Example:**

```bash
curl -X GET "https://ingest.spendl.money/api/debt/audit-logs?page=1&pageSize=10&guid=0123456789ABCDEF0123456789ABCDEF" \
  -H "Authorization: Bearer $TOKEN"
```

***

### Wallet Operations

Use these endpoints to check balances, make payments, transfer funds, and manage bank beneficiaries. All amounts use **ZAR cents**. Send positive integers.

Every wallet mutation that moves money (deposit, transfer, load-card, purchase-voucher, repay-debt, send-to-bank) requires an [idempotency key](#idempotency), sent as `idempotencyKey` in the body or as the `X-Idempotency-Key` header. A missing key returns `422 MISSING_IDEMPOTENCY_KEY` before any money moves. Reuse the same key when you retry a failed request.

Each user ID must belong to the tenant in the access token. For a user ID that is not one of your users, the Public API refuses the request before any money moves. The answer depends on the route:

| Routes                                                                                                                                                                                                                                                                                | Answer                                                                                                                   |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| The routes in this section that take a user ID, including [Load Card](#load-card) and [Send to Bank](#send-to-bank-eft)                                                                                                                                                               | `404 USER_NOT_FOUND`                                                                                                     |
| [Pay@](#pay-integration) and [Zapper](#zapper-integration) deposits and withdrawals, the Pay@ reads that take a `userId`, [`POST /api/vouchers/perform`](#perform-payout), [`GET /api/vouchers/status`](#get-payout-status) and [hosted checkout deposits](#hosted-checkout-deposits) | `403 FORBIDDEN` (a Pay@ withdrawal returns `403 PAYAT_PAYOUT_NOT_ENABLED` while it is [not available](#pay-integration)) |

On those routes in this section, the user is checked before the idempotency key. A request with an unknown user and no key returns `404 USER_NOT_FOUND`, not `422 MISSING_IDEMPOTENCY_KEY`.

You can set `feeAmount` on direct deposits, direct transfers, voucher purchases, debt repayments, Pay@ deposits, and Zapper deposits. Write-scoped keys can call all of these except [direct deposits](#deposit-funds), which also need the `deposit` scope. The API stores partner metadata under `metadata.partner`. This metadata cannot override trusted ledger metadata.

On these six routes, `feeAmount` is optional. Use one of these formats:

* A nonnegative integer JSON number in cents. For example, `250` means R2.50.
* A decimal JSON string in ZAR. It must have one or two fraction digits and a decimal point. Valid examples are `"2.5"`, `"2.50"`, and `"2.00"`.

Integer-only strings such as `"250"` are invalid. Fractional JSON numbers such as `2.5` are invalid. Negative values, scientific notation, and values with more than two decimal places are also invalid. An invalid string returns `422 INVALID_FEE_AMOUNT`; an invalid JSON number returns `422 VALIDATION_ERROR`. `null` is treated as no fee. Send `feeAmount` in the JSON body: a `feeAmount` query parameter is not converted and is refused with `422 VALIDATION_ERROR`. The Public API converts accepted values to integer cents. Responses and transaction metadata also use integer cents.

Spendl stores the authoritative fee fields in each transaction's metadata. Direct deposits and transfers store `amount`, `feeAmount`, and `netAmount`. Voucher purchases and debt repayments store `amount`, `feeAmount`, and `grossAmount`. Pay@ and Zapper deposits also separate the tenant's `requestedFeeAmount` from the provider fee and the total `feeAmount`. Transaction history returns these fields unchanged. Metadata that you supply cannot override them.

***

#### Get Balance

```
GET /api/wallet/balance/:userId
Authorization: Bearer <accessToken>
```

| Parameter | Type   | Description      |
| --------- | ------ | ---------------- |
| `userId`  | string | The user's `_id` |

**Response:**

```json
{
  "balance": -50000
}
```

> **Note:** These balances are for liability accounts. Negative values show funds available to the user. A balance of `-50000` means R500.00 is available.

**Errors:**

| Code | Type                          | Description                               |
| ---- | ----------------------------- | ----------------------------------------- |
| 401  | `INVALID_TOKEN`               | Missing or invalid authentication token   |
| 502  | `WALLET_BALANCE_FETCH_FAILED` | The balance could not be retrieved. Retry |

***

#### Get Treasury Deposit Reference

Get a user's unique treasury deposit reference. The user puts this reference on an EFT deposit so that Spendl can match the deposit to the user.

The reference is stored as `<PREFIX>-<8_DIGITS>` but returned here without the hyphen (`ACM00000001`), because bank reference fields routinely strip or reject punctuation and a depositor should type exactly what they were shown. Spendl reconciles either spelling, so a deposit made with the hyphenated form still allocates.

```
GET /api/wallet/:userId/depositRef
Authorization: Bearer <accessToken>
```

| Parameter | Type   | Description      |
| --------- | ------ | ---------------- |
| `userId`  | string | The user's `_id` |

The endpoint resolves the tenant user by `userId` — the same `_id` returned at ingestion. An unknown or cross-tenant `userId` returns `404 USER_NOT_FOUND`.

**Response:**

```json
{
  "userId": "507f1f77bcf86cd799439011",
  "depositRef": "ACM00000001"
}
```

**Errors:**

| Code | Type                           | Description                                                          |
| ---- | ------------------------------ | -------------------------------------------------------------------- |
| 401  | `INVALID_TOKEN`                | Missing or invalid authentication token                              |
| 404  | `USER_NOT_FOUND`               | `userId` is not one of your users                                    |
| 404  | `TREASURY_DEPOSIT_REF_NOT_SET` | The user exists but has no deposit reference                         |
| 422  | `VALIDATION_ERROR`             | `userId` is not a valid Spendl ID (`_id`, 24 hexadecimal characters) |

***

#### Create Tenant Wallet

Creates a KYC-approved `tenant_wallet` user for your tenant. The user is active and KYC Approved, compliance is cleared, and the user has no password and no cards. Emails are off. App login stays blocked.

Your key needs the [`tenant_wallet` scope](#scopes) as well as `write`. Spendl grants it on request. The API takes the tenant from the JWT label. Do not send a `tenantKey` in the body.

The treasury deposit reference is the tenant's configured 3-letter `treasuryPrefix` plus 8 digits, for example `ACM00000001` for a tenant with the prefix `ACM`, as returned in the `depositRef` field below. Show it to customers exactly as returned. Spendl matches an EFT reference with or without a hyphen after the prefix (`ACM-00000001`) and in any letter case, but not with spaces inside it. Creation fails if the tenant has no valid 3-letter prefix.

```
POST /api/wallet/tenant-wallets
Authorization: Bearer <accessToken>
Content-Type: application/json
```

```json
{
  "email": "wallet@example.com"
}
```

| Field   | Type   | Required | Description                              |
| ------- | ------ | -------- | ---------------------------------------- |
| `email` | string | Yes      | Email assigned to the tenant wallet user |

**Response** (`201`):

```json
{
  "wallet": {
    "_id": "507f1f77bcf86cd799439011",
    "email": "wallet@example.com",
    "accountType": "tenant_wallet",
    "status": "active",
    "kycStatus": "Approved",
    "depositRef": "ACM00000001",
    "balanceZar": 0,
    "createdAt": "2026-09-02T10:00:00.000Z",
    "updatedAt": "2026-09-02T10:00:00.000Z"
  }
}
```

**Errors:**

| Code | Type                       | Description                                                                                                                                                                                            |
| ---- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 400  | `INVALID_EMAIL`            | Email is missing or not a valid address                                                                                                                                                                |
| 401  | `INVALID_TOKEN`            | Missing or invalid authentication token                                                                                                                                                                |
| 403  | `INSUFFICIENT_SCOPE`       | The key lacks a scope this request needs, and no wallet is created. `data.requiredScope` is `write` or `tenant_wallet`. For `tenant_wallet`, ask your Spendl account manager, then request a new token |
| 409  | `DUPLICATE_EMAIL`          | This email cannot be used for a new user                                                                                                                                                               |
| 422  | `TENANT_LABEL_REQUIRED`    | JWT tenant label is missing                                                                                                                                                                            |
| 422  | `TENANT_CONFIG_NOT_FOUND`  | No tenant config exists for the JWT tenant                                                                                                                                                             |
| 422  | `TENANT_NOT_ACTIVE`        | Tenant exists but is not `active`                                                                                                                                                                      |
| 422  | `TREASURY_PREFIX_REQUIRED` | Tenant has no valid 3-letter `treasuryPrefix`                                                                                                                                                          |

***

#### Disburse from tenant wallet

Send funds from a tenant wallet to several recipients in one call. An existing tenant user receives an instant wallet transfer with no fee. An unknown email address starts an escrowed transfer and a signup invite. This is the same flow as sending to a new email in the app. Your key needs the [`tenant_wallet` scope](#scopes) as well as `write`. Spendl grants it on request.

```
POST /api/wallet/disburse
Authorization: Bearer <accessToken>
Content-Type: application/json
```

**Request body:**

```json
{
  "senderUserId": "507f1f77bcf86cd799439011",
  "kind": "salary",
  "description": "Salary disbursement",
  "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
  "recipients": [
    { "email": "existing@example.com", "amount": 100000 },
    { "email": "new@example.com", "amount": 50000 }
  ]
}
```

| Field                 | Type    | Required | Description                                                                                                                                                                                                   |
| --------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `senderUserId`        | string  | Yes      | The tenant wallet user `_id`                                                                                                                                                                                  |
| `kind`                | string  | Yes      | `salary` or `batch` (used for metadata/defaults)                                                                                                                                                              |
| `description`         | string  | No       | Description attached to each transfer                                                                                                                                                                         |
| `idempotencyKey`      | string  | Yes      | Durable key for the whole operation (1–200 characters). May be sent as the `X-Idempotency-Key` header instead; both must match when both are sent. The key for each recipient is `${idempotencyKey}:${email}` |
| `recipients`          | array   | Yes      | One or more recipients                                                                                                                                                                                        |
| `recipients[].email`  | email   | Yes      | Recipient email                                                                                                                                                                                               |
| `recipients[].amount` | integer | Yes      | Amount in ZAR cents                                                                                                                                                                                           |

**Response** (`200`):

```json
{
  "success": true,
  "totalAmount": 150000,
  "paidCount": 1,
  "invitedCount": 1,
  "failedCount": 0,
  "results": [
    { "email": "existing@example.com", "amount": 100000, "status": "posted", "journalEntryId": "..." },
    { "email": "new@example.com", "amount": 50000, "status": "escrowed", "journalEntryId": "...", "expiresAt": "2026-09-05T00:00:00Z" }
  ]
}
```

A same-key retry of a disbursement that Spendl had already recorded adds `"idempotentReplay": true` at the top level. It does not mean anyone was paid: read each recipient's `status`. See [Disburse retries](#disburse-retries) below.

Errors:

| Code | Type                                                                              | Description                                                                                                                                                                                                                                                                                 |
| ---- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400  | `INSUFFICIENT_FUNDS`                                                              | Soft pre-check: the total exceeds the available liability balance (`balance < 0` means funded). Nobody is paid, and a retry with the same key checks the balance again                                                                                                                      |
| 400  | `INVALID_SOURCE`                                                                  | The sender is not a `tenant_wallet`                                                                                                                                                                                                                                                         |
| 400  | `DUPLICATE_EMAIL`                                                                 | The same email appears more than once                                                                                                                                                                                                                                                       |
| 400  | `INVALID_AMOUNT`                                                                  | An amount, or the total of all amounts, is larger than 9007199254740991 cents. Nobody is paid                                                                                                                                                                                               |
| 401  | `NO_AUTH_HEADER` / `INVALID_AUTH_FORMAT` / `INVALID_TOKEN` / `NO_TENANT_ON_TOKEN` | Missing or invalid authentication                                                                                                                                                                                                                                                           |
| 403  | `INSUFFICIENT_SCOPE`                                                              | The key lacks a scope this disbursement needs, and nothing is paid. `data.requiredScope` is `write` or `tenant_wallet`. For `tenant_wallet`, ask your Spendl account manager, then request a new token                                                                                      |
| 409  | `IDEMPOTENCY_KEY_MISMATCH`                                                        | The key was already used for a disbursement with a different `senderUserId`, recipients or amounts. Nobody is paid. Use a new key for a new disbursement                                                                                                                                    |
| 422  | `WALLET_SUSPENDED`                                                                | The sender wallet is not active                                                                                                                                                                                                                                                             |
| 422  | `MISSING_IDEMPOTENCY_KEY`                                                         | No key in `idempotencyKey` or `X-Idempotency-Key`                                                                                                                                                                                                                                           |
| 422  | `IDEMPOTENCY_KEY_MISMATCH`                                                        | The body and header keys differ                                                                                                                                                                                                                                                             |
| 422  | `VALIDATION_ERROR`                                                                | The body is malformed: an invalid or missing email, a non-integer amount, a key longer than 200 characters, or empty `recipients`                                                                                                                                                           |
| 502  | `UPSTREAM_NETWORK_ERROR`                                                          | The initial balance check could not be completed, and this attempt pays nobody. After that check, a failure for a single recipient does not return `502`. It appears in the `200` response as a `results` item with `status: "failed"` and is counted in `failedCount`.                     |
| 503  | `INTERNAL_ERROR`                                                                  | Spendl could not record the disbursement. This attempt started no new payments, but an earlier or concurrent attempt with the same key may have paid recipients. Retry with the same idempotency key and payload: recipients already paid are reported with their original `journalEntryId` |

Self-transfer and wallet-to-wallet attempts do not return a top-level 400 error. They appear in the `200` response as per-recipient items with `status: "failed"`. Spendl does not reserve funds for the whole batch. The balance check rejects the whole request before any payment when the total exceeds the available funds. However, wallet activity after the check can still make some payments in the batch fail.

**Disburse retries**

After a timeout, a lost response or a `5xx`, retry with the same `idempotencyKey`. A same-key retry completes the remaining recipients; already-paid recipients return their original `journalEntryId`. Each payment uses its own key, `${idempotencyKey}:${email}`:

* A recipient already paid is reported as `posted` (or `escrowed`) with the original `journalEntryId`, and is not paid again. A recipient paid as `escrowed` who has since signed up comes back `posted`.
* A recipient not paid yet is paid as usual. A recipient whose payment fails is reported as its own `failed` item.
* A recipient reported `failed` after a timeout or a `5xx` may still have been paid. To retry failed recipients, resend the whole batch with the same key: anyone already paid comes back `posted` (or `escrowed`). Never resend a failed recipient under a new key without checking [Transaction History](#transaction-history).
* Spendl records the disbursement just before its first payment. A retry after that skips the whole-batch balance check, because the balance may already have fallen by what was paid, and has `idempotentReplay: true`, which does not mean anyone was paid.
* If the first attempt returned `400 INSUFFICIENT_FUNDS`, nobody was paid. A retry with the same key checks the balance again, so it pays once the wallet is funded.

The key belongs to one disbursement. A retry must send the same `senderUserId` and the same recipients and amounts, in any order. A different sender, recipient list or amount returns `409 IDEMPOTENCY_KEY_MISMATCH`, and nobody is paid. A `4xx` on a retry does not undo an earlier attempt: recipients already paid stay paid, so check [Transaction History](#transaction-history) before you send again. Two requests sent at the same time with the same key never pay a recipient twice. Use a new `idempotencyKey` for every new disbursement, for example each month's salary run.

***

#### Transaction History

```
GET /api/wallet/history/:userId
Authorization: Bearer <accessToken>
```

| Parameter  | Location | Type    | Required | Description                                                                                                                             |
| ---------- | -------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `userId`   | path     | string  | Yes      | The user's `_id`                                                                                                                        |
| `page`     | query    | integer | No       | Page number (default: 1)                                                                                                                |
| `pageSize` | query    | integer | No       | Results per page (default: 50)                                                                                                          |
| `type`     | query    | string  | No       | Filter by transaction type: one of the [history types](#history-types). Any other value returns no items, and an empty value is ignored |

**Response:**

```json
{
  "items": [
    {
      "_id": "6641...",
      "type": "deposit",
      "status": "posted",
      "displayStatus": "posted",
      "description": "Deposit of 500.00 ZAR",
      "entries": [
        { "accountCode": "1000", "amount": 50000 },
        { "accountCode": "2000-507f1f77bcf86cd799439011", "amount": -49750 },
        { "accountCode": "4010", "amount": -250 }
      ],
      "metadata": {
        "amount": 50000,
        "feeAmount": 250,
        "netAmount": 49750
      },
      "postedAt": "2026-04-01T10:00:00.000Z",
      "createdAt": "2026-04-01T10:00:00.000Z"
    }
  ],
  "page": 1,
  "pageSize": 50,
  "total": 1
}
```

For deposits and transfers where the amount is gross-inclusive, `metadata.netAmount` is the amount credited after fees. For voucher purchases and debt repayments, `metadata.grossAmount` is the total wallet debit (`amount + feeAmount`). Pay@ and Zapper metadata also contains `requestedFeeAmount`, `providerFeeAmount`, and the total `feeAmount`. In `entries`, Spendl's provider tariff and payment processing costs are reported under `4000` and `5000`, and the fee you set under `4010`, as the [Journal Conventions](#journal-conventions) describe. Spendl removes its internal metadata from `metadata`.

In a [tenant wallet](#create-tenant-wallet)'s history, a `tenant_fee_payout` has the description `Tenant fee payout`, and `metadata.tenantFeePayout.statement` explains the amount paid: your `4010` movements since the previous payout. Its amounts are integer ZAR cents, a fee positive and a refund of one negative:

* `balanceCents`: the `4010` balance paid out (equals `metadata.amount`)
* `totalCents`: the sum of `byProduct[].cents` and `payoutReversalsCents`
* `reconciled`: `true` when `totalCents` equals `balanceCents`, which is always the case on a payout
* `from`: when the previous payout was posted (ISO 8601), or `null` for the first payout
* `to`: when the statement was drawn up (ISO 8601)
* `lastPayout`: the previous payout (`journalId`, `postedAt`, `amountCents`, `tenantWalletUserId`), or `null`
* `byProduct`: one row per product with a movement in the period: `product` (`remittance`, `deposits_in`, `payments_out`, `itt_transfers`, `card_loads`, or `other`), `cents` (fees less refunds) and `count` (entries)
* `payoutReversalsCents`: what reversed earlier payouts put back in `4010`; `0` when there are none
* `lastMovementJournalId`: the newest entry in the period, or `null`

In a tenant wallet's history, a `debt_installment_settlement` has the description `Loan repayments received`, and `metadata.amount` is the amount paid in. Spendl pays repayments in on weekdays when there are any, usually as a single entry, and the entry does not list the loans.

A `card_load` has a description such as `Card load of R40.00`: the amount loaded onto the card, without the fee or the payment method. Those are in `metadata.feeAmount` and `metadata.paymentMethod`. Older card loads can show an earlier description that also named the fee or the payment method.

`displayStatus` equals `status`, except that a `posted` card load or send-to-bank payment (`card_load`, `fiat_withdrawal`) that the payment partner has not confirmed yet shows `pending`; a refunded one shows `reversed` in both.

Each item's `_id` is its journal entry ID, the `journalEntryId` the wallet mutations return. To read one entry by that ID, use [Get Journal Entry](#get-journal-entry).

**Errors:**

| Code | Type                          | Description                               |
| ---- | ----------------------------- | ----------------------------------------- |
| 401  | `INVALID_TOKEN`               | Missing or invalid authentication token   |
| 502  | `WALLET_HISTORY_FETCH_FAILED` | The history could not be retrieved. Retry |

**History Types**

`type` is the ledger entry's own type, as Spendl stores it. A user's history can show these:

| `type`                        | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `deposit`                     | Money into the wallet: a [deposit](#deposit-funds) from one of your tenant wallets or from the suspense account, a reward Spendl pays (description starting `Reward payout`), or a bank payment to the user's deposit reference. In the history of the tenant wallet that funded a deposit, the same entry is money out, and `metadata.sourceWallet` names that wallet                                                                           |
| `payat_deposit`               | A [Pay@](#pay-integration) deposit                                                                                                                                                                                                                                                                                                                                                                                                               |
| `zapper_deposit`              | A [Zapper](#zapper-integration) deposit                                                                                                                                                                                                                                                                                                                                                                                                          |
| `moment_deposit`              | A [hosted checkout deposit](#hosted-checkout-deposits)                                                                                                                                                                                                                                                                                                                                                                                           |
| `voucher_redemption`          | A voucher redeemed into the wallet                                                                                                                                                                                                                                                                                                                                                                                                               |
| `transfer`                    | A wallet-to-wallet [transfer](#transfer-funds) or [disbursement](#disburse-from-tenant-wallet), a move between the user's main balance and a sub-account, or a held transfer paid out to its recipient                                                                                                                                                                                                                                           |
| `transfer_escrow`             | A transfer to an email with no account yet, held until the recipient signs up                                                                                                                                                                                                                                                                                                                                                                    |
| `fiat_withdrawal`             | A [send-to-bank](#send-to-bank-eft) payment                                                                                                                                                                                                                                                                                                                                                                                                      |
| `card_load`                   | A [card load](#load-card)                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `debt_repayment`              | A [debt repayment](#repay-debt)                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `debt_installment`            | A debt installment paid from the wallet: paid early by the user, or collected automatically when money reaches the user's main balance, such as a deposit, a Pay@ payment, a transfer from another user (including a disbursement from your tenant wallet) or a refund posted as its own entry, for example a Zapper refund. A `reversal`, such as a refunded send-to-bank payment, and a move between the user's own accounts do not trigger it |
| `voucher_purchase`            | A voucher bought with the deprecated [Purchase Voucher](#purchase-voucher-deprecated)                                                                                                                                                                                                                                                                                                                                                            |
| `ott_payout`                  | A voucher payout from [`POST /api/vouchers/perform`](#perform-payout)                                                                                                                                                                                                                                                                                                                                                                            |
| `zapper_payment`              | A [Zapper withdrawal](#zapper-withdrawal-flow-scan-to-pay) (scan-to-pay)                                                                                                                                                                                                                                                                                                                                                                         |
| `zapper_refund`               | A refund of a Zapper withdrawal                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `payat_payout_auth`           | A [Pay@ withdrawal](#pay-withdrawal-flow): the debit when the till authorises the PIN                                                                                                                                                                                                                                                                                                                                                            |
| `payat_payout_void`           | A refund of a Pay@ withdrawal the till voided                                                                                                                                                                                                                                                                                                                                                                                                    |
| `remittance_submit`           | A [remittance send](#initiate-send): the full debit. If the exchange cannot be booked when the send is made, a `reversal` undoes it and this entry shows `status: "reversed"`                                                                                                                                                                                                                                                                    |
| `remittance_manual_refund`    | A remittance refund posted separately (principal and fee). The `remittance_submit` entry stays `posted`                                                                                                                                                                                                                                                                                                                                          |
| `remittance_refund`           | An earlier form of remittance refund. Appears only in older history                                                                                                                                                                                                                                                                                                                                                                              |
| `reversal`                    | Undoes an earlier entry, such as a refunded send or an unclaimed held transfer                                                                                                                                                                                                                                                                                                                                                                   |
| `reconciliation_adjustment`   | A correction by Spendl, such as a refunded fee. Rare                                                                                                                                                                                                                                                                                                                                                                                             |
| `tenant_fee_payout`           | Your fee share paid into a [tenant wallet](#create-tenant-wallet). Only in a tenant wallet's history                                                                                                                                                                                                                                                                                                                                             |
| `debt_installment_settlement` | Loan repayments collected from your users, paid into a [tenant wallet](#create-tenant-wallet). Only in a tenant wallet's history                                                                                                                                                                                                                                                                                                                 |

History lists entries on the user's main balance. Activity on a sub-account appears only when it moves money to or from the main balance.

`status` is `posted`, `reversed` (undone by a later `reversal` entry, which is also in the history), or `pending` while the entry is being posted. Entries that fail to post are not returned.

A `reversal` row has no field that links it to the entry it undoes. Some reversals mark the original `status: "reversed"`, such as the refund of a send-to-bank payment. For those, read either entry with [Get Journal Entry](#get-journal-entry): the original's `reversedBy` is the reversal's ID, and the reversal's `reversalOf` is the original's. Other reversals, such as the refund of an unclaimed held transfer or a Pay@ reversal, leave the original `posted` and both fields `null`. For a refunded send-to-bank payment, [`wallet.send_to_bank_failed`](#walletsend_to_bank_failed) also carries the payment's `journalEntryId`.

Other ledger entry types do not appear in a user's history. Of the types above, two are named differently in the [Journal API](#journal-conventions): `moment_deposit` is `checkout_deposit` there, and `ott_payout` is `voucher_payout`. Filter history with the names above. Spendl can add types without a version change, so handle an unrecognised value gracefully.

***

#### Deposit Funds

Credit a user's wallet from one of your tenant wallets. `sourceWallet` is required unless `fromSuspense` is `true`. Your key needs the [`deposit` scope](#scopes) as well as `write`. Spendl grants it on request. Funding the deposit from the suspense account (`fromSuspense: true`) needs the `admin` scope.

```
POST /api/wallet/deposit
Authorization: Bearer <accessToken>
Content-Type: application/json
```

Deposit funded from a tenant wallet:

```json
{
  "userId": "507f1f77bcf86cd799439011",
  "sourceWallet": "507f1f77bcf86cd799439021",
  "amount": 10000,
  "feeAmount": 250,
  "metadata": {}
}
```

Deposit funded from the suspense account (admin scope, no `sourceWallet`):

```json
{
  "userId": "507f1f77bcf86cd799439011",
  "fromSuspense": true,
  "amount": 10000,
  "feeAmount": 250,
  "metadata": {}
}
```

| Field            | Type                      | Required                             | Description                                                                                                                                                                               |
| ---------------- | ------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `userId`         | string                    | Yes                                  | The user's `_id`                                                                                                                                                                          |
| `sourceWallet`   | string                    | Yes, unless `fromSuspense` is `true` | The `_id` of one of your active [tenant wallets](#create-tenant-wallet), other than `userId`. It funds the deposit and must hold at least `amount`. Not allowed with `fromSuspense: true` |
| `amount`         | integer                   | Yes                                  | Gross inclusive amount in ZAR cents (positive)                                                                                                                                            |
| `idempotencyKey` | string                    | Yes\*                                | Durable key for safe retries. \*Send it here or as the `X-Idempotency-Key` header; both must match when both are sent. See [Idempotency](#idempotency)                                    |
| `feeAmount`      | integer or decimal string | No                                   | Requested fee. See the fee format rules above.                                                                                                                                            |
| `fromSuspense`   | boolean                   | No                                   | `true` funds the deposit from the suspense account instead of a tenant wallet, and needs the `admin` scope. Do not send `sourceWallet` with it. Default `false`                           |
| `metadata`       | object                    | No                                   | Partner metadata, stored under `metadata.partner`                                                                                                                                         |

**Response:**

```json
{
  "success": true,
  "journalEntryId": "6641...",
  "userId": "507f1f77bcf86cd799439011",
  "sourceWallet": "507f1f77bcf86cd799439021",
  "amount": 10000,
  "feeAmount": 250,
  "netAmount": 9750,
  "status": "posted"
}
```

`sourceWallet` is returned, in lowercase, when the deposit named one. `amount` is gross and inclusive. In this example, the tenant wallet is debited exactly 10000 cents. The wallet receives 9750 cents. Tenant fee revenue account `4010` receives 250 cents (see [Journal Conventions](#journal-conventions)). The fee must leave a positive net amount.

A deposit funded from a tenant wallet moves money that is already inside Spendl, so it does not send [`wallet.incoming_credit`](#walletincoming_credit). It sends [`wallet.deposit_completed`](#walletdeposit_completed), which includes `sourceWallet`.

**Errors:**

| Code | Type                                                                                                                                                             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401  | `INVALID_TOKEN`                                                                                                                                                  | Missing or invalid authentication token                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| 403  | `INSUFFICIENT_SCOPE`                                                                                                                                             | The key lacks a scope this deposit needs, and nothing is credited. `data.requiredScope` is `write`, `deposit`, or `admin` (for `fromSuspense: true`). For `deposit`, ask your Spendl account manager, then request a new token                                                                                                                                                                                                                                                                                                                                                                                            |
| 403  | `SOURCE_WALLET_FORBIDDEN`                                                                                                                                        | `sourceWallet` is not usable for this deposit, and nothing is credited. `data.reason` is `not_tenant_wallet` (the account is not a tenant wallet) or `not_active` (the tenant wallet is not active)                                                                                                                                                                                                                                                                                                                                                                                                                       |
| 404  | `SOURCE_WALLET_NOT_FOUND`                                                                                                                                        | `sourceWallet` does not match any tenant wallet of yours                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| 409  | `DUPLICATE_IDEMPOTENCY_KEY`                                                                                                                                      | This key was already used for a deposit (`data.existingEntryId` is its journal entry). With `data.result`, it holds that deposit's outcome, including `sourceWallet` when the deposit named one: act on its `status` (see [Idempotency](#idempotency): `posted` is processed; `pending` is still running, so retry later with the same key; `reversed` was later reversed, so check before trying again; `failed` moved nothing). Without `data.result`, the key was first used in another request: check the transaction history. Never retry with a new key until the outcome is known. See [Idempotency](#idempotency) |
| 409  | `IDEMPOTENCY_KEY_MISMATCH`                                                                                                                                       | This key was already used for a deposit with a different `amount` or `sourceWallet`, or with a `sourceWallet` when the first request had none (or the reverse). Nothing is credited. Use a new key for a new deposit                                                                                                                                                                                                                                                                                                                                                                                                      |
| 422  | `SOURCE_WALLET_REQUIRED`                                                                                                                                         | The request has no `sourceWallet` and `fromSuspense` is not `true`, and nothing is credited                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| 422  | `FROMSUSPENSE_AND_SOURCEWALLET_CONFLICT`                                                                                                                         | `fromSuspense: true` and `sourceWallet` were both sent. Send one of them                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| 422  | `SOURCE_WALLET_SAME_AS_USER`                                                                                                                                     | `sourceWallet` is the wallet of `userId`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| 422  | `SOURCE_WALLET_BALANCE_SHORT`                                                                                                                                    | The tenant wallet holds less than `amount`, and nothing is credited. `data.available` and `data.requested` are in cents                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| 422  | `INVALID_FEE_AMOUNT`                                                                                                                                             | `feeAmount` does not use an accepted format                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| 422  | `FEE_EXCEEDS_AMOUNT`                                                                                                                                             | The fee leaves no positive net amount                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| 422  | `SUSPENSE_BALANCE_SHORT`                                                                                                                                         | With `fromSuspense: true`, the suspense account holds less than `amount`, and nothing is credited. `data.available` and `data.requested` are in cents                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| 422  | `VALIDATION_ERROR`                                                                                                                                               | Invalid fields or amount, including a `sourceWallet` that is not a 24-character hexadecimal `_id`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| 5xx  | `WALLET_DEPOSIT_FAILED`                                                                                                                                          | The outcome is unknown: the deposit may have moved. Retry with the same key, which never moves money twice                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| 5xx  | Any other `5xx` (for example `INTERNAL_ERROR`, `REQUEST_TIMEOUT` or `UPSTREAM_NETWORK_ERROR`), a plain-text `503` or `504` from the network edge, or no response | The outcome is unknown: retry with the same key, which never moves money twice                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |

If a deposit timed out and you are unsure whether it posted, look it up in [Transaction History](#transaction-history) instead of sending it again under a new key.

***

#### Transfer Funds

Transfer between two user wallets.

```
POST /api/wallet/transfer
Authorization: Bearer <accessToken>
Content-Type: application/json
```

```json
{
  "senderUserId": "507f...",
  "receiverUserId": "508a...",
  "amount": 10000,
  "feeAmount": "2.50",
  "description": "Rent payment"
}
```

| Field            | Type                      | Required | Description                                                                                                                                            |
| ---------------- | ------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `senderUserId`   | string                    | Yes      | Sender's `_id`                                                                                                                                         |
| `receiverUserId` | string                    | Yes      | Receiver's `_id`                                                                                                                                       |
| `amount`         | integer                   | Yes      | Gross inclusive amount in ZAR cents (positive)                                                                                                         |
| `idempotencyKey` | string                    | Yes\*    | Durable key for safe retries. \*Send it here or as the `X-Idempotency-Key` header; both must match when both are sent. See [Idempotency](#idempotency) |
| `feeAmount`      | integer or decimal string | No       | Requested fee. `"2.50"` becomes 250 cents.                                                                                                             |
| `description`    | string                    | No       | Transfer description                                                                                                                                   |
| `metadata`       | object                    | No       | Partner metadata, stored under `metadata.partner`                                                                                                      |

**Response:**

```json
{
  "success": true,
  "journalEntryId": "6641...",
  "senderUserId": "507f...",
  "receiverUserId": "508a...",
  "amount": 10000,
  "feeAmount": 250,
  "netAmount": 9750,
  "status": "posted"
}
```

The sender moves exactly 10000 cents. The receiver gets 9750 cents. Tenant fee revenue account `4010` gets 250 cents.

**Errors:**

| Code | Type                                                                                                                                                             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401  | `INVALID_TOKEN`                                                                                                                                                  | Missing or invalid authentication token                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| 403  | `ACCOUNT_RESTRICTED`                                                                                                                                             | The sender's account is restricted from sending money                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| 409  | `DUPLICATE_IDEMPOTENCY_KEY`                                                                                                                                      | This key was already used for a transfer (`data.existingEntryId` is its journal entry). With `data.result`, it holds that transfer's outcome: act on its `status` (see [Idempotency](#idempotency): `posted` is processed; `pending` is still running, so retry later with the same key; `reversed` was later reversed, so check before trying again; `failed` moved nothing). Without `data.result`, the key was first used in another request: check the transaction history. Never retry with a new key until the outcome is known. See [Idempotency](#idempotency) |
| 422  | `INVALID_FEE_AMOUNT`                                                                                                                                             | `feeAmount` does not use an accepted format                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 422  | `FEE_EXCEEDS_AMOUNT`                                                                                                                                             | The fee leaves no positive net amount                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| 422  | `INSUFFICIENT_FUNDS`                                                                                                                                             | Sender does not have enough funds                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| 5xx  | `WALLET_TRANSFER_FAILED`                                                                                                                                         | The outcome is unknown: the transfer may have moved. Retry with the same key; see [Error Outcomes](#error-outcomes)                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| 5xx  | Any other `5xx` (for example `INTERNAL_ERROR`, `REQUEST_TIMEOUT` or `UPSTREAM_NETWORK_ERROR`), a plain-text `503` or `504` from the network edge, or no response | The outcome is unknown: retry with the same key, which never moves money twice                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

***

#### Load Card

Load a card from the user's wallet. Spendl loads cards one of two ways, set per environment, and the response's `channel` says which was used:

* `eft`: an EFT into the card's funding account. The API calculates the fee from the selected withdrawal option, and the card is credited when the payment clears (`cardCredited: false`).
* `fund_card`: an instant credit to the card. The fee is a flat amount whatever the withdrawal option, and a `200` means the card has been credited (`cardCredited: true`). The card provider also charges the card a small fee to receive the load; [Participating Banks](#reference-data) returns both fees in `cardLoad`.

On `fund_card` the request waits for the card provider, so it can take up to about 50 seconds. Set your HTTP client's timeout for this request to at least 65 seconds. The response's `channel` is the channel that was used: `cardLoad` from [Participating Banks](#reference-data) is cached for up to 5 minutes by default, so it can lag a channel switch.

> **Requires a card account:** Only users with a `Smart`, `Savvy`, or `Guru` product can use this endpoint. Wallet-only users must [upgrade](#account-types) before loading a card.

```
POST /api/wallet/load-card
Authorization: Bearer <accessToken>
Content-Type: application/json
```

```json
{
  "userId": "507f...",
  "amount": 25000,
  "cardId": "1000001",
  "withdrawalOption": "IMMEDIATE"
}
```

| Field              | Type    | Required | Description                                                                                                                                            |
| ------------------ | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `userId`           | string  | Yes      | The user's `_id`                                                                                                                                       |
| `amount`           | integer | Yes      | Amount in ZAR cents (positive)                                                                                                                         |
| `cardId`           | string  | Yes      | Opaque card identifier. It must be one of the user's own cards. See `GET /api/cards/:userId`.                                                          |
| `idempotencyKey`   | string  | Yes\*    | Durable key for safe retries. \*Send it here or as the `X-Idempotency-Key` header; both must match when both are sent. See [Idempotency](#idempotency) |
| `cardReference`    | string  | No       | Deprecated card reference. If you supply it, it must also be one of the user's own cards.                                                              |
| `withdrawalOption` | string  | No       | `"IMMEDIATE"` (PayShap or RTC — faster, higher fee) or `"ONE_DAY"` (same-day batch — lower fee). Ignored on the `fund_card` channel                    |
| `metadata`         | object  | No       | Partner metadata, retained under `metadata.partner`                                                                                                    |

**Response:**

```json
{
  "success": true,
  "journalEntryId": "6641...",
  "userId": "507f...",
  "amount": 25000,
  "feeAmount": 500,
  "grossDebit": 25500,
  "paymentMethod": "PAYSHAP",
  "status": "posted",
  "payaccsysRef": "PAY-123",
  "channel": "eft",
  "cardCredited": false
}
```

On the `fund_card` channel, `paymentMethod` is `FUND_CARD`, `payaccsysRef` is Spendl's reference for the load (`CL` followed by `journalEntryId`), `channel` is `fund_card` and `cardCredited` is `true`. If a response has neither `channel` nor `cardCredited`, treat it as `eft`.

**Errors:**

| Code | Type                                                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ---- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401  | `INVALID_TOKEN`                                                           | Missing or invalid authentication token                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| 403  | `ACCOUNT_RESTRICTED`                                                      | The user's account is restricted from sending money                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| 404  | `USER_NOT_FOUND`                                                          | `userId` is not one of your users                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| 404  | `CARD_NOT_FOUND`                                                          | `cardId` (or a supplied `cardReference`) is not one of the user's cards                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| 409  | `CARD_ACCOUNT_MISSING`                                                    | `eft` channel only: the user's card is not fully provisioned yet and has no card funding account. Nothing is debited. Retry when provisioning completes.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| 409  | `DUPLICATE_IDEMPOTENCY_KEY`                                               | This key was already used for a top-up (`data.existingEntryId` is its journal entry). With `data.result`, it holds that top-up's outcome, including `channel` and `cardCredited`: act on its `status` (see [Idempotency](#idempotency): `posted` is processed; `pending` is still running, so retry later with the same key; `reversed` was later reversed, so check before trying again; `failed` moved nothing). Without `data.result`, the key was first used in another request: check the transaction history. Never retry with a new key until the outcome is known. See [Idempotency](#idempotency) |
| 422  | `MISSING_IDEMPOTENCY_KEY`                                                 | No key in the body or the `X-Idempotency-Key` header                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| 422  | `INSUFFICIENT_FUNDS`                                                      | User does not have enough funds                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 422  | `CARD_NOT_FUNDABLE`                                                       | `fund_card` channel only: the card is closed (for example, replaced) or expired, and the amount was returned to the wallet (`data.reversed: true`). This spends the key: a same-key retry returns this error again. Do not retry with this card; the message is safe to show the user                                                                                                                                                                                                                                                                                                                      |
| 422  | `PAYACCSYS_SUPPLIER_FAILED`                                               | `eft` channel only: the payment provider did not accept the details of the card's funding account. Nothing is debited. Contact support                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| 500  | `INTERNAL_ERROR`                                                          | The outcome is unknown: the card load may have moved. Retry with the same key, which never moves money twice                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| 502  | `PAYACCSYS_LOAD_FAILED`                                                   | The amount was returned to the wallet (`data.reversed: true`). On `eft`, the payment provider rejected the top-up. On `fund_card`, the request never reached the card provider, or, on a same-key retry, Spendl has refunded a held load (see [held loads](#held-fund_card-loads)). You may start a new top-up with a new key                                                                                                                                                                                                                                                                              |
| 502  | `PAYACCSYS_LOAD_REVERSAL_FAILED`                                          | The top-up was rejected, but the amount could not be returned to the wallet yet. Do not retry; contact support                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| 502  | `PAYACCSYS_LOAD_AMBIGUOUS`                                                | The outcome is unknown and the wallet is still debited (`data.reversed: false`); the payment provider may still accept it. Never retry with a new key. A retry with the same key is safe and returns the current outcome, even though the `message` says not to retry. On `fund_card`, Spendl holds the load and settles or refunds it later (see [held loads](#held-fund_card-loads))                                                                                                                                                                                                                     |
| 502  | `UPSTREAM_NETWORK_ERROR`                                                  | The outcome is unknown (a network timeout or connectivity failure). Retry with the same key, which never moves money twice                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 504  | `REQUEST_TIMEOUT`                                                         | The outcome is unknown: the request ran out of time, and it may still complete. A plain-text `504` from the network edge, or no response, means the same. Retry with the same key, which never moves money twice                                                                                                                                                                                                                                                                                                                                                                                           |
| 5xx  | `WALLET_LOAD_CARD_FAILED`                                                 | The outcome is unknown: the card load may have moved. Retry with the same key, which never moves money twice                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| 5xx  | Any other `5xx`, a plain-text `503` from the network edge, or no response | The outcome is unknown: retry with the same key, which never moves money twice                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

A retry with the same key returns the first attempt's error again (a `PAYACCSYS_*` error, or `422 CARD_NOT_FUNDABLE`) while that attempt is failed or unconfirmed, and `409 DUPLICATE_IDEMPOTENCY_KEY` once it went through. A held `fund_card` load answers with its current outcome, below.

A retry sent while the first request is still waiting for the payment provider (on `fund_card`, while the card provider is crediting the card) returns `502 PAYACCSYS_LOAD_AMBIGUOUS` with `data.reversed: false`, not a `409` with `status: "pending"`. The first request is still running and may still credit the card: never switch to a new key. Retry later with the same key; once the first request has finished, the retry returns its outcome. If it ended with the load held, the retry keeps returning this `502` until Spendl settles or refunds the load (see [held loads](#held-fund_card-loads), below). A retry after a timeout, `502 UPSTREAM_NETWORK_ERROR` or `504 REQUEST_TIMEOUT` can land here; an HTTP timeout of at least 65 seconds makes it unlikely that your own client gives up first.

**Held `fund_card` loads**

On `fund_card`, `502 PAYACCSYS_LOAD_AMBIGUOUS` with `data.reversed: false` means Spendl holds the load and the wallet stays debited until the outcome is known. Spendl then settles the load or refunds the wallet, usually within 30 minutes. A load stays held longer in two cases:

* The card's records can't be read yet. The load stays held until they can be, or until Spendl confirms the outcome with the card provider.
* The card provider's answer was lost (for example, a timeout) and the card shows no credit. Spendl refunds the wallet only after it confirms the outcome with the card provider. If the credit shows on the card first, the load is settled.

The response doesn't say which case applies, and you don't need to know: retry with the same key, as described below.

The error's `message` is generic and says not to retry. Never retry a held load with a new key, because the card may still be credited. A retry with the same key is safe, never moves money twice, and returns the current outcome:

* `409 DUPLICATE_IDEMPOTENCY_KEY` with `data.result`: the load was settled and the card credited (`channel: "fund_card"`, `cardCredited: true`).
* `502 PAYACCSYS_LOAD_FAILED` with `data.reversed: true`: the wallet was refunded. You may start a new top-up with a new key.
* `502 PAYACCSYS_LOAD_AMBIGUOUS` again: the load is still held. Try again later with the same key.

If the card has since been unlinked, or the user check fails, a same-key retry returns that check's error (for example `404 CARD_NOT_FOUND`), which says nothing about the load: check the user's [Transaction History](#transaction-history) or contact support.

No webhook is sent for this later outcome. You can also check the user's [Transaction History](#transaction-history).

***

#### Send to Bank (EFT)

Send funds from a user's wallet to an external bank account. First, register a [beneficiary](#add-beneficiary).

```
POST /api/wallet/send-to-bank
Authorization: Bearer <accessToken>
Content-Type: application/json
```

```json
{
  "userId": "507f...",
  "amount": 50000,
  "withdrawalOption": "ONE_DAY",
  "beneficiaryId": "660a...",
  "description": "Salary payment"
}
```

| Field              | Type    | Required | Description                                                                                                                                            |
| ------------------ | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `userId`           | string  | Yes      | The user's `_id`                                                                                                                                       |
| `amount`           | integer | Yes      | Amount in ZAR cents (positive)                                                                                                                         |
| `withdrawalOption` | string  | Yes      | `"IMMEDIATE"` or `"ONE_DAY"`                                                                                                                           |
| `beneficiaryId`    | string  | Yes      | Beneficiary `_id` (from [Add Beneficiary](#add-beneficiary))                                                                                           |
| `idempotencyKey`   | string  | Yes\*    | Durable key for safe retries. \*Send it here or as the `X-Idempotency-Key` header; both must match when both are sent. See [Idempotency](#idempotency) |
| `description`      | string  | No       | Payment description                                                                                                                                    |
| `metadata`         | object  | No       | Partner metadata, retained under `metadata.partner`                                                                                                    |

**Speed and fee.** Each payment has one flat fee, the same for every tenant and never a percentage. Read the live fees from the `fees` field of [`GET /api/wallet/participating-banks`](#reference-data); they can change.

* `ONE_DAY` (normal): `paymentMethod` is `SAME_DAY` and the fee is `fees.SAME_DAY`, for every bank and amount. Sent on a business day by 15:50 SAST, it is paid the same day; otherwise on the next business day.
* `IMMEDIATE` (instant): the beneficiary's `branchCode` must be a universal branch code listed in `rtcBanks`, or the request returns `422 BANK_NOT_ELIGIBLE_FOR_IMMEDIATE`. Up to `payshapThresholdZar` rand, a payment to a bank in `payshapBanks`, or to Bank Zero (`888000`), is `PAYSHAP` and charged `fees.PAYSHAP`. Above `payshapThresholdZar`, or to any other bank listed only in `rtcBanks`, it is `RTC` and charged `fees.RTC`.
* An `IMMEDIATE` amount above the real-time limit (R5,000,000 on a business day until 15:50 SAST; R250,000 after 15:50, at weekends and on public holidays) is sent as a normal payment on the next business day, to any bank, and charged `fees.SAME_DAY`. The response shows `paymentMethod: "SAME_DAY"`.

`feeAmount` in the response is the fee charged, in ZAR cents (the rand `fees` value × 100). `grossDebit` is `amount + feeAmount`, the amount debited from the wallet.

**Response:**

```json
{
  "success": true,
  "journalEntryId": "6641...",
  "userId": "507f...",
  "amount": 50000,
  "feeAmount": 449,
  "grossDebit": 50449,
  "paymentMethod": "SAME_DAY",
  "status": "posted",
  "payaccsysRef": "PAY-456"
}
```

**Errors:**

| Code | Type                                                                                                                                                             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401  | `INVALID_TOKEN`                                                                                                                                                  | Missing or invalid authentication token                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| 403  | `ACCOUNT_RESTRICTED`                                                                                                                                             | The user's account is restricted from sending money                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| 404  | `BENEFICIARY_NOT_FOUND`                                                                                                                                          | The beneficiary does not exist, belongs to another user, or was removed                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| 409  | `DUPLICATE_IDEMPOTENCY_KEY`                                                                                                                                      | This key was already used for a payment (`data.existingEntryId` is its journal entry). With `data.result`, it holds that payment's outcome: act on its `status` (see [Idempotency](#idempotency): `posted` is processed; `pending` is still running, so retry later with the same key; `reversed` was later reversed, so check before trying again; `failed` moved nothing). Without `data.result`, the key was first used in another request: check the transaction history. Never retry with a new key until the outcome is known. See [Idempotency](#idempotency) |
| 422  | `INSUFFICIENT_FUNDS`                                                                                                                                             | User does not have enough funds                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| 422  | `BENEFICIARY_NOT_REGISTERED`                                                                                                                                     | The beneficiary was not fully registered. Remove it and add it again. Nothing was debited                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 422  | `BANK_NOT_ELIGIBLE_FOR_IMMEDIATE`                                                                                                                                | `IMMEDIATE` to a bank that cannot take instant payments. Nothing was debited. Send it as `ONE_DAY`                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| 502  | `PAYACCSYS_LOAD_FAILED`                                                                                                                                          | The payment provider rejected the payment and the amount was returned to the wallet (`data.reversed: true`). You may start a new payment with a new key                                                                                                                                                                                                                                                                                                                                                                                                              |
| 502  | `PAYACCSYS_EFT_REVERSAL_FAILED`                                                                                                                                  | The payment was rejected, but the amount could not be returned to the wallet yet. Do not retry; contact support                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| 502  | `PAYACCSYS_EFT_AMBIGUOUS`                                                                                                                                        | The outcome is unknown (`data.reversed: false`). Do not retry with a new key; check the balance or contact support. A same-key retry sent while the first request is still waiting for the payment provider also returns it: retry later with the same key                                                                                                                                                                                                                                                                                                           |
| 5xx  | `WALLET_SEND_TO_BANK_FAILED`                                                                                                                                     | The outcome is unknown: the payment may have moved. Retry with the same key, which returns the first attempt's outcome if there was one and never pays twice (see [Error Outcomes](#error-outcomes)). Despite the similar name, it does not mean the payment was refunded; [`wallet.send_to_bank_failed`](#walletsend_to_bank_failed) follows only if the payment is later failed and refunded                                                                                                                                                                       |
| 5xx  | Any other `5xx` (for example `INTERNAL_ERROR`, `REQUEST_TIMEOUT` or `UPSTREAM_NETWORK_ERROR`), a plain-text `503` or `504` from the network edge, or no response | The outcome is unknown: retry with the same key, which never moves money twice                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

Same-key retries behave as on [Load Card](#load-card).

When a payment fails and the whole debit is returned to the wallet, whether the payment is refused when Spendl submits it or the bank fails it later, the API sends [`wallet.send_to_bank_failed`](#walletsend_to_bank_failed) if you have configured that endpoint. No webhook does not mean the payment succeeded: wallet history is the source of truth.

***

### Vouchers and Payouts

Use this API to issue cash vouchers, direct airtime, gift vouchers, and bank payouts. Availability, exact names, codes, limits, and fixed denominations are runtime data. Do not hard-code these values from this guide.

#### Required Workflow

1. Call `GET /api/vouchers/providers` and let the user select an enabled product.
2. Call `GET /api/vouchers/providers/:providerCode/limits` and collect the returned recipient fields.
3. Call `POST /api/vouchers/quote` with the principal amount.
4. Show `amountItt + feeItt = totalItt` and obtain confirmation.
5. Call `POST /api/vouchers/perform` with the exact catalogue name, accepted total, tariff version, and a durable idempotency key (`X-Idempotency-Key` header or `idempotencyKey` in the body).
6. If the response is lost, pending, or ambiguous, call `GET /api/vouchers/status` with either the returned `uniqueReference` or the original idempotency key. Do not create a new payout key.

#### List Providers

```http
GET /api/vouchers/providers HTTP/1.1
Authorization: Bearer <accessToken>
```

```json
{
  "providers": [
    {
      "providerCode": 127,
      "providerName": "TAKEALOT"
    }
  ],
  "total": 1
}
```

The API returns only enabled products with a fee tariff and usable amount. Send `providerName` exactly as returned. Your user interface can show another name.

#### Get Provider Limits

```http
GET /api/vouchers/providers/127/limits HTTP/1.1
Authorization: Bearer <accessToken>
```

```json
{
  "providers": [
    {
      "providerCode": 127,
      "providerName": "TAKEALOT",
      "providerMinLimit": 5000,
      "providerMaxLimit": 200000,
      "requiredRecipientFields": [
        "firstname",
        "surname",
        "idNumber",
        "mobile"
      ],
      "optionalRecipientFields": ["email"]
    }
  ],
  "total": 1
}
```

Limits use ZAR cents. If `providerMinLimit` equals `providerMaxLimit`, the product has a fixed denomination. In this case, `amount` must equal that value. A product that is absent from the catalogue is unavailable. Do not use old codes or limits.

A product that pays out only in whole multiples of a fixed amount also returns `amountStepItt`. For example, Nedbank Cardless Withdrawal pays out in multiples of R10.00:

```json
{
  "providers": [
    {
      "providerCode": 4,
      "providerName": "Nedbank Cardless Withdrawal",
      "providerMinLimit": 2000,
      "providerMaxLimit": 500000,
      "amountStepItt": 1000,
      "requiredRecipientFields": [
        "firstname",
        "surname",
        "idNumber",
        "mobile"
      ],
      "optionalRecipientFields": ["email"]
    }
  ],
  "total": 1
}
```

| Field                     | Type      | Description                                                                                                                                         |
| ------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `providerCode`            | integer   | Current product code                                                                                                                                |
| `providerName`            | string    | Exact catalogue name; send it unchanged on quote and perform                                                                                        |
| `providerMinLimit`        | integer   | Minimum `amount` in ZAR cents                                                                                                                       |
| `providerMaxLimit`        | integer   | Maximum `amount` in ZAR cents                                                                                                                       |
| `amountStepItt`           | integer   | Optional. Present only for a product that pays out in fixed steps: `amount` must be a whole multiple of this value, in ZAR cents (`1000` is R10.00) |
| `requiredRecipientFields` | string\[] | Recipient fields the product requires                                                                                                               |
| `optionalRecipientFields` | string\[] | Recipient fields the product accepts but does not require                                                                                           |

Quote and perform reject an amount that is not a multiple of `amountStepItt` with `422 VOUCHER_PAYOUT_AMOUNT_OUT_OF_RANGE` and `data.reason: "AMOUNT_STEP"`, before any money moves. More fields may be added to this response without a version change.

#### Recipient Fields

The common required fields are `firstname`, `surname`, `idNumber`, and `mobile`. Always read `requiredRecipientFields` for the selected product. The live response can contain more requirements.

The name and mobile fields describe the recipient. `idNumber` and the other identity fields describe the paying user, because the payout is issued on their behalf. When a user buys for someone else, send that person's `firstname`, `surname`, and `mobile` with the paying user's `idNumber`.

| Field            | Meaning                                                                                                                                                                                                                                                                                                                                                                          |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `firstname`      | Recipient given name                                                                                                                                                                                                                                                                                                                                                             |
| `surname`        | Recipient family name                                                                                                                                                                                                                                                                                                                                                            |
| `idNumber`       | The paying user's identity document number, as held for their KYC: the South African ID number, or the passport number for a passport holder. When `idType` is `SA`, it must be a valid South African ID number: 13 digits with a valid date of birth (`YYMMDD`) and checksum; spaces are ignored                                                                                |
| `mobile`         | South African mobile number used for delivery or recipient identification, in `0XXXXXXXXX`, `27XXXXXXXXX` or `+27XXXXXXXXX` form. Spaces and hyphens are ignored                                                                                                                                                                                                                 |
| `accountNumber`  | Destination bank account number                                                                                                                                                                                                                                                                                                                                                  |
| `accountName`    | Destination account-holder name                                                                                                                                                                                                                                                                                                                                                  |
| `branchCode`     | Destination bank branch code                                                                                                                                                                                                                                                                                                                                                     |
| `title`          | Optional title                                                                                                                                                                                                                                                                                                                                                                   |
| `middleName`     | Optional middle name                                                                                                                                                                                                                                                                                                                                                             |
| `idType`         | Optional identity-document type: `SA` or `Passport`. Case, spaces and punctuation are ignored. `SA_ID`, `RSA_ID`, `ID_CARD`, `SMART_ID`, `GREEN_BOOK` and `SAI` count as `SA`; `PASSPORT` and `PASS` count as `Passport`. Spendl never infers `SA` from the number: with no type or another type, Spendl uses the number as given and does not apply the South African ID checks |
| `countryOfIssue` | Optional identity-document issuing country: a two-letter ISO 3166-1 code such as `ZW`, or an English country name such as `Zimbabwe`. Ignored with `idType: "SA"`                                                                                                                                                                                                                |
| `nationality`    | Deprecated. Accepted but ignored                                                                                                                                                                                                                                                                                                                                                 |
| `dateOfBirth`    | Optional date of birth, `yyyy-MM-dd`. With `idType: "SA"`, it must match the date in the ID number                                                                                                                                                                                                                                                                               |
| `gender`         | Optional: `Male` or `Female` (`M` and `F` are accepted)                                                                                                                                                                                                                                                                                                                          |
| `email`          | Optional recipient email address                                                                                                                                                                                                                                                                                                                                                 |
| `branchName`     | Optional bank branch name                                                                                                                                                                                                                                                                                                                                                        |
| `swiftCode`      | Optional SWIFT/BIC                                                                                                                                                                                                                                                                                                                                                               |
| `bankId`         | Optional provider bank identifier                                                                                                                                                                                                                                                                                                                                                |
| `clientAccount`  | Provider-specific account or meter identifier; not required by the products below                                                                                                                                                                                                                                                                                                |

For a South African ID number, send `idType: "SA"` and the user's `dateOfBirth`. Spendl then checks the number, and that the date matches it, before any money moves. With no type, or a type other than `SA`, `Passport` or one of their aliases above, the type is sent blank and the number as given, without these checks.

Recipient details are checked before any money moves. A value that cannot be used returns `422 VOUCHER_PAYOUT_INVALID_RECIPIENT`, with the field in `data.field` and, when present, the reason in `data.reason`. See [Voucher Payout Errors](#voucher-payout-errors).

#### Current Product Requirements

`Common` means `firstname`, `surname`, `idNumber`, and `mobile`. Before each purchase, get the current code, exact name, limits, and additional requirements.

| Product                     | Required recipient data                               | Delivery or eligibility notes                                                                                                  |
| --------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Standard Bank Instant Money | Common                                                | Cash-withdrawal details are delivered to the mobile number                                                                     |
| OTT Voucher                 | Common                                                | Returns or delivers voucher credentials and instructions                                                                       |
| Nedbank Cardless Withdrawal | Common                                                | Cardless cash-withdrawal details are delivered to the mobile number; the amount must be a multiple of R10.00 (`amountStepItt`) |
| CellC Direct Airtime        | Common                                                | Prepaid mobile number; direct airtime may arrive without an SMS                                                                |
| MTN Direct Airtime          | Common                                                | Prepaid mobile number; direct airtime may arrive without an SMS                                                                |
| Telkom Direct Airtime       | Common                                                | Prepaid mobile number; postpaid numbers may be rejected                                                                        |
| Vodacom Direct Airtime      | Common                                                | Prepaid mobile number; direct airtime may arrive without an SMS                                                                |
| Makro Gift Voucher          | Common                                                | Voucher credentials are delivered for merchant redemption                                                                      |
| PnP Digital Vouchers        | Common                                                | Voucher credentials are delivered for merchant redemption                                                                      |
| Shoprite Vouchers           | Common                                                | Voucher credentials are delivered for merchant redemption                                                                      |
| AnyTime Airtime             | Common                                                | Redeemable airtime voucher, not direct airtime; instructions are delivered by SMS                                              |
| Uber and Uber Eats          | Common                                                | Gift-card credentials are redeemed through the Uber wallet flow                                                                |
| TAKEALOT                    | Common                                                | May be variable or fixed denomination; trust live limits                                                                       |
| The Cycle Lab Gift Card     | Common                                                | Voucher credentials are delivered for merchant redemption                                                                      |
| The Pro Shop Gift Card      | Common                                                | Voucher credentials are delivered for merchant redemption                                                                      |
| Netflorist Voucher          | Common                                                | Voucher credentials are delivered for merchant redemption                                                                      |
| PlayStation Gift Card       | Common                                                | Voucher credentials are delivered for account redemption                                                                       |
| PayShap Account             | Common + `accountNumber`, `accountName`, `branchCode` | `bankId`, `branchName`, and `swiftCode` are optional when requested                                                            |
| ABSA CashSend               | Common                                                | CashSend details are delivered to the mobile number; trust the live minimum                                                    |
| RTC EFT                     | Common + `accountNumber`, `accountName`, `branchCode` | `bankId`, `branchName`, and `swiftCode` are optional when requested                                                            |

#### Quote

```http
POST /api/vouchers/quote HTTP/1.1
Authorization: Bearer <accessToken>
Content-Type: application/json

{
  "providerCode": 127,
  "amountItt": 5000
}
```

```json
{
  "providerCode": 127,
  "providerName": "TAKEALOT",
  "amountItt": 5000,
  "feeItt": 115,
  "totalItt": 5115,
  "feeIncludesVat": true,
  "tariffId": "takealot.variable",
  "tariffVersion": "2026-08-01"
}
```

The quote is authoritative. Before confirmation, show the principal, fee, and total debit. If the tariff changes, perform returns `VOUCHER_PAYOUT_QUOTE_STALE` before any money moves.

#### Perform Payout

```http
POST /api/vouchers/perform HTTP/1.1
Authorization: Bearer <accessToken>
X-Idempotency-Key: order-2026-000184
Content-Type: application/json

{
  "userId": "507f1f77bcf86cd799439011",
  "providerCode": 127,
  "providerName": "TAKEALOT",
  "amount": 5000,
  "recipient": {
    "firstname": "Jane",
    "surname": "Doe",
    "idType": "SA",
    "idNumber": "9001015009086",
    "dateOfBirth": "1990-01-01",
    "mobile": "0821234567"
  },
  "expectedTotalDebitItt": 5115,
  "quotedTariffVersion": "2026-08-01"
}
```

The durable key may be sent as the `X-Idempotency-Key` header, as `idempotencyKey` in the body, or both with the same value. See [Idempotency](#idempotency).

| Field                   | Type    | Required | Description                                                                                    |
| ----------------------- | ------- | -------- | ---------------------------------------------------------------------------------------------- |
| `userId`                | string  | Yes      | Wallet owner; must belong to the authenticated tenant                                          |
| `providerCode`          | integer | Yes      | Current code from the provider catalogue                                                       |
| `providerName`          | string  | Yes      | Exact current name from the provider catalogue                                                 |
| `amount`                | integer | Yes      | Recipient principal in ZAR cents, not total debit                                              |
| `recipient`             | object  | Yes      | String-valued fields required by the selected provider                                         |
| `expectedTotalDebitItt` | integer | Yes      | Accepted `totalItt` from the latest quote                                                      |
| `quotedTariffVersion`   | string  | Yes      | Accepted `tariffVersion` from the latest quote                                                 |
| `X-Idempotency-Key`     | header  | Yes\*    | Durable key reused for retries and recovery (1–200 characters)                                 |
| `idempotencyKey`        | string  | Yes\*    | Body form of the same key. \*Send the key in the header, the body, or both with the same value |

Completed voucher response:

```json
{
  "success": true,
  "entity": {
    "userId": "507f1f77bcf86cd799439011",
    "amountItt": 5000,
    "amountRand": 50,
    "customerFeeItt": 115,
    "totalDebitItt": 5115,
    "feeIncludesVat": true,
    "tariffId": "takealot.variable",
    "tariffVersion": "2026-08-01",
    "providerCode": 127,
    "providerName": "TAKEALOT",
    "paymentReference": "VP-394921",
    "voucher": {
      "pin": "<sensitive-voucher-pin>",
      "serialNumber": "<sensitive-serial>",
      "instructions": "Redeem with the selected merchant"
    },
    "uniqueReference": "<tenant-bound-reference>",
    "journalEntryId": "<journal-entry-id>"
  }
}
```

Cash products usually return a payment or withdrawal reference. Direct-airtime products credit the prepaid mobile number and might not return voucher data. PayShap and RTC products return a bank-payout reference. Voucher products can return a PIN, serial number, and instructions.

Pending response:

```json
{
  "success": false,
  "status": "pending",
  "message": "Payout is pending finalisation",
  "uniqueReference": "<tenant-bound-reference>",
  "journalEntryId": "<journal-entry-id>",
  "paymentReference": "VP-394921",
  "amountItt": 5000,
  "customerFeeItt": 115,
  "totalDebitItt": 5115,
  "tariffVersion": "2026-08-01"
}
```

Do not treat this response as a failure. Do not submit a new payout. Poll the status with the original recovery handle.

A retry with the same idempotency key can instead return `"status": "needs_review"` in the same format. The payout is waiting for manual review; see [Get Payout Status](#get-payout-status).

#### Get Payout Status

Supply `userId` and exactly one lookup field:

```http
GET /api/vouchers/status?userId=507f1f77bcf86cd799439011&idempotencyKey=order-2026-000184 HTTP/1.1
Authorization: Bearer <accessToken>
```

Alternatively, use `uniqueReference=<value>`. The status lookup verifies tenant user ownership before returning payout details.

```json
{
  "success": true,
  "status": "completed",
  "providerStatus": "100",
  "amountItt": 5000,
  "customerFeeItt": 115,
  "totalDebitItt": 5115,
  "tariffVersion": "2026-08-01",
  "uniqueReference": "<tenant-bound-reference>",
  "journalEntryId": "<journal-entry-id>",
  "paymentReference": "VP-394921"
}
```

Lifecycle values include `pending`, `completing`, `completed`, `failing`, `failed`, `reversal_failed`, and `needs_review`. After a network timeout, no response, or any `5xx` from perform other than `500 VOUCHER_PAYOUT_REVERSAL_FAILED`, the request might have been accepted. Keep the original key and poll the status.

`needs_review` (with `success: false`) means that Spendl could not confirm the payout's outcome automatically, so the payout is waiting for manual review. The status lookup and a perform retry with the same key return it. It is not final: the payout can still become `completed`, or `failed` with the debit returned to the wallet. Until then the debit stays in place. Do not treat it as a failure, and do not submit a new payout for it. Tell the user that the payout is being reviewed and that they can contact support, and check the status again later. Show the user your own text, not `message`. No webhook is sent for this status.

#### Security Requirements

* Show voucher PINs and serials only to the intended authenticated user.
* Never write voucher credentials to logs, analytics, callbacks, notifications, screenshots, or support tooling.
* Do not log full recipient identity or bank-account data.
* Set `userId` from your own authenticated session, never from a value the end user supplies. Spendl derives the caller from your access token and that `userId`.
* Keep the original idempotency key until the payout reaches a terminal state.

#### Voucher Payout Errors

| Code | Type                                   | Client action                                                                                                                                                                                                                               |
| ---- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 422  | `MISSING_IDEMPOTENCY_KEY`              | Supply a durable key in `X-Idempotency-Key` or `idempotencyKey` and retry once                                                                                                                                                              |
| 422  | `IDEMPOTENCY_KEY_MISMATCH`             | The header and body keys differ; send one value                                                                                                                                                                                             |
| 401  | `INVALID_TOKEN`                        | Re-authenticate the tenant integration                                                                                                                                                                                                      |
| 403  | `FORBIDDEN`                            | Stop; `userId` is not one of your users, or the user does not own the requested payout                                                                                                                                                      |
| 403  | `ACCOUNT_RESTRICTED`                   | Stop; the user's account is restricted from sending money                                                                                                                                                                                   |
| 403  | `KYC_REQUIRED`                         | Stop; the user's KYC must be approved before a payout                                                                                                                                                                                       |
| 404  | `VOUCHER_PAYOUT_NOT_FOUND`             | Verify `userId` and the original recovery handle                                                                                                                                                                                            |
| 422  | `VOUCHER_PAYOUT_INVALID_RECIPIENT`     | Correct the recipient field named in `data.field`. `data.reason`, when present, says why (see the table below)                                                                                                                              |
| 422  | `VOUCHER_PAYOUT_INVALID_STATUS_LOOKUP` | Supply exactly one status lookup field                                                                                                                                                                                                      |
| 422  | `VOUCHER_PAYOUT_PROVIDER_UNAVAILABLE`  | Refresh the provider catalogue                                                                                                                                                                                                              |
| 422  | `VOUCHER_PAYOUT_AMOUNT_OUT_OF_RANGE`   | Refresh limits and choose a valid amount. `data.minAmountItt` and `data.maxAmountItt` give the limits. With `data.reason: "AMOUNT_STEP"`, the amount is within the limits but is not a multiple of `data.amountStepItt`                     |
| 422  | `INSUFFICIENT_FUNDS`                   | No money moved. Resending the same key performs this payout if the wallet has since been funded. If you abandon the payout, never resend its key; use a new key for a new attempt                                                           |
| 422  | `VOUCHER_PAYOUT_FAILED`                | Stop; the payout is final and the reserved funds were returned to the wallet. The key is spent: a same-key retry with the same details returns this error again, so handle it idempotently per key. To try again, use a new idempotency key |
| 409  | `VOUCHER_PAYOUT_QUOTE_STALE`           | Fetch a fresh quote and ask the user to confirm the new total                                                                                                                                                                               |
| 409  | `VOUCHER_PAYOUT_PERFORM_FAILED`        | The key was already used for a payout with different details (user, amount, product or recipient). Never change a payout's details under its key; use a new key for a new payout                                                            |
| 500  | `VOUCHER_PAYOUT_REVERSAL_FAILED`       | Stop and escalate for reconciliation                                                                                                                                                                                                        |
| 502  | `VOUCHER_PAYOUT_AMBIGUOUS`             | The outcome is unknown. Do not use a new key. Poll status with the original key, or resend perform with the same key and the same details                                                                                                   |
| 502  | `VOUCHER_PAYOUT_NETWORK_ERROR`         | Treat perform as ambiguous; for read operations retry with backoff                                                                                                                                                                          |
| 5xx  | `VOUCHER_PAYOUT_PERFORM_FAILED`        | The outcome is unknown: the payout may have gone through. Do not use a new key. Poll status with the original key, or resend perform with the same key and the same details                                                                 |

`VOUCHER_PAYOUT_PERFORM_FAILED` has two meanings, so branch on the HTTP status, not only on the type. With `409`, the key was already used for a payout with different details: use a new key for a new payout. With a `5xx` (for example `504` when the payout could not be confirmed in time, or `500` or `503`), the outcome is unknown and the payout may have gone through: keep the key, and poll status or resend perform with the same key and the same details. Any other `4xx` with this type was refused before money moved: correct the request and resend with the same key.

A resend or a status lookup never returns voucher credentials (`voucher`): only the first `200` of a completed payout carries them. If that response was lost, do not buy again under a new key; contact Spendl support. After a `5xx`, status can answer `404 VOUCHER_PAYOUT_NOT_FOUND` when nothing is recorded yet: resend perform with the same key and the same details.

`VOUCHER_PAYOUT_FAILED` is the only `422` on perform that spends the idempotency key. Every other `422`, `INSUFFICIENT_FUNDS` included, is returned before any money moves and leaves the key unused: correct the request, or fund the wallet, and resend with the same key. After `VOUCHER_PAYOUT_FAILED`, a same-key retry with the same details returns `422 VOUCHER_PAYOUT_FAILED` again, and one with different details returns `409 VOUCHER_PAYOUT_PERFORM_FAILED`. A replay looks exactly like the first failure, so handle `VOUCHER_PAYOUT_FAILED` idempotently per key.

`data.reason` on `VOUCHER_PAYOUT_INVALID_RECIPIENT`:

| `data.reason`      | `data.field`        | Meaning                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------ | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SA_ID_LENGTH`     | `idNumber`          | `idType` is `SA`, and the number is not 13 digits                                                                                                                                                                                                                                                                                                                          |
| `SA_ID_INVALID`    | `idNumber`          | `idType` is `SA`, and the 13 digits are not a valid South African ID number: the date of birth or the checksum is wrong                                                                                                                                                                                                                                                    |
| `DATE_INVALID`     | `dateOfBirth`       | Reserved. A date of birth that cannot be read, for a product that requires one                                                                                                                                                                                                                                                                                             |
| `DOB_ID_MISMATCH`  | `dateOfBirth`       | `idType` is `SA`, and the date of birth differs from the date in the ID number                                                                                                                                                                                                                                                                                             |
| `MOBILE_INVALID`   | `mobile`            | Not a South African mobile number in a supported form                                                                                                                                                                                                                                                                                                                      |
| `COUNTRY_INVALID`  | `countryOfIssue`    | Reserved. Not a recognised ISO code or English country name, for a product that requires the country                                                                                                                                                                                                                                                                       |
| `COUNTRY_REQUIRED` | `countryOfIssue`    | Reserved. No country of issue, for a product that requires it                                                                                                                                                                                                                                                                                                              |
| `REQUIRED`         | Any recipient field | A required field is missing or blank. The required fields are `firstname`, `surname`, `idNumber` and `mobile`. For a bank payout, `accountNumber`, `accountName` and `branchCode` are also required: this applies when the `providerName` you send contains PayShap, or RTC or EFT as a word. For a field that only `requiredRecipientFields` lists, this code is reserved |

Spendl does not return the reserved reasons now. Handle them, so that your integration keeps working when Spendl starts to return them.

A recipient field the API does not accept, or a value that is not a string, returns `data.field` without `data.reason`. Treat a `data.reason` you do not recognise as an invalid value in `data.field`.

***

#### Purchase Voucher (deprecated)

> **Deprecated since v1.38.** Use the [Vouchers and Payouts](#vouchers-and-payouts) flow instead: `GET /api/vouchers/providers` → `GET /api/vouchers/providers/:providerCode/limits` → `POST /api/vouchers/quote` → `POST /api/vouchers/perform` → `GET /api/vouchers/status`. That flow selects the product from a live catalogue, quotes the fee, lets you recover a lost response, and emits the same `wallet.purchase_voucher_completed` webhook. This route keeps working for existing integrations. Every successful (`2xx`) response carries `Deprecation: true` and a `Link: </api/vouchers/perform>; rel="successor-version"` header; error responses do not. No removal date is set yet; it will be announced in this changelog at least 90 days in advance.

```
POST /api/wallet/purchase-voucher
Authorization: Bearer <accessToken>
Content-Type: application/json
```

```json
{
  "userId": "507f...",
  "amount": 10000,
  "feeAmount": "2.50",
  "voucherDetails": { "provider": "Vodacom" }
}
```

`amount` is the voucher principal. The wallet is debited `amount + feeAmount`. The journal metadata stores authoritative integer-cent `amount`, `feeAmount`, and `grossAmount` fields and transaction history returns them unchanged.

| Legacy field                                                                                                       | Successor                                                                                                 |
| ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| `voucherDetails.provider` (free text)                                                                              | `providerCode` + exact `providerName` from `GET /api/vouchers/providers`                                  |
| `feeAmount` (set by you)                                                                                           | `feeItt` from `POST /api/vouchers/quote`, asserted with `expectedTotalDebitItt` and `quotedTariffVersion` |
| `idempotencyKey` (required since v1.38; header or body)                                                            | Required durable key; header or body                                                                      |
| No status lookup; a same-key retry returns the original outcome in `data.result` (see [Idempotency](#idempotency)) | `GET /api/vouchers/status` by `idempotencyKey` or `uniqueReference`                                       |

***

#### Repay Debt

```
POST /api/wallet/repay-debt
Authorization: Bearer <accessToken>
Content-Type: application/json
```

```json
{
  "userId": "507f...",
  "amount": 15000,
  "feeAmount": 250,
  "debtDetails": { "obligationGuid": "abc-123" }
}
```

| Field            | Type                      | Required | Description                                                                                                                                            |
| ---------------- | ------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `userId`         | string                    | Yes      | The user's `_id`                                                                                                                                       |
| `amount`         | integer                   | Yes      | Amount in ZAR cents (positive)                                                                                                                         |
| `idempotencyKey` | string                    | Yes\*    | Durable key for safe retries. \*Send it here or as the `X-Idempotency-Key` header; both must match when both are sent. See [Idempotency](#idempotency) |
| `feeAmount`      | integer or decimal string | No       | Requested fee. See the fee format rules above.                                                                                                         |
| `debtDetails`    | object                    | No       | Details of the debt being repaid                                                                                                                       |
| `metadata`       | object                    | No       | Partner metadata, retained under `metadata.partner`                                                                                                    |

`amount` is the debt principal. The wallet is debited `amount + feeAmount`. The journal metadata stores authoritative integer-cent `amount`, `feeAmount`, and `grossAmount` fields and transaction history returns them unchanged.

**Errors:**

| Code | Type                                                                                                                                                             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 401  | `INVALID_TOKEN`                                                                                                                                                  | Missing or invalid authentication token                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| 403  | `ACCOUNT_RESTRICTED`                                                                                                                                             | The user's account is restricted from sending money                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| 409  | `DUPLICATE_IDEMPOTENCY_KEY`                                                                                                                                      | This key was already used for a repayment (`data.existingEntryId` is its journal entry). With `data.result`, it holds that repayment's outcome: act on its `status` (see [Idempotency](#idempotency): `posted` is processed; `pending` is still running, so retry later with the same key; `reversed` was later reversed, so check before trying again; `failed` moved nothing). Without `data.result`, the key was first used in another request: check the transaction history. Never retry with a new key until the outcome is known. See [Idempotency](#idempotency) |
| 422  | `INVALID_FEE_AMOUNT`                                                                                                                                             | `feeAmount` does not use an accepted format                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| 422  | `INSUFFICIENT_FUNDS`                                                                                                                                             | User does not have enough funds                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| 5xx  | `WALLET_REPAY_DEBT_FAILED`                                                                                                                                       | The outcome is unknown: the repayment may have moved. Retry with the same key, which never moves money twice                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| 5xx  | Any other `5xx` (for example `INTERNAL_ERROR`, `REQUEST_TIMEOUT` or `UPSTREAM_NETWORK_ERROR`), a plain-text `503` or `504` from the network edge, or no response | The outcome is unknown: retry with the same key, which never moves money twice                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |

***

#### Add Beneficiary

Register a bank beneficiary for electronic funds transfer (EFT) payments. Register the beneficiary before you use [Send to Bank](#send-to-bank-eft).

```
POST /api/wallet/beneficiary
Authorization: Bearer <accessToken>
Content-Type: application/json
```

```json
{
  "userId": "507f...",
  "bankName": "FNB",
  "accountNumber": "62000000001",
  "accountType": "Cheque",
  "branchCode": "250655",
  "accountHolder": "John Doe",
  "reference": "RENT",
  "supplierType": "Individual",
  "idempotencyKey": "beneficiary-2026-000184"
}
```

| Field            | Type   | Required | Description                                                                                                                                                                                                                                                                                                                       |
| ---------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `userId`         | string | Yes      | The user's `_id`                                                                                                                                                                                                                                                                                                                  |
| `bankName`       | string | Yes      | Bank name (see [Reference Data](#reference-data))                                                                                                                                                                                                                                                                                 |
| `accountNumber`  | string | Yes      | Bank account number                                                                                                                                                                                                                                                                                                               |
| `accountType`    | string | Yes      | Account type (see [Reference Data](#reference-data))                                                                                                                                                                                                                                                                              |
| `branchCode`     | string | Yes      | The bank's universal branch code. `IMMEDIATE` payments need it: see [Send to Bank](#send-to-bank-eft)                                                                                                                                                                                                                             |
| `accountHolder`  | string | Yes      | Account holder name                                                                                                                                                                                                                                                                                                               |
| `branchName`     | string | No       | Bank branch name                                                                                                                                                                                                                                                                                                                  |
| `reference`      | string | No       | Your reference for this beneficiary                                                                                                                                                                                                                                                                                               |
| `supplierType`   | string | No       | Supplier type (see [Reference Data](#reference-data))                                                                                                                                                                                                                                                                             |
| `idempotencyKey` | string | No       | Spendl sends it as the `X-Idempotency-Key` of the [`wallet.beneficiary_added`](#walletbeneficiary_added) webhook. A retry is not replayed: a retry for the same account returns `409 DUPLICATE_ENTRY`. May be sent as the `X-Idempotency-Key` header instead; both must match when both are sent. See [Idempotency](#idempotency) |

**Errors:**

| Code | Type                                                                                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ---- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401  | `INVALID_TOKEN`                                                                            | Missing or invalid authentication token                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| 409  | `DUPLICATE_ENTRY`                                                                          | The user already has an active beneficiary with this account number. A retry of an add that succeeded also returns this                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| 422  | `IDEMPOTENCY_KEY_MISMATCH`                                                                 | The body and header keys differ                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 422  | `VALIDATION_ERROR`                                                                         | Invalid fields                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| 422  | `INCOMPLETE_KYC`                                                                           | `Individual` beneficiary only: the user's KYC data is missing a field needed to add a beneficiary. `data.missingFields` names each one: `lastName`, `idNumber` or `identityType`, as in [Sender Profile](#sender-profile). A missing `identityType` is read from a valid South African ID number, so it is asked for only when the number is missing or is not one. Nothing is added. Add the fields with [Replace KYC Details](#replace-kyc-details), which restarts KYC, and try again once the user is approved again. For a user created from a [Sumsub share token](#create-user-from-sumsub-share-token), these fields cannot be changed; contact support |
| 422  | `PAYACCSYS_SUPPLIER_FAILED`                                                                | The payment provider did not accept the beneficiary's details, for example an account number that failed bank verification. Nothing is added. Correct the details and add the beneficiary again                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 502  | `WALLET_BENEFICIARY_ADD_FAILED`                                                            | The beneficiary may have been added. Handle it like any other `5xx` (next row)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| 5xx  | Any other `5xx` (for example `INTERNAL_ERROR` or `UPSTREAM_NETWORK_ERROR`), or no response | The beneficiary may have been added. Retry. If the retry returns `409 DUPLICATE_ENTRY`, the first attempt succeeded: get the beneficiary's `_id` from [List Beneficiaries](#list-beneficiaries)                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

**Response:**

```json
{
  "success": true,
  "_id": "660a...",
  "bankName": "FNB",
  "accountNumber": "62000000001",
  "accountType": "Cheque",
  "branchCode": "250655",
  "branchName": null,
  "accountHolder": "John Doe",
  "reference": "RENT",
  "supplierCode": "SUP-123",
  "supplierType": "Individual",
  "isActive": true,
  "createdAt": "2026-05-21T13:30:00.000Z"
}
```

`branchName` and `reference` are `null` when not sent, and `supplierType` defaults to `Individual`. `_id` is the `beneficiaryId` for [Send to Bank](#send-to-bank-eft) and [Remove Beneficiary](#remove-beneficiary).

***

#### List Beneficiaries

```
GET /api/wallet/beneficiaries/:userId
Authorization: Bearer <accessToken>
```

| Parameter | Type   | Description      |
| --------- | ------ | ---------------- |
| `userId`  | string | The user's `_id` |

**Response:**

```json
{
  "items": [
    {
      "_id": "660a...",
      "bankName": "FNB",
      "accountNumber": "62000000001",
      "accountType": "Cheque",
      "branchCode": "250655",
      "branchName": null,
      "accountHolder": "John Doe",
      "reference": "RENT",
      "supplierCode": "SUP-123",
      "isActive": true,
      "createdAt": "2026-05-21T13:30:00.000Z"
    }
  ]
}
```

***

#### Remove Beneficiary

```
DELETE /api/wallet/beneficiary/:userId/:beneficiaryId
Authorization: Bearer <accessToken>
```

| Parameter       | Type   | Description             |
| --------------- | ------ | ----------------------- |
| `userId`        | string | The user's `_id`        |
| `beneficiaryId` | string | The beneficiary's `_id` |

**Response:**

```json
{
  "success": true,
  "message": "Beneficiary removed."
}
```

Removal is a soft delete: the beneficiary is no longer listed and cannot be paid ([Send to Bank](#send-to-bank-eft) returns `404 BENEFICIARY_NOT_FOUND`). Adding the same account again creates a new beneficiary with a new `_id`.

**Errors:**

| Code | Type            | Description                                                                     |
| ---- | --------------- | ------------------------------------------------------------------------------- |
| 401  | `INVALID_TOKEN` | Missing or invalid authentication token                                         |
| 404  | `NOT_FOUND`     | The beneficiary does not exist, belongs to another user, or was already removed |

***

#### Reference Data

These endpoints return static reference data for beneficiary and payment operations. The cache stores responses for up to 5 minutes by default.

| Method | Path                              | Description                        |
| ------ | --------------------------------- | ---------------------------------- |
| GET    | `/api/wallet/bank-options`        | Available banks                    |
| GET    | `/api/wallet/account-types`       | Bank account types                 |
| GET    | `/api/wallet/supplier-types`      | Supplier types                     |
| GET    | `/api/wallet/participating-banks` | Banks participating in PayShap/RTC |

All require `Authorization: Bearer <accessToken>`.

`/api/wallet/participating-banks` returns the instant-payment banks and the [Send to Bank](#send-to-bank-eft) fees for this environment. Read the values from the response: they can change.

| Field                 | Type      | Description                                                                                                           |
| --------------------- | --------- | --------------------------------------------------------------------------------------------------------------------- |
| `payshapBanks`        | object    | Banks that take PayShap payments, keyed by universal branch code, with the bank's name as the value                   |
| `rtcBanks`            | object    | Banks that take instant payments (`IMMEDIATE`), keyed by universal branch code. Includes every bank in `payshapBanks` |
| `fees`                | object    | The flat fee per payment for each `paymentMethod` (`SAME_DAY`, `PAYSHAP`, `RTC`), in rand                             |
| `payshapThresholdZar` | number    | The largest amount, in rand, sent as `PAYSHAP`. Larger instant payments are `RTC`                                     |
| `paymentMethods`      | string\[] | The `paymentMethod` values a payment can have                                                                         |

It also returns `cardLoad`, how [Load Card](#load-card) loads cards in this environment: `{ "channel": "eft" | "fund_card", "feeZar": number | null, "receiveFeeZar": number | null }`. On `fund_card`, `feeZar` is the flat load fee and `receiveFeeZar` is what the card provider charges the card to receive a load, both in rand; on `eft` both are `null` and the fee depends on the withdrawal option. If `cardLoad` is absent, treat it as `eft`. Like the rest of this response, `cardLoad` is cached for up to 5 minutes by default, so it can lag a channel switch; the load-card response's `channel` is the channel that was actually used.

***

### Pay@ Integration

Pay@ lets users **deposit cash at any Pick n Pay or Boxer till** (Pay@ IN). Cash withdrawal at a till with a single-use PIN (Pay@ OUT) is **not available** yet (see below). Both flows use the account number sequence that Spendl assigns. Each account number has 18 digits, and its first five are a Pay@ issuer prefix. Deposits use the prefix Spendl sets up for your tenant, returned as `deposit.issuerPrefix` by [`GET /api/payat/account/:userId`](#get-apipayataccountuserid); a user's deposit and payout account numbers can be the same. Don't hard-code the prefix: show `accountNumber` exactly as returned.

> **Not available yet:** Pay@ cash withdrawal (Pay@ OUT) is not available. [`POST /api/wallet/withdrawal/payat`](#post-apiwalletwithdrawalpayat) returns `403 PAYAT_PAYOUT_NOT_ENABLED` and issues no PIN, and a PIN issued before this change cannot be used. Don't offer cash withdrawal at a till or show users the `payout` account number from [`GET /api/payat/account/:userId`](#get-apipayataccountuserid). For cash payouts, use [Vouchers and Payouts](#vouchers-and-payouts). The reference below stays for when Spendl announces availability in the [Changelog](#changelog). Pay@ deposits are not affected.

Gross and provider amounts use **ZAR cents** and must be positive integers. For example, `R125.00` is `12500`. On Pay@ deposits, the optional public `feeAmount` accepts either integer cents or a decimal ZAR string as described in [Wallet Operations](#wallet-operations).

#### Pay@ Deposit Flow

```
1. Tenant → POST /api/wallet/deposit/payat
  { userId, amount, feeAmount? }

2. Spendl → returns:
   { referenceKey, accountNumber, webPaymentLinks[],
     appPaymentLinks[], qrCodePayment }

3. Tenant displays payment links / QR / 18-digit account number
   to user (account number can be rendered as a Code 128 barcode
   for in-store bill payment at Pick n Pay).

4. User pays via any method (card, EFT, QR, cash at a Pick n Pay till).

5. Pay@ notifies Spendl → user wallet credited asynchronously.
   Tenant polls GET /api/payat/transactions for status.

6. (Card / EFT only) After payment, Spendl redirects the customer's
   browser to your destination — either the URL supplied on the
   request, or the one configured for your tenant.
```

For Pay@ deposits, the requested fee is additional to the provider-computed fee. Pay@ receives the gross `amount` unchanged. The wallet receives `amount - requested fee - provider fee`. Your requested fee goes to tenant fee revenue account `4010` and the provider fee to Spendl's transaction fee account `4000` (see [Journal Conventions](#journal-conventions)). If the total fee leaves no positive net amount, Spendl returns `422 FEE_EXCEEDS_AMOUNT` before it submits the payment to Pay\@.

#### Pay@ Withdrawal Flow

> **Not available yet:** step 1 returns `403 PAYAT_PAYOUT_NOT_ENABLED`. See [Pay@ Integration](#pay-integration).

```
1. Tenant → POST /api/wallet/withdrawal/payat
   { userId, amount, withdrawalRequestId }

2. Spendl → returns:
   { pin: "654321", accountNumber, amount, expiresAt,
     withdrawalRequestId, pinId }

3. Tenant delivers the plaintext PIN to user via their own
   secure channel (encrypted SMS, in-app message). The user
   also needs the 18-digit accountNumber (Pay@ OUT prefix 13044).

4. User walks into a participating retailer, presents the
   accountNumber + PIN at the till. Pay@ confirms with Spendl,
   which debits the wallet and authorises the payout.

5. Retailer hands cash. Tenant polls
   GET /api/payat/withdrawal/status/:withdrawalRequestId — status
   moves issued → authorized → redeemed.
```

#### Security expectations (Pay@ OUT)

> **Not available yet:** these apply once Pay@ cash withdrawal is available. Until then no PIN is issued.

> **The plaintext PIN appears only in the `initiate withdrawal` response. Spendl stores only a one-way hash of each PIN and cannot show it again after this response.**

Tenant-side obligations:

* Send the PIN to your user **only through a channel you control**. Examples are HTTPS, an encrypted SMS gateway, and a secure in-app message.
* **Never log the PIN.** Tenant logs are outside Spendl's audit boundary.
* Use `withdrawalRequestId` as the durable idempotency token, such as your own withdrawal request ID. Reusing it returns `409 PAYOUT_PIN_ALREADY_ISSUED`.
* The PIN expires after 30 minutes by default. Override this period through `expiresInSec`, which is clamped to `[60, 86400]`.

#### POST /api/wallet/deposit/payat

Start a Pay@ deposit and return the payment links and account number.

> **Redirect URLs:** `successUrl`, `failedUrl`, and `cancelledUrl` are optional. Omit them to use the redirect destinations configured for your tenant.
>
> After payment, Spendl redirects the customer's browser to the URL you supplied for that status, with a `ref` query parameter attached that identifies the deposit. If your URL already has a `ref` parameter, Spendl keeps yours. Your URL needs no allow-listing with Pay\@.
>
> Each status resolves independently — supply only `successUrl` and the other two still use your configured destinations. A URL that is missing, blank, longer than 2048 characters, not a valid URL, or not `https://` is **silently dropped**: that status falls back to the destination configured for your tenant, and the deposit still succeeds. `http://` is rejected along with every other scheme — `ref` is attached to your URL, so it must not travel in plaintext. You will not get a validation error, so verify the redirect in staging before relying on it.
>
> Spendl enables Pay@ redirects for your tenant during onboarding. Until then, Pay@ deposits fail with a `422` (for example `PAYAT_DIGIAPI_UNAUTHORIZED_HOST`), including simulated deposits in staging. Ask Spendl to enable them.
>
> Two caveats. Spendl re-encodes your URL's query string when it attaches `ref` (for example `%20` becomes `+` and `@` becomes `%40`), so avoid depending on exact query encoding. And **do not treat the redirect as proof of payment** — anyone can open the link. Confirm the outcome from the Pay@ transaction record or your webhook.

**Request:**

```http
POST /api/wallet/deposit/payat HTTP/1.1
Authorization: Bearer <accessToken>
Content-Type: application/json
X-Idempotency-Key: <uuid>          # optional; see Idempotency

{
  "userId": "507f1f77bcf86cd799439011",
  "amount": 50000,                    // ZAR cents (R500.00)
  "feeAmount": "2.50",               // optional decimal ZAR string; becomes 250 cents
  "clientReference": "optional-tenant-ref",
  "simulate": true,                    // staging only — triggers simulated payment asynchronously
  "simulateStatus": "success",           // "success" | "failed" | "cancelled"

  // All optional — omit to use your configured redirect destinations
  "successUrl": "https://acme.example/payments/done",
  "failedUrl": "https://acme.example/payments/failed",
  "cancelledUrl": "https://acme.example/payments/cancelled"
}
```

| Field             | Type                      | Required | Description                                                                                                                                                                                                                      |
| ----------------- | ------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `userId`          | string                    | Yes      | The user's `_id`                                                                                                                                                                                                                 |
| `amount`          | integer                   | Yes      | Gross inclusive amount in ZAR cents (min 1000, max 500000)                                                                                                                                                                       |
| `feeAmount`       | integer or decimal string | No       | Requested fee. This is additional to the provider-computed deposit fee.                                                                                                                                                          |
| `clientReference` | string                    | No       | Your reference for this deposit                                                                                                                                                                                                  |
| `simulate`        | boolean                   | No       | **Staging only.** When `true`, the API starts the deposit normally and also starts a simulated payment asynchronously. `simulateStatus` sets the outcome. Production disables simulation and ignores this flag without an error. |
| `simulateStatus`  | string                    | No       | The outcome to simulate: `"success"` (the wallet is credited), `"failed"` (the payment is declined), or `"cancelled"` (the user cancelled). Default: `"success"`.                                                                |
| `successUrl`      | string                    | No       | Where to send the customer after a successful payment. Must be `https://`, max 2048 characters. Silently ignored if invalid — see **Redirect URLs** above.                                                                       |
| `failedUrl`       | string                    | No       | Where to send the customer after a failed payment. Same rules as `successUrl`.                                                                                                                                                   |
| `cancelledUrl`    | string                    | No       | Where to send the customer after a cancelled payment. Same rules as `successUrl`.                                                                                                                                                |

**Response (200 OK):**

```json
{
  "success": true,
  "userId": "507f1f77bcf86cd799439011",
  "amount": 50000,
  "feeAmount": 250,
  "providerFeeAmount": 1250,
  "netAmount": 48500,
  "amountDisplay": "R500.00",
  "referenceKey": "ref-key-uuid",
  "accountNumber": "130441256000000001",
  "clientReference": "SPC-507f...-abc12345",
  "webPaymentLinks": [
    { "paymentMethodName": "CARD", "paymentUrl": "https://payat.io/card?token=..." },
    { "paymentMethodName": "EFT",  "paymentUrl": "https://payat.io/eft?token=..." }
  ],
  "appPaymentLinks": [
    { "paymentMethodName": "MASTERPASS", "paymentUrl": "https://payat.io/masterpass?token=..." },
    { "paymentMethodName": "SNAPSCAN",  "paymentUrl": "https://payat.io/snapscan?token=..." }
  ],
  "qrCodePayment": {
    "qrCodeUrl": "https://payat.io/qr/130441256000000001",
    "supportedApplications": ["SNAPSCAN", "MASTERPASS", "ZAPPER"]
  },
  "pendingTopUps": 0
}
```

When you send `simulate: true` in staging, the response has the **same format**. The simulated payment runs asynchronously. The system sends the result to the tenant's configured webhook.

`providerFeeAmount` is the provider fee used for initiation validation. The actual Pay@ fee depends on the completed tender. Spendl records the final requested fee, provider fee, total fee, and net amount in integer cents. A reversal reverses the recorded total fee. Do not send a new fee on a reversal.

**Common errors:**

| HTTP | `type`                                                                            | Cause                                                                                                                                                                                                                                                   |
| ---- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401  | `NO_AUTH_HEADER` / `INVALID_AUTH_FORMAT` / `INVALID_TOKEN` / `NO_TENANT_ON_TOKEN` | Missing or invalid Bearer token ([Authentication](#authentication))                                                                                                                                                                                     |
| 403  | `FORBIDDEN`                                                                       | `userId` is not one of your users. Nothing is initiated                                                                                                                                                                                                 |
| 422  | `VALIDATION_ERROR`                                                                | A missing or malformed field: a `userId` that is not a 24-character hex ID, or an `amount` that is not an integer or is outside `1000`–`500000` (R10–R5,000)                                                                                            |
| 422  | `BELOW_MINIMUM_AMOUNT`                                                            | Amount below a deposit minimum that Spendl has set above `1000` (`data.minAmount`)                                                                                                                                                                      |
| 422  | `EXCEEDS_MAXIMUM_AMOUNT`                                                          | Amount above a deposit maximum that Spendl has set below `500000` (`data.maxAmount`)                                                                                                                                                                    |
| 422  | `INVALID_FEE_AMOUNT`                                                              | `feeAmount` does not use an accepted format                                                                                                                                                                                                             |
| 422  | `FEE_EXCEEDS_AMOUNT`                                                              | Requested fee plus the validation provider fee leaves no positive net amount                                                                                                                                                                            |
| 422  | `PAYAT_DIGIAPI_UNAUTHORIZED_HOST`                                                 | Spendl has not yet enabled Pay@ redirects for your tenant. Ask Spendl                                                                                                                                                                                   |
| 422  | `IDEMPOTENCY_KEY_MISMATCH`                                                        | The body and header keys differ                                                                                                                                                                                                                         |
| 409  | `IDEMPOTENCY_KEY_MISMATCH`                                                        | This idempotency key was already used for a deposit with a different `userId`, `amount` or `feeAmount`                                                                                                                                                  |
| 409  | `PAYAT_INITIATION_PENDING`                                                        | The first request with this key has not finished, or it ended with an error. Retry shortly with the same key. If it still returns this after about two minutes, use a new key: the first request returned no payment links, so the user cannot pay them |
| 409  | `PAYAT_INITIATION_PREVIOUSLY_FAILED`                                              | The first request with this key failed. Retry with a new key                                                                                                                                                                                            |
| 502  | `PAYAT_DIGIAPI_HTTP_ERROR`                                                        | Pay@ could not create the payment links. Retry with a new key                                                                                                                                                                                           |

**Amount limits.** The API first checks `amount` against the fixed range `1000`–`500000`. An amount outside it, such as `999` or `500001`, returns `422 VALIDATION_ERROR`. `BELOW_MINIMUM_AMOUNT` and `EXCEEDS_MAXIMUM_AMOUNT` apply only to an amount inside that range, where Spendl has configured narrower Pay@ deposit limits for the environment. With the default limits you do not receive them. Treat all three as an amount that is out of range.

***

#### POST /api/wallet/withdrawal/payat

Issue a single-use Pay@ OUT (cash-at-till) PIN for a user.

> **Not available yet:** this endpoint returns `403 PAYAT_PAYOUT_NOT_ENABLED`. No PIN is issued and nothing moves. Spendl will announce availability in the [Changelog](#changelog). Until then, use [Vouchers and Payouts](#vouchers-and-payouts) for cash payouts.
>
> ```json
> {
>   "error": {
>     "message": "Pay@ cash withdrawals are not available.",
>     "code": 403,
>     "type": "PAYAT_PAYOUT_NOT_ENABLED"
>   }
> }
> ```

**Request:**

```http
POST /api/wallet/withdrawal/payat HTTP/1.1
Authorization: Bearer <accessToken>
Content-Type: application/json

{
  "userId": "507f1f77bcf86cd799439011",
  "amount": 25000,                       // ZAR cents (R250.00)
  "withdrawalRequestId": "tenant-wr-abc-123",
  "expiresInSec": 1800,                  // optional, default 1800 (30 min), clamped to [60, 86400]
  "metadata": { "source": "tenant-app" } // optional, free-form audit
}
```

**Response (200 OK):**

```json
{
  "success": true,
  "pin": "654321",                       // ⚠ Deliver securely to user — never log
  "accountNumber": "130441256000000001",  // 18-digit, Pay@ OUT prefix 13044
  "amount": 25000,
  "expiresAt": "2026-06-29T10:30:00.000Z",
  "pinId": "pin-id-1",
  "withdrawalRequestId": "tenant-wr-abc-123"
}
```

**Common errors:**

| HTTP | `type`                                                                            | Cause                                                                                                                                                        |
| ---- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 401  | `NO_AUTH_HEADER` / `INVALID_AUTH_FORMAT` / `INVALID_TOKEN` / `NO_TENANT_ON_TOKEN` | Missing or invalid Bearer token ([Authentication](#authentication))                                                                                          |
| 403  | `PAYAT_PAYOUT_NOT_ENABLED`                                                        | Pay@ cash withdrawal is not available yet. No PIN is issued and nothing moves                                                                                |
| 403  | `FORBIDDEN`                                                                       | `userId` is not one of your users. No PIN is issued                                                                                                          |
| 403  | `ACCOUNT_RESTRICTED`                                                              | The user's account is restricted from sending money                                                                                                          |
| 409  | `PAYOUT_PIN_ALREADY_ISSUED`                                                       | The `withdrawalRequestId` was reused. You cannot recover the PIN. Void the existing PIN and retry with a new ID.                                             |
| 422  | `VALIDATION_ERROR`                                                                | A missing or malformed field: a `userId` that is not a 24-character hex ID, or an `amount` that is not an integer or is outside `5000`–`500000` (R50–R5,000) |
| 422  | `PAYOUT_AMOUNT_OUT_OF_RANGE`                                                      | Amount outside payout limits that Spendl has set narrower than `5000`–`500000` (`data.minCents`, `data.maxCents`)                                            |
| 500  | `TENANT_MISSING_TREASURY_PREFIX`                                                  | Tenant configuration error. Contact support.                                                                                                                 |

**Amount limits.** The API first checks `amount` against the fixed range `5000`–`500000`. An amount outside it, such as `4999` or `500001`, returns `422 VALIDATION_ERROR`. `PAYOUT_AMOUNT_OUT_OF_RANGE` applies only to an amount inside that range, where Spendl has configured narrower Pay@ payout limits for the environment. With the default limits you do not receive it. Treat both as an amount that is out of range.

***

#### GET /api/payat/account/:userId

Get a user's stable deposit and payout account numbers without starting a transaction. Use this endpoint to show the deposit reference before payment. For example, you can show a barcode for in-store scanning.

> **Not available yet:** the `payout` account number cannot be used at a till yet, because Pay@ cash withdrawal is [not available](#pay-integration). The response still includes the `payout` block, unchanged, so existing parsers keep working. Don't show the payout number to your users.

**Response (200 OK):**

```json
{
  "userId": "507f1f77bcf86cd799439011",
  "userSeq": 1,
  "treasuryPrefix": "SPC",
  "deposit": {
    "issuerPrefix": "13044",
    "accountNumber": "130441256000000001",
    "purpose": "Cash deposit at PnP bill-pay till (Pay@ IN)"
  },
  "payout": {
    "issuerPrefix": "13044",
    "accountNumber": "130441256000000001",
    "purpose": "Cash withdrawal at participating retailer (Pay@ OUT)"
  }
}
```

The account numbers are assigned on the first call for a user and never change. The user must be one of your users.

**Errors:**

| HTTP | `type`                                                                            | Cause                                                               |
| ---- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| 401  | `NO_AUTH_HEADER` / `INVALID_AUTH_FORMAT` / `INVALID_TOKEN` / `NO_TENANT_ON_TOKEN` | Missing or invalid Bearer token ([Authentication](#authentication)) |
| 403  | `FORBIDDEN`                                                                       | `userId` is not one of your users. No account numbers are assigned  |
| 422  | `VALIDATION_ERROR`                                                                | `userId` is not a 24-character hex ID                               |

***

#### GET /api/payat/transactions

Paginated read of a user's Pay@ deposit transaction history.

**Query string:**

| Param          | Type                  | Notes                                                                                           |
| -------------- | --------------------- | ----------------------------------------------------------------------------------------------- |
| `userId`       | string (**required**) | Spendl user id                                                                                  |
| `page`         | integer               | default `1`                                                                                     |
| `pageSize`     | integer               | default `20`, max `100`                                                                         |
| `status`       | string                | optional filter — `initiated`, `authorized`, `completed`, `voided`, `reversal_*`                |
| `referenceKey` | string                | optional filter — matches either Pay@'s `digiApiReferenceKey` **or** Spendl's `clientReference` |

**Response (200 OK):**

```json
{
  "userId": "...",
  "items": [
    {
      "transactionId": "PAYAT-...",
      "issuerTransactionId": "ISS-...",
      "accountNumber": "130441256000000001",
      "amount": 12500,
      "amountDisplay": "R125.00",
      "status": "completed",
      "digiApiReferenceKey": "ref-key-1",
      "clientReference": "SPC-USER1-abc",
      "completedAt": "2026-06-01T10:00:00.000Z",
      "createdAt": "2026-06-01T09:55:00.000Z",
      "updatedAt": "2026-06-01T10:00:00.000Z"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 1,
  "hasMore": false
}
```

A user with no Pay@ deposits returns an empty `items` list.

**Errors:**

| HTTP | `type`                                                                            | Cause                                                                                        |
| ---- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| 401  | `NO_AUTH_HEADER` / `INVALID_AUTH_FORMAT` / `INVALID_TOKEN` / `NO_TENANT_ON_TOKEN` | Missing or invalid Bearer token ([Authentication](#authentication))                          |
| 403  | `FORBIDDEN`                                                                       | `userId` is not one of your users                                                            |
| 422  | `VALIDATION_ERROR`                                                                | `userId` is missing or is not a 24-character hex ID, or `page` or `pageSize` is out of range |

***

#### GET /api/payat/transactions/:id

Get one Pay@ deposit transaction by its ID. Use the `transactionId` or `issuerTransactionId` returned by [`GET /api/payat/transactions`](#get-apipayattransactions). The endpoint is tenant-scoped. You can retrieve only IDs that belong to your tenant.

***

#### GET /api/payat/withdrawal/status/:withdrawalRequestId

Get the lifecycle status of an issued payout PIN. The endpoint **never returns the plaintext PIN**. It returns only the lifecycle state and audit timestamps.

> **Not available yet:** no new PIN is issued. This endpoint still answers for a PIN issued earlier until shortly after its `expiresAt`, then returns `404 PAYOUT_PIN_NOT_FOUND`.

**Status values:** `issued`, `authorized`, `redeemed`, `voided`. `expired` is reserved and not currently returned.

A PIN's status is available only until shortly after its `expiresAt`; after that this endpoint returns `404 PAYOUT_PIN_NOT_FOUND`. Until then, an unused PIN past its `expiresAt` can still read `issued`, but it cannot be used: compare `expiresAt` with the current time. Store any outcome you need before `expiresAt`.

**Response (200 OK):**

```json
{
  "pinId": "pin-id-1",
  "userId": "507f1f77bcf86cd799439011",
  "withdrawalRequestId": "tenant-wr-abc-123",
  "accountNumber": "130441256000000001",
  "amount": 25000,
  "amountDisplay": "R250.00",
  "status": "redeemed",
  "expiresAt": "2026-06-29T10:30:00.000Z",
  "networkTransactionId": "net-tx-1",
  "issuerTransactionId": "iss-tx-1",
  "attemptCount": 1,
  "lastAttemptAt": "2026-06-29T10:25:00.000Z",
  "createdAt": "2026-06-29T10:00:00.000Z",
  "updatedAt": "2026-06-29T10:25:00.000Z"
}
```

Returns `404 PAYOUT_PIN_NOT_FOUND` if no PIN exists for the `withdrawalRequestId` in your tenant, including once the PIN's status is no longer available (shortly after `expiresAt`) and for a request refused with `403 PAYAT_PAYOUT_NOT_ENABLED`.

***

#### GET /api/payat/withdrawal/list/:userId

Get a paginated list of a user's withdrawal PINs. Each item has the same shape as `withdrawal/status/:withdrawalRequestId`. The response uses `{ userId, items, page, pageSize, total, hasMore }`. The endpoint **never** returns plaintext PINs.

While Pay@ cash withdrawal is [not available](#pay-integration), the list holds only PINs issued earlier, until shortly after each one's `expiresAt`. No PIN currently has status `expired`, so `status=expired` returns no items.

**Query string:** `page`, `pageSize`, `status` (same defaults as `/api/payat/transactions`).

**Errors:** the same as [`GET /api/payat/transactions`](#get-apipayattransactions): `403 FORBIDDEN` when `userId` is not one of your users, and `422 VALIDATION_ERROR` for a `userId` that is not a 24-character hex ID or a `page` or `pageSize` that is out of range.

***

### Zapper Integration

Zapper is another way to move money into and out of a wallet. It has two flows:

* **Deposit (Zapper IN)** — A **Hosted Payment Page (HPP)** top-up. Spendl creates a Zapper payment session and returns `redirectUrl`. Send the user to this URL. The user can pay by card, instant EFT, or the Zapper app. After Zapper confirms payment, Spendl credits the user's wallet asynchronously.
* **Withdrawal (Zapper OUT)** — A **scan-to-pay** payment. The user scans a Zapper merchant QR code. Decode the code and show a confirmation screen. After confirmation, Spendl debits the user's wallet and pays the merchant through Zapper. This flow removes money from the wallet.

All amounts use **ZAR cents** and must be positive integers. For example, `R125.00` is `12500`. The default limits match the Pay@ limits.

#### Zapper Deposit Flow

```
1. Tenant → POST /api/wallet/deposit/zapper
  { userId, amount, feeAmount?, returnBaseUrl? }

2. Spendl → returns:
   { success: true,
     entity: { sessionId, redirectUrl, merchantOrderId, amount } }

3. Tenant redirects the user to `redirectUrl` (the Zapper HPP).

4. User pays on the Zapper Hosted Payment Page.

5. Zapper → notifies Spendl (webhook) → user wallet credited
   asynchronously. Tenant polls
   GET /api/zapper/deposit/status/:sessionId (or
   .../status-by-order/:merchantOrderId) — status moves
   pending → completed.
```

For Zapper deposits, the requested fee is additional to the provider-computed fee. Zapper receives the gross `amount` unchanged. The wallet receives `amount - requested fee - provider fee`. Your requested fee goes to tenant fee revenue account `4010` and the provider fee to Spendl's transaction fee account `4000` (see [Journal Conventions](#journal-conventions)). Spendl validates a positive net amount before it creates the HPP session.

#### Zapper Withdrawal Flow (scan-to-pay)

```
1. Tenant → POST /api/wallet/withdrawal/zapper/decode
   { code }                          # raw scanned merchant QR
   ← { merchantName, amount, isAmountEditable, allowTip, ... }

2. Tenant shows a confirmation screen (merchant, amount, tip).

3. Tenant → POST /api/wallet/withdrawal/zapper
   { code, userId, amount, withdrawalRequestId }

4. Spendl → debits the wallet, submits the payment to Zapper,
   and returns:
   { success: true,
     entity: { paymentReference, customerReference,
               status: "zapper_acked", amount, totalAmount, ... } }

5. Tenant polls
   GET /api/zapper/withdrawal/status/:paymentReference for the
   final Zapper status. If Zapper rejects the payment, Spendl
   automatically reverses the wallet debit.
```

#### Requirements (same as Pay@)

* **Authentication:** Every endpoint requires `Authorization: Bearer <accessToken>` (see [Authentication](#authentication)). The token's tenant identity limits access to tenant data. A tenant can see only its users' sessions and payments. A deposit or withdrawal for a `userId` that is not one of your users returns `403 FORBIDDEN`. The status endpoints take a session, order or payment reference instead of a `userId`, and return `404` for one that does not belong to your tenant.
* **Gross and provider amounts** are positive-integer ZAR cents. On Zapper deposits, the optional public `feeAmount` accepts either integer cents or a decimal ZAR string. See [Wallet Operations](#wallet-operations). Deposit bounds default to `[1000, 500000]`. Withdrawal bounds default to `[5000, 500000]`. Spendl configures both.
* **Idempotency (withdrawal):** `withdrawalRequestId` is the **required** durable idempotency token, such as your own withdrawal request ID. Reusing the same ID returns a paid payment with `idempotentReplay: true`, or `429 SEND_IN_PROGRESS` while it is still processing. It does not debit the wallet again. A failed payment replays as its `422` error instead. Spendl does not permit money movement without idempotency.
* **Idempotency (deposit):** This key is optional. Send `X-Idempotency-Key` or `idempotencyKey` in the body. If you omit both, Spendl generates a key.
* Spendl does **not** retry mutations automatically. You can safely retry a withdrawal with the same `withdrawalRequestId`.

#### POST /api/wallet/deposit/zapper

Create a Zapper HPP deposit session and return the redirect URL.

**Request:**

```http
POST /api/wallet/deposit/zapper HTTP/1.1
Authorization: Bearer <accessToken>
Content-Type: application/json
X-Idempotency-Key: <uuid>          # optional; see Idempotency

{
  "userId": "507f1f77bcf86cd799439011",
  "amount": 50000,                    // ZAR cents (R500.00)
  "feeAmount": 250,                   // optional integer cents (R2.50)
  "returnBaseUrl": "https://tenant.example"  // optional — your frontend origin for post-payment return/cancel URLs
}
```

**Response (200 OK):**

```json
{
  "success": true,
  "entity": {
    "sessionId": "sess-abc123",
    "redirectUrl": "https://gateway.zapper.com/hpp/sess-abc123",
    "merchantOrderId": "b3f1c2d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "amount": 50000,
    "feeAmount": 1750,
    "requestedFeeAmount": 250,
    "providerFeeAmount": 1500,
    "netAmount": 48250
  }
}
```

**Common errors:**

| HTTP | `type`                                                                            | Cause                                                                                                                                                                                                                                       |
| ---- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401  | `NO_AUTH_HEADER` / `INVALID_AUTH_FORMAT` / `INVALID_TOKEN` / `NO_TENANT_ON_TOKEN` | Missing or invalid Bearer token ([Authentication](#authentication))                                                                                                                                                                         |
| 403  | `FORBIDDEN`                                                                       | `userId` is not one of your users. No session is created                                                                                                                                                                                    |
| 422  | `INVALID_FEE_AMOUNT`                                                              | `feeAmount` does not use an accepted format                                                                                                                                                                                                 |
| 422  | `FEE_EXCEEDS_AMOUNT`                                                              | Requested fee plus provider fee leaves no positive net amount                                                                                                                                                                               |
| 422  | `VALIDATION_ERROR`                                                                | Amount outside the configured deposit bounds, or a `userId` that is missing or is not a 24-character hex ID                                                                                                                                 |
| 422  | `IDEMPOTENCY_KEY_MISMATCH`                                                        | The body and header keys differ                                                                                                                                                                                                             |
| 409  | `IDEMPOTENCY_KEY_MISMATCH`                                                        | This idempotency key was already used for a deposit with a different `userId`, `amount` or `feeAmount`                                                                                                                                      |
| 409  | `ZAPPER_INITIATION_PENDING`                                                       | The first request with this key has not finished creating its session. Retry shortly with the same key. If it still returns this after about a minute, use a new key: the first request returned no payment page, so the user cannot pay it |
| 409  | `ZAPPER_INITIATION_PREVIOUSLY_FAILED`                                             | The first request with this key failed. Retry with a new key                                                                                                                                                                                |
| 500  | `INTERNAL_ERROR`                                                                  | Zapper deposits are not set up in this environment, or an unexpected error occurred. Contact Spendl support if it persists                                                                                                                  |
| 502  | `ZAPPER_SESSION_FAILED`                                                           | Zapper gateway temporarily unavailable (retryable)                                                                                                                                                                                          |

***

#### POST /api/wallet/withdrawal/zapper/decode

Decode a Zapper merchant QR code into merchant and invoice data. Show this data on the confirmation screen. This endpoint is read-only. It does not move money.

**Request:**

```http
POST /api/wallet/withdrawal/zapper/decode HTTP/1.1
Authorization: Bearer <accessToken>
Content-Type: application/json

{
  "code": "<raw Zapper QR code string>"
}
```

**Response (200 OK):**

```json
{
  "merchantName": "Coffee Shop",
  "merchantReference": "MERCH-123",
  "currency": "ZAR",
  "amount": 5000,                 // ZAR cents, or null when the amount is editable/open
  "isAmountEditable": false,
  "reference": "ORDER-9",         // merchant order reference, when present
  "orderReferenceEditable": false,
  "orderReferenceRequired": false,
  "allowTip": true,
  "lineItems": []
}
```

**Common errors:**

| HTTP | `type`                                                                            | Cause                                                               |
| ---- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| 401  | `NO_AUTH_HEADER` / `INVALID_AUTH_FORMAT` / `INVALID_TOKEN` / `NO_TENANT_ON_TOKEN` | Missing or invalid Bearer token ([Authentication](#authentication)) |
| 404  | `ZAPPER_CODE_NOT_FOUND`                                                           | The QR code could not be resolved by Zapper                         |
| 502  | `ZAPPER_DECODE_FAILED`                                                            | Zapper Platform temporarily unavailable (retryable)                 |

***

#### POST /api/wallet/withdrawal/zapper

Make a scan-to-pay payment. This operation debits the user's wallet. It pays the scanned merchant through Zapper.

**Request:**

```http
POST /api/wallet/withdrawal/zapper HTTP/1.1
Authorization: Bearer <accessToken>
Content-Type: application/json

{
  "code": "<raw Zapper QR code string>",
  "userId": "507f1f77bcf86cd799439011",
  "amount": 25000,                       // ZAR cents (R250.00)
  "withdrawalRequestId": "tenant-wr-abc-123",  // REQUIRED durable idempotency token
  "tipAmount": 0,                        // optional, ZAR cents
  "orderReference": "ORDER-9",           // optional
  "merchantName": "Coffee Shop",         // optional, display-only (≤80 chars)
  "firstName": "John",                   // optional cardholder details
  "lastName": "Doe"
}
```

**Response (200 OK):**

```json
{
  "success": true,
  "entity": {
    "customerReference": "tenant-wr-abc-123",
    "paymentReference": "ZPR123456789",
    "status": "zapper_acked",
    "amount": 25000,
    "tipAmount": 0,
    "totalAmount": 25000,
    "journalEntryId": "6650a1b2c3d4e5f6a7b8c9d0"
  }
}
```

**Idempotent replay** — Sending the same `withdrawalRequestId` never debits the wallet again. A paid payment is returned as below. A payment that is still processing returns `429 SEND_IN_PROGRESS` with `data.idempotentReplay: true` and its `data.status`: keep the `withdrawalRequestId` and check again shortly, and treat it as neither paid nor failed. A failed payment returns its `422` error again (`ZAPPER_PAYMENT_FAILED`, or `ZAPPER_WALLET_REFUND_FAILED` while the refund is outstanding). The same `withdrawalRequestId` with a different QR code, amount or tip returns `409 IDEMPOTENCY_KEY_MISMATCH`:

```json
{
  "success": true,
  "idempotentReplay": true,
  "entity": {
    "paymentId": "6650a1b2c3d4e5f6a7b8c9d0",
    "status": "zapper_acked",
    "paymentReference": "ZPR123456789",
    "customerReference": "tenant-wr-abc-123"
  }
}
```

**Common errors:**

| HTTP | `type`                                                                            | Cause                                                                                                                                                                                                                                                                                           |
| ---- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401  | `NO_AUTH_HEADER` / `INVALID_AUTH_FORMAT` / `INVALID_TOKEN` / `NO_TENANT_ON_TOKEN` | Missing or invalid Bearer token ([Authentication](#authentication))                                                                                                                                                                                                                             |
| 403  | `FORBIDDEN`                                                                       | `userId` is not one of your users. Nothing is debited                                                                                                                                                                                                                                           |
| 403  | `ACCOUNT_RESTRICTED`                                                              | The user's account is restricted from sending money                                                                                                                                                                                                                                             |
| 409  | `IDEMPOTENCY_KEY_MISMATCH`                                                        | This `withdrawalRequestId` was already used for a different QR code, amount or tip. Use a new `withdrawalRequestId` for a new payment                                                                                                                                                           |
| 429  | `SEND_IN_PROGRESS`                                                                | `data.idempotentReplay: true`: this payment is still processing. `data.idempotentReplay: false`: another payment by this user to the same QR code is still processing, so this one was not started. In both cases nothing new was debited; keep the `withdrawalRequestId` and try again shortly |
| 422  | `VALIDATION_ERROR`                                                                | Missing `code` or `withdrawalRequestId`, a `userId` that is not a 24-character hex ID, or an amount outside the configured withdrawal bounds                                                                                                                                                    |
| 422  | `BELOW_MINIMUM_AMOUNT` / `EXCEEDS_MAXIMUM_AMOUNT`                                 | The amount, including the tip, is outside Zapper's own bounds                                                                                                                                                                                                                                   |
| 422  | `INSUFFICIENT_FUNDS`                                                              | The wallet balance is below the total amount                                                                                                                                                                                                                                                    |
| 422  | `ZAPPER_PAYMENT_FAILED`                                                           | The payment failed. Nothing was taken, or the debit was returned to the wallet. Also returned when you replay a failed payment, or one refunded later. Use a new `withdrawalRequestId` for a new attempt.                                                                                       |
| 422  | `ZAPPER_WALLET_REFUND_FAILED`                                                     | The payment failed, but the amount could not be returned to the wallet yet. Do not retry; contact support. Also returned on a replay while the refund is outstanding.                                                                                                                           |
| 502  | `ZAPPER_WITHDRAWAL_INITIATE_FAILED`                                               | The payment service could not process the request. Your input did not cause this. Keep the `withdrawalRequestId` when you try again, so the wallet is never debited twice; contact support if it continues                                                                                      |
| 503  | `ZAPPER_TRANSPORT_ERROR`                                                          | A network error occurred when the API submitted the payment to Zapper after the debit. The API reconciles this automatically. You can retry.                                                                                                                                                    |

Any other `4xx` returned once the payment has started (for example `INSUFFICIENT_FUNDS`) moved nothing, but spends the `withdrawalRequestId`: a retry returns `ZAPPER_PAYMENT_FAILED`.

***

#### GET /api/zapper/deposit/status/:sessionId

Look up a deposit session's status by its HPP `sessionId`.

**Response (200 OK):**

```json
{
  "sessionId": "sess-abc123",
  "merchantOrderId": "b3f1c2d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "userId": "507f1f77bcf86cd799439011",
  "amountCents": 50000,
  "requestedFeeCents": 250,
  "providerFeeCents": 1500,
  "feeCents": 1750,
  "netCents": 48250,
  "status": "pending",
  "paymentReference": null,
  "paymentStatus": null,
  "createdAt": "2026-07-06T10:00:00.000Z"
}
```

**Status values:** `pending`, `completed`, `failed`, `expired`. Returns `404 DEPOSIT_NOT_FOUND` if no session with that id exists for your tenant.

***

#### GET /api/zapper/deposit/status-by-order/:merchantOrderId

This endpoint has the same response format as `GET /api/zapper/deposit/status/:sessionId`. It uses the `merchantOrderId` that Spendl created before Zapper returned a `sessionId`. Use this endpoint on the landing page that the user returns to after payment. That page contains only the order ID.

***

#### GET /api/zapper/withdrawal/status/:paymentReference

Get a scan-to-pay payment's status by its Zapper `paymentReference`. The `POST /api/wallet/withdrawal/zapper` response returns this value. The endpoint is tenant-scoped. You can resolve only your tenant's references.

**Response (200 OK):**

```json
{
  "paymentReference": "ZPR123456789",
  "status": "success",
  "paymentMethodType": "External",
  "processedAmount": 25000
}
```

Returns `404 PAYMENT_NOT_FOUND` if no payment with that reference exists for your tenant.

***

### Hosted Checkout Deposits

A hosted checkout deposit tops up a user's wallet on a hosted payment page. Spendl creates a checkout session and returns `redirectUrl`. Send the user to that URL. The user pays by card, Capitec Pay or bank transfer on the hosted page. After the payment is confirmed, Spendl credits the user's wallet asynchronously. Poll the session status until `credited` is `true`.

All amounts use **ZAR cents** and must be positive integers. For example, `R125.00` is `12500`.

#### Hosted Checkout Deposit Flow

```
1. Tenant → POST /api/wallet/deposit/checkout
   X-Idempotency-Key: <your key>
   { userId, amount, feeAmount? }

2. Spendl → returns:
   { success: true,
     entity: { sessionId, redirectUrl, amount,
               requestedFeeAmount, maxFeeAmount, minNetAmount, ... } }

3. Tenant redirects the user to `redirectUrl` (the hosted payment page).

4. The user chooses card, Capitec Pay or bank transfer and pays.

5. Spendl confirms the payment and credits the wallet asynchronously.
   Tenant polls GET /api/wallet/deposit/checkout/status/:sessionId
   until `credited: true` (or a final `failed` / `expired` /
   `cancelled`). `wallet.incoming_credit` is also sent when the
   wallet is credited, if you have that webhook configured.
```

**Fees.** The optional `feeAmount` is your fee. It is additional to the payment fee, which depends on the payment method the user chooses on the hosted page. Spendl checks, before it creates the session, that the most expensive method still leaves a positive net amount. The create response therefore returns the bounds (`maxProviderFeeAmount`, `maxFeeAmount`, `minNetAmount`). The status response returns the actual `feeAmount` and `netAmount` once the wallet is credited. The wallet receives `amount - feeAmount`.

**Return page.** After paying, the user is returned to the return page Spendl configured for your tenant during onboarding. This API does not accept a return URL. Do not rely on query parameters on the return page. Track the `sessionId` you received from the create call, and read its status.

#### Requirements

* **Authentication:** Every endpoint requires `Authorization: Bearer <accessToken>`. `POST` needs the `write` scope and `GET` needs the `read` scope. The token's tenant limits access: you can create sessions only for your users and read only your sessions.
* **Availability:** Spendl enables hosted checkout per tenant. A tenant without it gets a `CHECKOUT_SESSION_FAILED` error. Contact Spendl support if it persists.
* **KYC:** The user's KYC must be `Approved`. Other users get `403 KYC_REQUIRED`.
* **Amounts:** `amount` is a positive integer in ZAR cents. Spendl configures the allowed range per tenant. An amount outside it returns `422 VALIDATION_ERROR` with `data: { field: "amount", min, max }`. `feeAmount` accepts integer cents or a decimal ZAR string with one or two fraction digits, for example `"2.50"`. See [Wallet Operations](#wallet-operations).
* **Idempotency (required):** Send `X-Idempotency-Key` or `idempotencyKey` in the body. If you send both, they must match. A key is 8–128 characters of letters, digits and `_ . : -`. One key creates one session for your tenant. Retrying with the same key, user, amount and fee returns the same session with `idempotentReplay: true`, so you can always retry a timeout safely. The same key with a different user, amount or fee returns `409 IDEMPOTENCY_KEY_MISMATCH`. A replay returns the session as it was created, even after it has expired or been paid. Use a new key for a new top-up.
* Spendl does not retry mutations automatically.
* If a retry with the same key arrives while the first request is still running, it can return `503 CHECKOUT_SESSION_UNCONFIRMED`. Wait a moment and retry with the same key.

#### POST /api/wallet/deposit/checkout

Create a hosted checkout deposit session and return the hosted payment page URL.

**Request:**

```http
POST /api/wallet/deposit/checkout HTTP/1.1
Authorization: Bearer <accessToken>
Content-Type: application/json
X-Idempotency-Key: topup-2026-10-10-0001     # required (or idempotencyKey in the body)

{
  "userId": "507f1f77bcf86cd799439011",
  "amount": 50000,                    // ZAR cents (R500.00)
  "feeAmount": 250                    // optional, integer cents (R2.50) or "2.50"
}
```

**Response (200 OK):**

```json
{
  "success": true,
  "entity": {
    "sessionId": "chk_6dbffaa5c1192ee6fc266a4f66fb52a3",
    "redirectUrl": "https://<hosted payment page>/...",
    "amount": 50000,
    "requestedFeeAmount": 250,
    "maxProviderFeeAmount": 1500,
    "maxFeeAmount": 1750,
    "minNetAmount": 48250,
    "createdAt": "2026-10-10T08:00:00.000Z"
  }
}
```

| Field                  | Type            | Description                                                                      |
| ---------------------- | --------------- | -------------------------------------------------------------------------------- |
| `sessionId`            | string          | Spendl checkout session ID (`chk_` + 32 hex characters). Read the status with it |
| `redirectUrl`          | string          | The hosted payment page. Send the user here. Treat it as opaque                  |
| `amount`               | integer         | Gross amount in ZAR cents                                                        |
| `requestedFeeAmount`   | integer         | Your fee in ZAR cents (`0` when you sent none)                                   |
| `maxProviderFeeAmount` | integer \| null | The highest payment fee any method can charge                                    |
| `maxFeeAmount`         | integer \| null | `requestedFeeAmount + maxProviderFeeAmount`                                      |
| `minNetAmount`         | integer \| null | The lowest amount the wallet can receive                                         |
| `createdAt`            | string          | When the session was created (ISO 8601)                                          |

A same-key replay adds `"idempotentReplay": true` at the top level and returns the same `sessionId`.

**Errors:**

| HTTP                  | `type`                                                     | Cause                                                                                                                                                                                                                    | Retry?            |
| --------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------- |
| 401                   | `NO_AUTH_HEADER` / `INVALID_AUTH_FORMAT` / `INVALID_TOKEN` | Missing or invalid Bearer token ([Authentication](#authentication))                                                                                                                                                      | No                |
| 403                   | `INSUFFICIENT_SCOPE`                                       | The key has no `write` scope                                                                                                                                                                                             | No                |
| 403                   | `FORBIDDEN`                                                | The user is not one of your users                                                                                                                                                                                        | No                |
| 403                   | `KYC_REQUIRED`                                             | The user's KYC is not `Approved`                                                                                                                                                                                         | No                |
| 409                   | `IDEMPOTENCY_KEY_MISMATCH`                                 | The key was already used for a different user, amount or fee                                                                                                                                                             | No, use a new key |
| 422                   | `MISSING_IDEMPOTENCY_KEY`                                  | No idempotency key                                                                                                                                                                                                       | No                |
| 422                   | `IDEMPOTENCY_KEY_MISMATCH`                                 | The header and body keys differ                                                                                                                                                                                          | No                |
| 422                   | `VALIDATION_ERROR`                                         | Missing or malformed `userId` (a 24-character hex id), a non-integer or non-positive `amount`, an amount outside the allowed range, or a key of the wrong length or characters                                           | No                |
| 422                   | `INVALID_FEE_AMOUNT`                                       | `feeAmount` does not use an accepted format                                                                                                                                                                              | No                |
| 422                   | `FEE_EXCEEDS_AMOUNT`                                       | The fees leave no positive amount to credit                                                                                                                                                                              | No                |
| 502 / 503             | `CHECKOUT_SESSION_FAILED`                                  | The session could not be created. The `message` says how to retry (see below)                                                                                                                                            | See below         |
| 500 / 502 / 503 / 504 | `CHECKOUT_SESSION_UNCONFIRMED`                             | Spendl could not confirm whether the session was created (for example a timeout or a lost connection). It is never a success. Retry with the same key: you get the session if it was created, or a new one if it was not | Yes, same key     |

A timeout before the API answers (for example a `504` with type `REQUEST_TIMEOUT`, or no response at all) has the same meaning as `CHECKOUT_SESSION_UNCONFIRMED`: retry with the same key.

`CHECKOUT_SESSION_FAILED` has one of three fixed messages. Nothing was created in any of these cases:

| `message`                                                                                                               | Meaning                                                                                                                         | Retry?        |
| ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `The checkout session could not be created. Retry with the same idempotency key.`                                       | A temporary failure                                                                                                             | Yes, same key |
| `The checkout session could not be created. Retry with a new idempotency key; contact Spendl support if this persists.` | The payment provider refused the session, or returned one Spendl could not use. A retry with the same key gets the same failure | Yes, new key  |
| `The checkout session could not be created. Contact Spendl support if this persists.`                                   | A configuration problem on Spendl's side                                                                                        | No            |

***

#### GET /api/wallet/deposit/checkout/status/:sessionId

Read a hosted checkout session's status. `credited: true` is the success signal: it is set only once the wallet credit is booked, and it never goes back to `false`.

**Response (200 OK):**

```json
{
  "success": true,
  "entity": {
    "sessionId": "chk_6dbffaa5c1192ee6fc266a4f66fb52a3",
    "status": "completed",
    "credited": true,
    "amount": 50000,
    "requestedFeeAmount": 250,
    "maxFeeAmount": 1750,
    "minNetAmount": 48250,
    "feeAmount": 1250,
    "netAmount": 48750,
    "paymentMethod": "card",
    "completedAt": "2026-10-10T08:05:00.000Z",
    "createdAt": "2026-10-10T08:00:00.000Z"
  }
}
```

| Field                          | Type            | Description                                                                                                               |
| ------------------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `status`                       | string          | `pending`, `completed`, `failed`, `expired` or `cancelled`. A paid session is `pending` until the wallet credit is booked |
| `credited`                     | boolean         | `true` once the wallet is credited. The only success signal                                                               |
| `amount`                       | integer         | Gross amount in ZAR cents                                                                                                 |
| `requestedFeeAmount`           | integer         | Your fee in ZAR cents                                                                                                     |
| `maxFeeAmount`, `minNetAmount` | integer \| null | The fee bounds from the create response                                                                                   |
| `feeAmount`                    | integer \| null | Total fee charged (your fee plus the payment fee). `null` until credited                                                  |
| `netAmount`                    | integer \| null | The amount credited to the wallet. `null` until credited                                                                  |
| `paymentMethod`                | string \| null  | `card`, `capitec_pay`, `bank_transfer` or `other`. `null` until credited. New values may be added                         |
| `completedAt`                  | string \| null  | When the wallet was credited. `null` until credited                                                                       |
| `createdAt`                    | string          | When the session was created                                                                                              |

`failed`, `expired` and `cancelled` mean the user did not complete a payment on that session. In rare cases Spendl support can still credit such a session after an investigation, so keep polling or rely on `wallet.incoming_credit` if the user says they paid.

**Errors:**

| HTTP      | `type`                                                     | Cause                                                               | Retry? |
| --------- | ---------------------------------------------------------- | ------------------------------------------------------------------- | ------ |
| 401       | `NO_AUTH_HEADER` / `INVALID_AUTH_FORMAT` / `INVALID_TOKEN` | Missing or invalid Bearer token ([Authentication](#authentication)) | No     |
| 404       | `CHECKOUT_SESSION_NOT_FOUND`                               | No session with that ID exists for your tenant                      | No     |
| 502 / 504 | `CHECKOUT_STATUS_FETCH_FAILED`                             | The status could not be read right now                              | Yes    |

***

### Remittance API

Use the Remittance API to send cross-border transfers from a user's Spendl wallet. Send funds to a supported mobile wallet, bank account, or cash-pickup partner. All endpoints require a Bearer token. All endpoints are tenant-scoped.

Spendl enables remittances for each tenant. Until they are enabled for you, `POST /api/remittance/quote`, `/name-check`, `/validate`, `/send` and `/transactions/:transactionId/retry-edit` return `403 REMITTANCE_NOT_ENABLED`, and nothing is quoted, checked or sent. Ask your Spendl account manager to enable them. Corridors, banks, transactions, status, statistics and user limits keep working, so you can still see earlier transfers. If the API cannot confirm that remittances are enabled, these requests return `503 REMITTANCE_UNAVAILABLE`, and you can retry.

#### Flow Coverage

The API supports the complete transfer lifecycle:

* corridor and bank discovery;
* indicative quotes;
* recipient validation and advisory wallet name checks;
* wallet debit and currency conversion;
* submission to the destination network and status webhooks;
* status tracking and transaction history;
* settlement and refunds.

The following rules apply:

| Area                        | Behaviour                                                                                                                                                                                                                                                                   |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Rail validation             | Wallet, bank, and cash-pickup sends need the documented rail-specific recipient fields before any wallet debit or currency trade                                                                                                                                            |
| Corridor routing            | The API selects the destination currency, payment type, partner code, bank, and cash-pickup partner from active corridor discovery data                                                                                                                                     |
| Beneficiary data            | The API exposes only corridors that this contract's recipient fields support. Corridor configuration contains destination-specific requirements.                                                                                                                            |
| Destination amount encoding | `receiveAmount` uses a fixed two-decimal transport scale for every destination currency. Divide by 100 to get major units.                                                                                                                                                  |
| Funding and dispatch        | A successful send debits the wallet and creates a `pending` transaction. Spendl then submits it to the destination network, usually within 15 minutes.                                                                                                                      |
| Failure remediation         | A destination failure becomes `failed`. When the recipient details caused it, you can [retry it](#retry-failed-transfer) with them corrected. Spendl handles other failures, and retries or refunds a transfer only after it confirms that duplicate delivery cannot occur. |
| Finality                    | The destination network's confirmation sets the final status. If a confirmation is delayed, Spendl checks the transfer's status itself.                                                                                                                                     |

#### Conventions

* `sendAmountZar`, `feeAmountZar`, `convertibleAmountZar`, and `totalDebitZar` are positive integer **ZAR cents**. For example, `10000` is R100.00.
* `receiveAmount` is a positive integer. It equals the destination amount in major units multiplied by 100 and rounded to the nearest integer. For two-decimal currencies, `250000` KES is KSh2,500.00. This value matches the ISO minor-unit representation. For zero-decimal currencies, `500000` XOF is 5,000 XOF. Always divide this field by 100 for display. Do not treat it as an ISO minor-unit value for zero-decimal currencies.
* Country codes use uppercase ISO 3166-1 alpha-2 values such as `KE`; currency codes use uppercase ISO 4217 values such as `KES`.
* Recipient phone numbers use international digits without a leading `+`, for example `254712345678`.
* `paymentType` can be `wallet`, `bank`, or `cash_pickup`. Availability depends on the destination. Use only values in the corridor's `paymentTypes` array.
* Each user can request one quote every two seconds. A quote is valid for at most 50 seconds by default and can be shorter; use the quote's own `expiresIn` for the time left (see [Get Quote](#get-quote)). A quote stays indicative until send processing accepts it.
* Always supply a unique idempotency key for a send. Use `idempotencyKey` in the request body or `X-Idempotency-Key`.
* The send is rejected with `422 MISSING_IDEMPOTENCY_KEY` when neither form is supplied. If both are supplied, their values must match or the API returns `422 IDEMPOTENCY_KEY_MISMATCH`.
* The sender must belong to the selected tenant and have KYC status `Approved`, and their KYC data must hold the fields in [Sender Profile](#sender-profile). The API reads these values from the Spendl profile. Do not send them in the remittance request.
* `partnerCode` is routing data, not a display label. Use the value returned for the selected corridor. Do not accept a value entered by a user.

#### Sender Profile

A send reads the sender's details from the user's KYC data, `kycDetails.kycData`. Before anything moves, a send is refused with `404 USER_NOT_FOUND`, `403 ACCOUNT_RESTRICTED` (the account is `suspended`, `inactive` or `deleted`, or is a tenant wallet that is not active), `403 KYC_NOT_APPROVED` (KYC status is not `Approved`), or `422 INCOMPLETE_KYC` (a field below is missing or blank). `data.missingFields` lists the missing fields by the names in the last column, or is `["all"]` when the user has no `kycData` object.

| `kycData` field        | Flat-format field        | `missingFields` name   |
| ---------------------- | ------------------------ | ---------------------- |
| `name`                 | `name`                   | `firstName`            |
| `surname`              | `surname`                | `lastName`             |
| `phone`                | `phone`                  | `phone`                |
| `dob`                  | `birth_date`             | `dateOfBirth`          |
| `city`                 | `city_id`                | `city`                 |
| `idNumber`             | `id_number`              | `idNumber`             |
| `identityType`         | `identity_type`          | `identityType`         |
| `identityIssueCountry` | `identity_issue_country` | `identityIssueCountry` |

`422 KYC_INCOMPLETE` means the same as `INCOMPLETE_KYC`; its `data.missingFields` can name the identity type as `idType` and the phone as `msisdn`.

Send `phone` as an international number, for example `27821234567`, and `identityIssueCountry` as a two-letter ISO 3166-1 code, for example `ZA`. The phone is read only from `kycData.phone`; ingestion ignores `userDetails.phone`. Of these fields, ingestion requires only `name`, `surname` and `dob` (and `identityType` when you send `productType`), so send the other sender fields when you ingest a user who will send remittances. If you add `identityType` (with `productType`), upload the [FICA documents](#fica-identity-requirements) that pair needs, or verification will not run.

To add a missing `phone`, `city` or `identityIssueCountry` to an approved user, use [Fill Missing KYC Details](#fill-missing-kyc-details): it does not restart KYC, so after a `200` the user can send straight away. To add any other missing field, send the user's complete KYC data in one [Replace KYC Details](#replace-kyc-details) PATCH, which restarts KYC. The outcome can be a review or a rejection. Before you retry a send, wait until [Check Ingestion Status](#check-ingestion-status) shows `kycStatus: "Approved"` again (it shows `Pending` from the PATCH onwards). A send tried too early is refused (`403 KYC_NOT_APPROVED` or `422 INCOMPLETE_KYC`) before anything is debited.

For a user created from a [Sumsub share token](#create-user-from-sumsub-share-token), the identity fields come from Sumsub. One that Sumsub left empty, such as `identityIssueCountry`, is listed in `sumsub.unmappedIdentityFields` and cannot be added through the API; contact support.

#### Integration Flow

1. Confirm that the sender has KYC approval, the [sender profile](#sender-profile) fields, and enough wallet funds for the full send amount.
2. Call `GET /api/remittance/corridors` and present the returned destinations and payment types.
3. Keep the selected corridor's `toCurrency` and `partnerCode`. Do not construct or hard-code these values.
4. For a bank transfer, call `GET /api/remittance/banks` and use the selected bank's `mfsBankCode` as the recipient bank code.
5. Request a quote using the selected corridor and payment type.
6. Collect every field required for the payment type. Then validate the recipient. You can also run a separate name check for a mobile-wallet recipient.
7. Show the quote, recipient, fee, receive amount, destination currency, and asynchronous delivery notice. Ask the user to confirm.
8. Initiate the send with the quote ID and a durable idempotency key. A successful response means the wallet was debited and the transfer was queued. It does not mean the recipient was paid.
9. Use the transaction list, detail, and status endpoints until the transfer reaches a terminal status. Customers cannot cancel a transfer; to stop one, contact Spendl support. If a transfer becomes `failed`, see [Retry Failed Transfer](#retry-failed-transfer).

#### Discover Corridors

Use this endpoint as the authoritative source for destination setup. It returns enabled countries and currencies. It also returns valid `paymentType`, `partnerCode`, wallet operator, and cash-pickup partner options.

```
GET /api/remittance/corridors
GET /api/remittance/corridors?paymentType=bank
```

| Parameter     | In    | Required | Description                                                         |
| ------------- | ----- | -------- | ------------------------------------------------------------------- |
| `paymentType` | Query | No       | Return only corridors supporting `wallet`, `bank`, or `cash_pickup` |

**Response (200 OK):**

```json
{
  "items": [
    {
      "_id": "66a7f1c9b45e8d0012345670",
      "toCountry": "KE",
      "toCountryName": "Kenya",
      "toCurrency": "KES",
      "dialCode": "254",
      "partnerCode": "KE-MPESA",
      "paymentTypes": ["wallet", "bank"],
      "operators": ["M-PESA", "Airtel Money"],
      "cashPickupPartners": [],
      "limits": {
        "minPerTxZar": 5000,
        "maxPerTxZar": 5000000,
        "maxDailyZar": 10000000,
        "minPerTxLocal": 10000,
        "maxPerTxLocal": 50000000,
        "maxDailyLocal": 100000000,
        "maxWeeklyLocal": 300000000,
        "maxMonthlyLocal": 1000000000
      }
    }
  ],
  "total": 1
}
```

Use the discovery fields as follows:

| Field                | Client usage                                                                                      |
| -------------------- | ------------------------------------------------------------------------------------------------- |
| `toCountry`          | Send as `toCountry` on quote/send and `countryCode` on validation/name check                      |
| `toCurrency`         | Send as `toCurrency` on quote/send and `currency` for bank validation                             |
| `partnerCode`        | Send unchanged on validation and send                                                             |
| `paymentTypes`       | Render only these rails for the selected destination                                              |
| `operators`          | Optional wallet-operator choices for display; the recipient MSISDN remains the routing identifier |
| `cashPickupPartners` | Render these choices for `cashPickupPartner`; send the exact selected value                       |
| `dialCode`           | Assist MSISDN entry and normalization                                                             |
| `limits`             | Constrain amount entry before requesting a quote                                                  |

Do not keep a hard-coded catalogue of payment types or partner codes. Corridor configuration can differ by tenant and destination.

#### List Destination Banks

```
GET /api/remittance/banks?country=KE
```

| Parameter | In    | Required | Description                         |
| --------- | ----- | -------- | ----------------------------------- |
| `country` | Query | Yes      | Two-letter destination country code |

**Response (200 OK):**

```json
{
  "country": "KE",
  "banks": [
    {
      "bankName": "Example Bank Kenya",
      "mfsBankCode": "001",
      "domBankCode": "01",
      "bic": "EXAMKENA",
      "iban": "",
      "currencyCode": "KES",
      "limits": {
        "minPerTx": 10000,
        "maxPerTx": 50000000,
        "maxDaily": 100000000,
        "maxWeekly": 300000000,
        "maxMonthly": 1000000000
      }
    }
  ]
}
```

Call this endpoint only when the selected corridor includes `bank` in `paymentTypes`. For validation, use `mfsBankCode` as `bankCode`. For send, use it as `recipientBankCode`. `domBankCode`, `bic`, and `iban` are reference attributes. They can be empty when they do not apply.

Returns `404 CORRIDOR_NOT_FOUND` when the country has no active corridor.

#### Get Quote

```
POST /api/remittance/quote
Content-Type: application/json
```

```json
{
  "userId": "user-123",
  "toCountry": "KE",
  "toCurrency": "KES",
  "sendAmountZar": 10000,
  "paymentType": "wallet"
}
```

**Response (200 OK):**

```json
{
  "quoteId": "QT-20260728-SPEN-001",
  "sendAmountZar": 10000,
  "feeAmountZar": 500,
  "convertibleAmountZar": 9500,
  "totalDebitZar": 10000,
  "receiveAmount": 67750,
  "receiveCurrency": "KES",
  "combinedFxRate": 7.1316,
  "partnerCode": "KE-MPESA",
  "expiresAt": "2026-07-28T12:00:50.000Z",
  "expiresIn": 50,
  "rateBreakdown": {
    "zarToUsdcRate": 18.42,
    "usdToDestRate": 131.36,
    "destinationRateTimestamp": "2026-07-28T09:00:00.000Z"
  },
  "userLimits": {
    "dailyLimitItt": 500000,
    "dailyUsedItt": 150000,
    "dailyRemainingItt": 350000,
    "dailyResetAt": "2026-07-28T22:00:00.000Z",
    "monthlyLimitItt": 2500000,
    "monthlyUsedItt": 800000,
    "monthlyRemainingItt": 1700000,
    "monthlyResetAt": "2026-07-31T22:00:00.000Z"
  }
}
```

`userId` identifies the sender for the per-user quote limit. It also binds the quote to the sender. The service deducts the fee from the converted amount: `convertibleAmountZar = sendAmountZar - feeAmountZar`.

`userLimits` is the same snapshot of remaining capacity that `GET /api/remittance/user-limits` returns. Use it to show the sender's remaining daily and monthly capacity next to the quote without a second request. The value can be `null` when Spendl cannot calculate the limits. Then do not show a remaining-capacity figure, and rely on the send's limit check.

A quote does not reserve funds or check the wallet balance. The service checks the balance and KYC when you initiate the send. The response `partnerCode` confirms the selected corridor route. Send the same value during validation and send.

`expiresAt` is when the quote expires. The send operation checks the quote against the same clock. A send after `expiresAt` returns `409 QUOTE_EXPIRED`. `expiresIn` is the number of seconds that remain at the moment of the response. Use `expiresIn` for a client-side countdown. It is not affected by clock differences between your host and Spendl. A quote is valid for at most 50 seconds by default. Spendl may raise this limit to at most 59 seconds. The exchange rate behind a quote can expire sooner, so a quote often lasts less. Each quote's own `expiresIn` is authoritative; do not assume a fixed period.

Common quote errors are:

| Code | Type                          | Cause                                                                                                                            |
| ---- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| 403  | `REMITTANCE_NOT_ENABLED`      | Remittances are not enabled for your tenant                                                                                      |
| 429  | `QUOTE_RATE_LIMITED`          | The user requested quotes too quickly                                                                                            |
| 404  | `CORRIDOR_NOT_FOUND`          | No active corridor matches the request                                                                                           |
| 422  | `AMOUNT_EXCEEDS_LIMIT`        | The amount is above the allowed limit                                                                                            |
| 422  | `CORRIDOR_LIMIT_EXCEEDED`     | The amount is above the corridor limit                                                                                           |
| 422  | `CORRIDOR_MINIMUM_NOT_MET`    | The amount is below the corridor minimum                                                                                         |
| 422  | `AMOUNT_TOO_LOW`              | The calculated fee consumes the transfer amount                                                                                  |
| 422  | `USER_DAILY_LIMIT_EXCEEDED`   | The send exceeds the user's daily cap                                                                                            |
| 422  | `USER_MONTHLY_LIMIT_EXCEEDED` | The send exceeds the user's monthly cap                                                                                          |
| 503  | `RATE_NOT_AVAILABLE`          | No exchange rate is available                                                                                                    |
| 503  | `RATE_STALE`                  | The available exchange rate is too old                                                                                           |
| 503  | `UPSTREAM_STALE_CLOCK`        | The quote would expire too soon to use. You can retry.                                                                           |
| 503  | `FX_PROVIDER_UNAVAILABLE`     | No live exchange rate could be obtained. You can retry.                                                                          |
| 503  | `REMITTANCE_UNAVAILABLE`      | The API could not confirm that remittances are enabled for your tenant, or the remittance service is unavailable. You can retry. |

#### Recipient Name Check

The name check is advisory and applies to mobile-wallet recipients. A low score does not stop a transfer.

```
POST /api/remittance/name-check
Content-Type: application/json
```

```json
{
  "msisdn": "254712345678",
  "countryCode": "KE",
  "firstName": "Amina",
  "lastName": "Kamau"
}
```

**Response (200 OK):**

```json
{
  "responseCode": "SUCCESS",
  "responseMsg": "Name check completed",
  "fuzzyCompare": 94,
  "recipientName": "AMINA KAMAU",
  "passed": true
}
```

`fuzzyCompare` is a similarity percentage from 0 to 100. If the name check could not be completed, the API returns `passed: false` with `responseCode: "ERROR"` and `responseMsg: "Name check could not be completed"`. You can continue or ask for manual confirmation. A slow name check can time out and return `502 UPSTREAM_NETWORK_ERROR` instead; you can retry.

If remittances are not enabled for your tenant, the name check returns `403 REMITTANCE_NOT_ENABLED`, or `503 REMITTANCE_UNAVAILABLE` when the API cannot confirm it.

#### Validate Recipient

```
POST /api/remittance/validate
Content-Type: application/json
```

Fields common to all payment types:

| Field           | Required | Description                                                                                                   |
| --------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| `paymentType`   | Yes      | `wallet`, `bank`, or `cash_pickup`                                                                            |
| `partnerCode`   | Yes      | Destination partner returned by the quote/corridor configuration                                              |
| `countryCode`   | Yes      | Two-letter destination country code                                                                           |
| `recipientName` | No       | Claimed recipient name, first name then last name; for wallet and cash pickup, enables an advisory name check |

Payment rail fields:

| Payment type  | Required fields             | Optional fields                                |
| ------------- | --------------------------- | ---------------------------------------------- |
| `wallet`      | `msisdn`                    | `recipientName`                                |
| `cash_pickup` | `msisdn`                    | `recipientName`                                |
| `bank`        | `accountNumber`, `bankCode` | `currency`, `recipientMsisdn`, `recipientName` |

**Mobile-wallet example:**

```json
{
  "paymentType": "wallet",
  "partnerCode": "KE-MPESA",
  "countryCode": "KE",
  "msisdn": "254712345678",
  "recipientName": "Amina Kamau"
}
```

**Bank example:**

```json
{
  "paymentType": "bank",
  "partnerCode": "KE-BANK",
  "countryCode": "KE",
  "accountNumber": "1234567890",
  "bankCode": "001",
  "currency": "KES",
  "recipientName": "Amina Kamau"
}
```

**Response (200 OK):**

```json
{
  "valid": true,
  "recipientName": "AMINA KAMAU",
  "message": "Recipient account validated",
  "nameCheck": {
    "fuzzyCompare": 94,
    "recipientName": "AMINA KAMAU",
    "passed": true
  }
}
```

For wallet and cash-pickup validation, the API runs the advisory name check only when the account is valid and `recipientName` has at least two words (the first is used as the first name, the rest as the last name). `nameCheck` is present only when that check ran and returned a result; `fuzzyCompare` and `passed` mean the same as in [Recipient Name Check](#recipient-name-check). If the name check returns an error, validation still returns `200`, without `nameCheck`. A missing `nameCheck` therefore means the name was not checked, not that it did not match. Bank validation never includes `nameCheck`.

Send `msisdn` in international format: 7 to 15 digits, not starting with `0`, optionally with a leading `+`. For a wallet, it must start with the destination country's dialling code, for example `254` for Kenya. For a wallet or cash pickup, any other value returns `422 INVALID_RECIPIENT_MSISDN`; bank validation does not check the number. If the account lookup fails, validation returns `503 VALIDATION_SERVICE_UNAVAILABLE`; you can retry. If the account lookup or name check is slow, validation can return `502 UPSTREAM_NETWORK_ERROR`; you can retry. If remittances are not enabled for your tenant, validation returns `403 REMITTANCE_NOT_ENABLED`, or `503 REMITTANCE_UNAVAILABLE` when the API cannot confirm it.

#### Initiate Send

```
POST /api/remittance/send
Content-Type: application/json
X-Idempotency-Key: remit-user-123-20260728-001
```

```json
{
  "userId": "user-123",
  "toCountry": "KE",
  "toCurrency": "KES",
  "sendAmountZar": 10000,
  "paymentType": "wallet",
  "partnerCode": "KE-MPESA",
  "recipientName": "Amina",
  "recipientSurname": "Kamau",
  "recipientMsisdn": "254712345678",
  "purposeOfTransfer": "PT1",
  "sourceOfFunds": "SF1",
  "termsAcceptedAt": true,
  "quoteId": "QT-20260728-SPEN-001"
}
```

`termsAcceptedAt` is required and must be the JSON boolean `true` (not a timestamp): the sender's confirmation of the remittance terms for this transfer. Spendl records its own time of acceptance. A missing, `null` or `false` value returns `422 TERMS_NOT_ACCEPTED`. Any other value, such as a date string, `"true"` or `1`, returns `422 VALIDATION_ERROR`. Neither debits the wallet.

Required recipient fields depend on `paymentType`:

| Payment type  | Required recipient fields                                      | Optional recipient fields               |
| ------------- | -------------------------------------------------------------- | --------------------------------------- |
| `wallet`      | `recipientName`, `recipientMsisdn`                             | `recipientSurname`                      |
| `bank`        | `recipientName`, `recipientAccountNumber`, `recipientBankCode` | `recipientSurname`, `recipientMsisdn`   |
| `cash_pickup` | `recipientName`, `recipientMsisdn`                             | `recipientSurname`, `cashPickupPartner` |

The API validates the selected payment rail before it debits the wallet. For a wallet or cash pickup, `recipientMsisdn` must follow the rule in [Validate Recipient](#validate-recipient), or the send returns `422 INVALID_RECIPIENT_MSISDN`. It also verifies the active corridor and route. For applicable transfers, it verifies the destination bank code, currency, or cash-pickup partner.

For cash pickup, omit `cashPickupPartner` only if the active corridor provides exactly one partner. If the corridor returns several partners, select one.

For cash pickup, send `recipientName` and `recipientSurname` exactly as they appear on the recipient's government ID. The cash-pickup partner checks the name on the transfer against the ID, and only the recipient can collect the cash.

The `quoteId` is opaque and short-lived. It is bound to the quoted amount, destination, payment type, route, sender, and tenant. Send the value unchanged. A mismatch returns `409 QUOTE_MISMATCH` before wallet debit.

The `quoteId` is optional. If you supply it, the service tries to accept that quote. If the quote expired, the send is rejected with `409 QUOTE_EXPIRED`: get a new quote and show the user its pricing before they confirm. If the exchange refuses it, the service reverses the wallet debit before returning the error; if the exchange's answer cannot be confirmed, the send returns `422 CURRENC_TRADE_AMBIGUOUS` and the debit is held (see the error table below).

`409 QUOTE_EXPIRED` without `data.reversed` means this request moved nothing. It says nothing about an earlier attempt with the same key: a timed-out send retried with its original `quoteId` gets this error even if that send went through. Get a new quote and send it with the same idempotency key. If the earlier attempt went through, that send returns its transaction with `duplicate: true` at the original pricing, and nothing is sent twice; if it is still running, it returns `429 SEND_IN_PROGRESS`. With `data.reversed: true`, the wallet was debited and the exchange rate expired during processing, so the debit was refunded and the key is spent: get a new quote and send it with a new key. Show the user the new quote's pricing before they confirm a new send.

**Purpose of transfer:**

| Code  | Meaning          | Code  | Meaning      |
| ----- | ---------------- | ----- | ------------ |
| `PT1` | Family support   | `PT6` | Construction |
| `PT2` | Education        | `PT7` | Rent         |
| `PT3` | Business payment | `PT8` | Gift         |
| `PT4` | Medical expense  | `PT9` | Other        |
| `PT5` | Investment       |       |              |

**Source of funds:**

| Code  | Meaning         | Code  | Meaning           |
| ----- | --------------- | ----- | ----------------- |
| `SF1` | Salary          | `SF4` | Sale of assets    |
| `SF2` | Savings         | `SF5` | Investment income |
| `SF3` | Business income | `SF6` | Other             |

**Response (200 OK):**

```json
{
  "success": true,
  "transaction": {
    "_id": "66a7f1c9b45e8d0012345678",
    "userId": "user-123",
    "paymentType": "wallet",
    "toCountry": "KE",
    "toCurrency": "KES",
    "sendAmountZar": 10000,
    "feeAmountZar": 500,
    "convertibleAmountZar": 9500,
    "totalDebitZar": 10000,
    "receiveAmount": 67750,
    "recipientName": "Amina",
    "recipientSurname": "Kamau",
    "status": "pending",
    "thirdPartyTransId": "SPEN-20260728-001",
    "attempt": 1,
    "createdAt": "2026-07-28T12:00:20.000Z"
  }
}
```

`thirdPartyTransId` is the reference of the transfer's current attempt and `attempt` its number, as on the [remittance webhooks](#remittance-lifecycle-events); a retry changes both. Send, retry, list, get and status responses carry them. The webhooks' ordering rule applies to the retry response too. Get, status and list show the transfer as it is now.

The send operation checks the sender's account status, KYC and wallet balance. It debits the full `sendAmountZar`. It deducts the fee from the converted amount. It then locks in the exchange rate and creates a `pending` transaction.

The operation does not submit or complete the destination payout synchronously. Spendl usually submits the transfer within 15 minutes. A transfer can stay `pending` for longer. You don't need to do anything, and `pending` never means the transfer failed.

The first successful response does not contain `duplicate`. Reusing an idempotency key returns the stored transaction with `duplicate: true`. It does not create another debit.

The key remains valid for the transaction's lifetime. The replay window does not expire. After a timeout or ambiguous response, retry only with the same key.

Common send errors are:

| Code | Types                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Outcome                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 403  | `REMITTANCE_NOT_ENABLED`, `USER_MISMATCH`, `KYC_NOT_APPROVED`, `ACCOUNT_RESTRICTED`                                                                                                                                                                                                                                                                                                                                                                                                                                     | This request moved nothing                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| 404  | `USER_NOT_FOUND`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `userId` is not one of your users. This request moved nothing                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| 409  | `QUOTE_MISMATCH`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | This request moved nothing                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| 409  | `QUOTE_EXPIRED`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | This request moved nothing, but an earlier attempt with this key may have (see above); use a new quote and the same key. With `data.reversed: true`: debited, then refunded, and the key is spent; use a new quote and a new key                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| 422  | `INCOMPLETE_KYC`, `KYC_INCOMPLETE`, `INSUFFICIENT_FUNDS`, `TERMS_NOT_ACCEPTED`, `VALIDATION_ERROR`, `MISSING_IDEMPOTENCY_KEY`, `IDEMPOTENCY_KEY_MISMATCH`, `INVALID_CORRIDOR_ROUTING`, `INVALID_RECIPIENT_MSISDN`, `INVALID_RECIPIENT_BANK`, `INVALID_CASH_PICKUP_PARTNER`, `AMOUNT_TOO_LOW`, `CASH_PICKUP_PARTNER_REQUIRED`, `INVALID_QUOTE` (the `quoteId` is not one the API issued), `INVALID_QUOTE_TOKEN` (the quote could not be verified when the send was processed, for example because it expired on the way) | This request moved nothing. After `INVALID_QUOTE_TOKEN`, get a new quote and send it with the same key                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 422  | `TRADE_LIMIT_EXCEEDED`, `FX_PROVIDER_REJECTED`                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Debited, then refunded (`data.reversed: true`). The key is spent; use a new key                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| 422  | `AMOUNT_TOO_SMALL`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Debited, then refunded; `data.reversed: false` means the refund is still outstanding. The key is spent: a retry returns this error again                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| 422  | `IDEMPOTENCY_KEY_ALREADY_USED`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | An earlier attempt with this key was refunded. The key is spent; use a new key                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| 422  | `CURRENC_TRADE_AMBIGUOUS`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Debited, and the exchange's answer could not be confirmed, so the debit is held until support resolves it. May have moved. Do not use a new key: until then, a retry with this key (with a new quote, or none) returns this error again, with `data.reversed: false`. Once it is resolved, such a retry answers like any other retry of that send if the exchange went through (its transaction with `duplicate: true` while the send is in flight or delivered, `422 PRIOR_ATTEMPT_UNRESOLVED` if its payout later fails, is cancelled or is refunded), or returns this error with `data.reversed: true` if the debit was refunded; only then is the key spent. Check [List Transactions](#list-transactions) or contact support |
| 422  | `PRIOR_ATTEMPT_UNRESOLVED`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | May have moved. Do not use a new key; check [List Transactions](#list-transactions) or contact support                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 429  | `SEND_IN_PROGRESS`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | A send for this user, possibly an earlier attempt with this key, is still running; this request moved nothing. Retry later with the same key                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| 503  | `REMITTANCE_UNAVAILABLE`, `FX_PROVIDER_UNAVAILABLE` (no live exchange rate could be obtained)                                                                                                                                                                                                                                                                                                                                                                                                                           | Returned before the wallet is debited: this request moved nothing. Retry later with the same key, with a new quote if the old one expired                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| 5xx  | Any other `5xx` (for example `INTERNAL_ERROR`, `REQUEST_TIMEOUT` or `UPSTREAM_NETWORK_ERROR`), a plain-text `503` or `504` from the network edge, or no response                                                                                                                                                                                                                                                                                                                                                        | May have moved. Retry with the same key (see below)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |

The quote and corridor errors listed above can also occur.

`AMOUNT_TOO_SMALL` means that the receive amount after conversion rounded to zero. The service reverses the wallet debit before it returns the error. `INCOMPLETE_KYC` lists the missing sender profile fields in `data.missingFields` (see [Sender Profile](#sender-profile)).

After a `5xx` other than `REMITTANCE_UNAVAILABLE` or `FX_PROVIDER_UNAVAILABLE`, retry with the same key, with a new quote if the old one expired (see `QUOTE_EXPIRED` above). The retry returns the earlier attempt's outcome: its transaction (`duplicate: true`) or an error from the table, such as `429 SEND_IN_PROGRESS`, `PRIOR_ATTEMPT_UNRESOLVED` (keep the key; contact support) or `IDEMPOTENCY_KEY_ALREADY_USED` (refunded; use a new key). If nothing moved, it sends once. Do not generate a new key before then.

#### List Transactions

```
GET /api/remittance/transactions?userId=user-123&page=1&limit=20&status=processing
```

| Parameter | In    | Required | Description                                 |
| --------- | ----- | -------- | ------------------------------------------- |
| `userId`  | Query | Yes      | User whose transactions are requested       |
| `page`    | Query | No       | Page number, default `1`                    |
| `limit`   | Query | No       | Items per page, default `20`, maximum `100` |
| `status`  | Query | No       | Filter by a lifecycle status listed below   |

**Response (200 OK):**

```json
{
  "items": [
    {
      "_id": "66a7f1c9b45e8d0012345678",
      "userId": "user-123",
      "paymentType": "wallet",
      "toCountry": "KE",
      "toCurrency": "KES",
      "sendAmountZar": 10000,
      "feeAmountZar": 500,
      "receiveAmount": 67750,
      "recipientName": "Amina",
      "recipientSurname": "Kamau",
      "status": "processing",
      "thirdPartyTransId": "SPEN-20260728-001",
      "attempt": 1,
      "createdAt": "2026-07-28T12:00:20.000Z",
      "updatedAt": "2026-07-28T12:01:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}
```

The API returns the newest transactions first. It omits the sender's identity details. It never contains a cash pickup's `voucherCode`. Each item can contain `voucherStatus` and `voucherCollected` (see [Cash Pickup Vouchers](#cash-pickup-vouchers)).

#### Get Transaction

Use this endpoint to show transfer details or a receipt.

```
GET /api/remittance/transactions/:transactionId?userId=user-123
```

The response contains the stable transaction fields in this section. These fields contain recipient routing details for confirmation and receipts. It can also contain `voucherStatus` and `voucherCollected`, which carry values only for a cash pickup, and, while a cash pickup's voucher can still be collected, `voucherCode` (see [Cash Pickup Vouchers](#cash-pickup-vouchers)). The response omits the sender's ID number and date of birth. The API returns `404 NOT_FOUND` if the transaction does not belong to the supplied user, and `400 INVALID_ID` if `transactionId` is not a valid transaction ID.

#### Check Transaction Status

```
GET /api/remittance/transactions/:transactionId/status?userId=user-123
```

| Parameter       | In    | Required | Description                                         |
| --------------- | ----- | -------- | --------------------------------------------------- |
| `transactionId` | Path  | Yes      | Remittance transaction ID returned by initiate send |
| `userId`        | Query | Yes      | Owner of the transaction                            |

**Response (200 OK):**

```json
{
  "status": "processing",
  "networkStatusCode": "MR102",
  "voucherCode": null,
  "voucherPartner": null,
  "callbackReceivedAt": null,
  "thirdPartyTransId": "SPEN-20260728-001",
  "attempt": 1
}
```

A completed cash pickup also returns the voucher, where to collect it, and its collection state:

```json
{
  "status": "completed",
  "networkStatusCode": "MR101",
  "voucherCode": "CP-834921",
  "voucherPartner": "Example Cash Network",
  "callbackReceivedAt": "2026-07-28T12:18:44.000Z",
  "thirdPartyTransId": "SPEN-20260728-001",
  "attempt": 1,
  "voucherStatus": "issued",
  "voucherCollected": false
}
```

Lifecycle statuses are `pending`, `submitted`, `processing`, `completed`, `failed`, `cancelled`, `refunded`, and `cash_pickup_ready`. For cash pickup, `voucherCode` is the code the recipient needs to collect the cash. Treat it as sensitive. Send it only to the intended recipient. See [Cash Pickup Vouchers](#cash-pickup-vouchers). `voucherPartner` is the cash-pickup partner where the recipient collects the cash, the same value as `cashPickupPartner` on [`remittance.cashPickupReady`](#remittancecashpickupready); it is `null` for a wallet or bank transfer, or when no partner is recorded, and stays set after the code is withheld. `thirdPartyTransId` and `attempt` identify the current attempt, as on the [send response](#initiate-send). The API returns `404 NOT_FOUND` if the transaction does not exist for the supplied user, and `400 INVALID_ID` if `transactionId` is not a valid transaction ID.

| Status              | Meaning                                                                                                                                                                                                                                                                                                      | Terminal |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- |
| `pending`           | Accepted and queued for submission                                                                                                                                                                                                                                                                           | No       |
| `submitted`         | Submitted to the destination network                                                                                                                                                                                                                                                                         | No       |
| `processing`        | Destination network is processing the transfer                                                                                                                                                                                                                                                               | No       |
| `cash_pickup_ready` | Cash is ready for pickup. Rare: a cash pickup normally goes straight to `completed`                                                                                                                                                                                                                          | No       |
| `completed`         | Funds were delivered. For a cash pickup, the voucher was issued; collection is shown by `voucherStatus` and `voucherCollected`                                                                                                                                                                               | Yes      |
| `failed`            | The payout or the submission failed. The wallet is not refunded automatically: you can [retry the transfer](#retry-failed-transfer) when the recipient details caused the failure, and Spendl retries it otherwise. A retry returns it to `submitted`. Contact support about a transfer that stays `failed`. | No       |
| `cancelled`         | Destination processing was cancelled. The wallet stays debited until Spendl retries the transfer or refunds it; a refund changes the status to `refunded` and sends [`remittance.refunded`](#remittancerefunded).                                                                                            | Yes      |
| `refunded`          | The full debit, including the fee, was returned to the sender wallet                                                                                                                                                                                                                                         | Yes      |

`networkStatusCode` contains the destination network's own status code, or `null` when no network code is available. Common values include `MR101` (paid out; for a cash pickup, voucher issued), `MR102`–`MR104` (processing or awaiting confirmation), `MR105` (cash collected), `MR106` (cash pickup ready), `MR107` or `MR109` (cancelled), `MR108`, `MR118`, or `MR128` (queued), `MR119` (reversed), `TS` (successful), `TF` (failed), `101` (the network refused the transfer when it was submitted), and `ER1xx`–`ER2xx` error codes.

The destination network can add more codes. Use the public `status` field for lifecycle decisions. Pending or queued network statuses can stay `processing` while operations determine the result. Do not infer failure from a pending status. Do not issue a compensating credit from a pending status.

`completed` means the destination network confirmed delivery. If Spendl cannot finish settling a delivered transfer, it returns the transfer to `processing` until settling succeeds, and [`remittance.completed`](#remittancecompleted) is sent only once it has.

#### Cash Pickup Vouchers

For a cash pickup, the destination network issues a voucher code. To collect the cash, the recipient must show this code and a government-issued ID (a passport counts) at the cash-pickup partner, which checks that the name on the ID matches the recipient's name on the transfer. Only the recipient can collect the cash, in person; no one can collect it for them. The code is not linked to an ID number, so treat it as sensitive: show it only to the sending user, send it only to the intended recipient, and do not log it.

* A cash-pickup transfer becomes `completed`, with `networkStatusCode` `MR101`, when the voucher is **issued**, not when the cash is collected.
* `voucherCode` is returned by [Check Transaction Status](#check-transaction-status) and [Get Transaction](#get-transaction) only while the voucher can still be collected: the transfer is `completed` or `cash_pickup_ready`, `voucherStatus` is `issued` or not set, and `voucherCollected` is not `true`. Once the voucher is collected or cancelled, the status endpoint returns `voucherCode: null` and Get Transaction omits it. Both responses carry `Cache-Control: no-store`, so do not cache them. [List Transactions](#list-transactions) and the send response never contain it. The [`remittance.cashPickupReady`](#remittancecashpickupready) webhook also carries it.
* `voucherCode` can be `null` for a short time after the transfer becomes `completed`. Keep polling the status endpoint until it is set. If it is still `null` 30 minutes after `completed`, contact Spendl support.
* A voucher can be cancelled after its transfer completed. The transfer stays `completed`, `voucherStatus` becomes `cancelled`, and the code is withheld; no webhook is sent for it. Tell the customer the code is no longer valid and to contact support. Spendl reviews the transfer.
* `voucherStatus` and `voucherCollected` show collection when the network reports it. `voucherStatus` is `issued`, `collected`, `cancelled`, or `null` when nothing has been reported. `voucherCollected` is `true` once collection is reported. When a completed transfer's voucher is later collected, [`remittance.cashPickupCollected`](#remittancecashpickupcollected) is sent; a later cancellation sends no webhook. [Check Transaction Status](#check-transaction-status) always has the voucher's current `voucherStatus`. Collection usually shows no sooner than about a day after the voucher is issued, so `voucherCollected: false` does not prove that the cash is still uncollected.
* Any transaction, on the status, transaction, list and send responses, can contain `voucherStatus` and `voucherCollected`. For a wallet or bank transfer, and for a transfer sent before these fields existed, `voucherStatus` is `null` or absent and `voucherCollected` is `false` or absent; `voucherCode` is `null` or absent.
* `cash_pickup_ready` (`MR106`) is rare. Handle it as a non-terminal status.
* A voucher cannot be cancelled through the API: [Cancel Transaction](#cancel-transaction) always returns `422 NOT_CANCELLABLE`. Contact Spendl support to stop it.

#### Cancel Transaction

```
POST /api/remittance/transactions/:transactionId/cancel
Content-Type: application/json
```

```json
{
  "userId": "user-123"
}
```

Customers cannot cancel a remittance. This endpoint always returns `422 NOT_CANCELLABLE`, whatever the payment type or status, and nothing changes: the wallet keeps its debit and the transfer goes ahead. The exchange rate is booked and funded when the transfer is sent. To stop a transfer, or a cash pickup whose voucher was issued, contact Spendl support.

#### Retry Failed Transfer

```
POST /api/remittance/transactions/:transactionId/retry-edit
Content-Type: application/json
X-Idempotency-Key: retry-user-123-20260728-001
```

```json
{
  "userId": "user-123",
  "edits": {
    "recipientMsisdn": "254712345678"
  }
}
```

Retry a `failed` transfer with corrected recipient details. The wallet is not debited again. A successful retry returns the transaction, as the send does, with `status: "submitted"`, and the transfer then progresses as a new send does.

The failure's network code (`networkStatusCode` from [Check Transaction Status](#check-transaction-status), or `statusCode` on [`remittance.failed`](#remittancefailed)) decides what `edits` may change:

| Network code     | Fields you can change                                            |
| ---------------- | ---------------------------------------------------------------- |
| `ER106`, `ER108` | `recipientMsisdn`                                                |
| `ER111`, `ER200` | `recipientMsisdn`, `recipientAccountNumber`, `recipientBankCode` |

`edits` can contain only these three fields. Change at least one of them: a value equal to the current one is not a change. For `ER111` and `ER200` only, a transfer that has not been retried yet can also be retried once with no change, to try the same details again. Any other failure returns `422 NOT_EDITABLE`: Spendl handles it. You can retry a transfer at most three times. Send a new `recipientMsisdn` as for [Validate Recipient](#validate-recipient), and validate the corrected recipient first. Here a malformed number returns `422 VALIDATION_ERROR`, not `INVALID_RECIPIENT_MSISDN`.

Always supply an idempotency key, as for a send (`X-Idempotency-Key` or `idempotencyKey` in the body). Once a retry has been made with a key, a repeat with that key retries nothing, whatever its body: it returns the transfer as it is now, with `duplicate: true`. Read `transaction.status`: the retry may have failed since. After a `5xx` or no response, repeat the request with the same key. Use a new key for each new retry.

None of these errors debits the wallet:

| Code | Types                                                                                                               | Meaning                                                                                                                                                                                                                                            |
| ---- | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400  | `INVALID_ID`                                                                                                        | `transactionId` is not a valid transaction ID                                                                                                                                                                                                      |
| 403  | `REMITTANCE_NOT_ENABLED`, `ACCOUNT_RESTRICTED`, `KYC_REQUIRED`, `INSUFFICIENT_SCOPE` (the key has no `write` scope) | Nothing was retried                                                                                                                                                                                                                                |
| 404  | `NOT_FOUND`                                                                                                         | The transaction does not exist for the supplied user. The user is checked first: a `userId` that is not one of your users returns `403 KYC_REQUIRED`                                                                                               |
| 409  | `CONCURRENT_MODIFICATION`                                                                                           | Another retry of this transfer was made at the same time. Check its status before you retry again                                                                                                                                                  |
| 409  | `RETRY_AMBIGUOUS`                                                                                                   | The retry's outcome could not be confirmed. Check the transfer's status before you retry again: it normally stays `submitted` until Spendl confirms the outcome                                                                                    |
| 422  | `RETRY_REJECTED`                                                                                                    | The destination network refused the retry. Check the transfer's status: it is normally `failed` again, and [`remittance.failed`](#remittancefailed) is sent with its `statusCode`. Retry it if `statusCode` allows; otherwise Spendl handles it    |
| 422  | `INVALID_STATUS`                                                                                                    | Only a `failed` transfer can be retried                                                                                                                                                                                                            |
| 422  | `NOT_EDITABLE`, `AWAITING_RECONCILIATION`, `ALREADY_REFUNDED`                                                       | This transfer cannot be retried by you. Spendl handles it                                                                                                                                                                                          |
| 422  | `EDIT_NOT_ALLOWED`                                                                                                  | `edits` changes a field this failure does not allow; `data.editableFields` lists the ones it does                                                                                                                                                  |
| 422  | `NO_EDITS_PROVIDED`                                                                                                 | `edits` changes nothing, and this retry needs a change                                                                                                                                                                                             |
| 422  | `INVALID_RECIPIENT_MSISDN`                                                                                          | The new `recipientMsisdn` is in international format but not valid for the destination, for example without its dialling code                                                                                                                      |
| 422  | `MAX_RETRIES_EXCEEDED`                                                                                              | You have already retried the transfer three times. Contact support                                                                                                                                                                                 |
| 422  | `MISSING_IDEMPOTENCY_KEY`, `IDEMPOTENCY_KEY_MISMATCH`, `VALIDATION_ERROR`                                           | The request is incomplete or malformed, `edits` contains another field or a value that is not a string (such as `null`), or the new `recipientMsisdn` is not 7 to 15 digits in international format (for example a local number starting with `0`) |
| 503  | `RETRY_UNAVAILABLE`                                                                                                 | The retry could not be sent. Nothing was retried and it does not count toward the three: the transfer is still `failed`. Repeat the request later, with the same key                                                                               |

#### User Statistics

```
GET /api/remittance/stats?userId=user-123
```

**Response (200 OK):**

```json
{
  "totalTransactions": 12,
  "completedCount": 8,
  "pendingCount": 1,
  "failedCount": 2,
  "cancelledCount": 1,
  "thisMonthCount": 3,
  "totalSentZar": 120000,
  "thisMonthSentZar": 45000,
  "topCorridors": [
    { "countryCode": "KE", "count": 5, "totalZar": 60000 },
    { "countryCode": "GH", "count": 3, "totalZar": 30000 }
  ]
}
```

All ZAR amounts are in cents. `topCorridors` returns the five most-used destination countries.

#### User Limits

```
GET /api/remittance/user-limits?userId=user-123
```

Read the caller's remaining remittance capacity. This endpoint does not depend on a corridor. It is safe to call from a landing screen or an amount input, because it does not request a quote. When a corridor is known, `POST /api/remittance/quote` returns the same values under `userLimits`.

**Response (200 OK):**

```json
{
  "dailyLimitItt": 500000,
  "dailyUsedItt": 150000,
  "dailyRemainingItt": 350000,
  "dailyResetAt": "2026-09-08T22:00:00.000Z",
  "monthlyLimitItt": 2500000,
  "monthlyUsedItt": 800000,
  "monthlyRemainingItt": 1700000,
  "monthlyResetAt": "2026-09-30T22:00:00.000Z"
}
```

All amounts are in **ZAR cents** (`1 cent = 0.01 ZAR`). This is the same unit that every other cent-denominated field on the remittance surface uses. The windows reset at midnight SAST (UTC+2). `dailyResetAt` is the start of the next SAST day. `monthlyResetAt` is the start of the next SAST month. A limit of `0` means that the platform disabled that cap and enforces no capacity check.

`POST /api/remittance/send` rejects a send that would exceed either cap. It returns `422 USER_DAILY_LIMIT_EXCEEDED` or `422 USER_MONTHLY_LIMIT_EXCEEDED`. The rejection payload contains `limitItt`, `usedItt`, `remainingItt`, `attemptedItt`, and `resetAt`, so that your client can show an exact message.

***

### Webhooks

#### Callback Event Model

Webhooks are event-driven. Configure webhooks for each tenant and event key. The Public API sends callbacks for the following lifecycle events and can support future events.

Current callback events:

* `bank_account_created` (legacy KYC/account callback)
* `debt_obligation_created` (legacy debt processing callback)
* `debt_repayment_complete` (legacy debt-repayment callback. The API sends it only when the tenant has a `debtRepaymentComplete` endpoint configured.)
* `user.created` (legacy alias: `user_created`)
* `account.updated`
* `account.status_changed` (legacy alias: `account_status_changed`)
* `kyc.document_uploaded` (legacy alias: `kyc_document_uploaded`)
* `kyc.documents_completed` (legacy alias: `kyc_documents_completed`)
* `kyc.submission_pending` (legacy alias: `kyc_submission_pending`)
* `kyc.not_ready` (legacy alias: `kyc_not_ready`)
* `kyc.submitting` (legacy alias: `kyc_submitting`)
* `kyc.submitted` (legacy alias: `kyc_submitted`)
* `kyc.submission_failed` (legacy alias: `kyc_submission_failed`)
* `kyc.validation_pending` (legacy alias: `kyc_validation_pending`)
* `kyc.validation_started` (legacy alias: `kyc_validation_started`)
* `kyc.validation_failed` (legacy alias: `kyc_validation_failed`)
* `kyc.superseded` (legacy alias: `kyc_superseded`)
* `wallet.deposit_completed` (legacy alias: `wallet_deposit_completed`)
* `wallet.transfer_completed` (legacy alias: `wallet_transfer_completed`)
* `wallet.disbursement_completed`
* `wallet.load_card_completed` (legacy alias: `wallet_load_card_completed`)
* `wallet.purchase_voucher_completed` (legacy alias: `wallet_purchase_voucher_completed`). Sent by the deprecated `POST /api/wallet/purchase-voucher` and, since v1.38, by `POST /api/vouchers/perform` when the payout completes. The voucher-flow payload carries `source: "vouchers.perform"`, its own top-level fields and a redacted `result` without voucher credentials or recipient data (see [`wallet.purchase_voucher_completed`](#walletpurchase_voucher_completed)). A `pending` or `needs_review` perform sends no callback. A perform that you retry with the same idempotency key replays the completed result and sends the callback again with the same `X-Idempotency-Key`; deduplicate on that header, as with every other event.
* `wallet.repay_debt_completed` (legacy alias: `wallet_repay_debt_completed`)
* `wallet.debt_repayment_failure` (a debt obligation missed its repayment window. The API sends it only when the tenant has a `wallet.debt_repayment_failure` endpoint configured.)
* `wallet.incoming_credit` (legacy alias: `wallet_incoming_credit`. Money from outside Spendl arrived in a user's wallet. The API sends it only when the tenant has a `wallet.incoming_credit` endpoint configured.)
* `wallet.send_to_bank_completed` (legacy alias: `wallet_send_to_bank_completed`)
* `wallet.send_to_bank_failed` (a send-to-bank payment failed and the wallet was refunded. The API sends it only when the tenant has a `wallet.send_to_bank_failed` endpoint configured.)
* `wallet.beneficiary_added` (legacy alias: `wallet_beneficiary_added`)
* `wallet.beneficiary_removed` (legacy alias: `wallet_beneficiary_removed`)

Status-transition events. The Public API sends these events directly for its own outcomes. Spendl also sends them when it detects a status change made outside the Public API, for example by Spendl compliance or operations.

* `kyc.approved` (legacy alias: `kyc_approved`)
* `kyc.rejected` (legacy alias: `kyc_rejected`)
* `kyc.review_required` (legacy alias: `kyc_review_required`)
* `wallet.suspended` (legacy alias: `wallet_suspended`)
* `wallet.closed` (legacy alias: `wallet_closed`)
* `compliance.hold_set` (legacy alias: `compliance_hold_set`)
* `compliance.hold_cleared` (legacy alias: `compliance_hold_cleared`)

Remittance callback events: `remittance.submitted`, `remittance.completed`, `remittance.failed`, `remittance.cancelled`, `remittance.cashPickupReady`, `remittance.cashPickupCollected`, `remittance.refunded`.

Endpoint key routing:

* Default route key is the event name itself (for example `wallet.transfer_completed`), in lowercase. A camelCase event routes by its lowercase name: configure `remittance.cashpickupready` for `remittance.cashPickupReady` and `remittance.cashpickupcollected` for `remittance.cashPickupCollected`. A key spelled in camelCase is not matched.
* Legacy compatibility mappings remain enabled:
  * `bank_account_created` → `accountCreation`
  * `debt_obligation_created` → `debtObligation`
  * `debt_repayment_complete` → `debtRepaymentComplete`

If you have no endpoint for an event, the Public API does not send that event.

Some events are opt-in: `debt_repayment_complete`, `wallet.debt_repayment_failure`, `wallet.incoming_credit`, `wallet.send_to_bank_failed` and every remittance event. Configure an endpoint for one of these only if you want it. `debt_repayment_complete` is for tenants that use the legacy debt-repayment integration. The others are for tenants that want to be told about that activity.

An inactive tenant, or an invalid endpoint type or auth type, stops delivery of every event. An invalid URL stops delivery of the events sent to that endpoint. If callbacks stop arriving, ask your account manager to check your endpoint configuration.

#### Example Payloads

The following sections show the JSON body for each event that the Public API sends. They also show the remittance event payloads. Headings use the **canonical event name**. A heading includes the legacy snake\_case alias when one exists.

> **Optional fields** appear only when supplied and non-null. The sender does **not** send these fields as `null`. Your receiver must allow these fields to be absent.
>
> The `result` object on wallet activity events contains the response of the wallet operation. Its inner shape can change. Allow unrecognised fields.
>
> Currency amounts on wallet events are in **minor units** (e.g. ZAR cents).

**Lifecycle / Account Events**

**`bank_account_created`**

Sent after KYC verification reaches an outcome and the user's bank account is ready. This event is not a KYC approval. The outcome arrives as `kyc.approved`, `kyc.review_required`, or `kyc.rejected`. *Endpoint key override:* `accountCreation`. *Wire format:* always `REST`.

```json
{
  "success": true,
  "account": {
    "spendlUserId": "507f1f77bcf86cd799439011",
    "bankAccountNumber": "1234567890",
    "branchCode": "250655",
    "bankName": "ABSA",
    "accountHolderName": "John Doe",
    "uniqueDepositReference": "ACM00000001",
    "currency": "ZAR"
  }
}
```

**`debt_obligation_created`**

Sent after the system processes a debt obligation. *Endpoint key override:* `debtObligation`. *Wire format:* always `REST`.

```json
{
  "success": true,
  "obligation": {
    "_id": "507f1f77bcf86cd799439011",
    "guid": "DEBT-2025-001234",
    "clientNo": "C12345",
    "loanRefNo": "LOAN-98765",
    "processingStatus": "callback_sent",
    "replyCd": "207",
    "replyStr": "Successful"
  }
}
```

**`debt_repayment_complete`**

Sent after `wallet.repay_debt_completed` when the tenant has a `debtRepaymentComplete` endpoint. The system sends this event **in addition to** `wallet.repay_debt_completed`, not instead of it.

The payload is a flat object with camelCase fields. *Endpoint key override:* `debtRepaymentComplete`. *Wire format:* always `REST`. *Conditional:* The system sends the event only when the endpoint is configured.

For tenants that use the legacy ingestion path, this callback occurs **after** the [Debt Obligation Callback](#debt_obligation_created). It reports the wallet debit result.

```json
{
  "guid": "0123456789ABCDEF0123456789ABCDEF",
  "machine": "WINDOWS-PC",
  "clientNo": "00000000123456",
  "loanRefNo": "123456_12345",
  "processingStatus": "SUCCESS",
  "replyCd": "207",
  "replyStr": "Successful",
  "processedAt": "2026-01-29T10:06:01.000Z",
  "amountProcessed": "1500.00"
}
```

| Field              | Type   | Description                                                                                                                                                                            |
| ------------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `guid`             | string | The obligation's unique identifier                                                                                                                                                     |
| `machine`          | string | Originating machine (echoed from the original request)                                                                                                                                 |
| `clientNo`         | string | Client reference (echoed from the original request)                                                                                                                                    |
| `loanRefNo`        | string | Loan reference (echoed from the original request)                                                                                                                                      |
| `processingStatus` | string | Processing outcome — see [Debt Repayment Statuses](#debt-repayment-statuses)                                                                                                           |
| `replyCd`          | string | Underlying processor result code                                                                                                                                                       |
| `replyStr`         | string | Human-readable result description                                                                                                                                                      |
| `processedAt`      | string | ISO 8601 timestamp of when processing completed                                                                                                                                        |
| `amountProcessed`  | string | The amount that was debited. The API formats it as a major-unit decimal string with two decimals, for example `"1500.00"`. The value is `"0.00"` for outcomes that are not successful. |

> **Echo fields:** The `guid`, `machine`, `clientNo`, and `loanRefNo` values come from `debtDetails` in the original [Repay Debt](#repay-debt) request. The legacy callback is sent **only when all four fields are present**. The API accepts `client_no` and `loan_ref_no` as aliases for `clientNo` and `loanRefNo`. If any field is missing, the system silently skips the legacy callback. Only `wallet.repay_debt_completed` is sent.

**Debt Repayment Statuses**

| Status                 | Description                                                                                                    |
| ---------------------- | -------------------------------------------------------------------------------------------------------------- |
| `SUCCESS`              | Obligation processed successfully and funds debited                                                            |
| `FAILED`               | Processing failed for an unspecified or generic reason — see `replyStr`                                        |
| `INSUFFICIENT_BALANCE` | The user's account did not have enough funds to cover the obligation                                           |
| `ACCOUNT_NOT_FOUND`    | The target account could not be located                                                                        |
| `ACCOUNT_FROZEN`       | The target account is frozen and cannot be debited                                                             |
| `ACCOUNT_CLOSED`       | The target account is closed                                                                                   |
| `INVALID_ACCOUNT`      | The account details on the obligation are invalid (e.g. wrong branch/account number)                           |
| `USER_NOT_REGISTERED`  | The user associated with the obligation is not registered or KYC is incomplete                                 |
| `DUPLICATE`            | An identical obligation has already been processed (idempotent rejection)                                      |
| `CANCELLED`            | The obligation was cancelled before it could be processed                                                      |
| `EXPIRED`              | The obligation passed its valid-until window before being processed                                            |
| `LIMIT_EXCEEDED`       | A daily, monthly, or per-transaction limit was exceeded                                                        |
| `PENDING`              | Processing is still in progress. The API sends a follow-up callback when processing reaches a terminal status. |
| `RETRYING`             | A temporary failure occurred and the obligation is queued for a retry                                          |

**`user.created`**

Legacy alias: `user_created`. Sent immediately after user ingestion.

```json
{
  "id": "507f1f77bcf86cd799439011",
  "email": "john.doe@example.com",
  "timestamp": "2026-05-21T10:30:45.123Z"
}
```

**`account.updated`**

Sent after an [Update Account Details](#update-account-details) or [Replace KYC Details](#replace-kyc-details) request is applied. [Fill Missing KYC Details](#fill-missing-kyc-details) does not send it. The endpoint key is `account.updated`. Delivery occurs at least once. Use `X-Idempotency-Key` to remove duplicates.

```json
{
  "userId": "507f1f77bcf86cd799439011",
  "email": "john.doe@example.com",
  "updateId": "1ec16b55-f92d-4c5a-bb26-830599f57425",
  "sequence": 4,
  "updateType": "details",
  "changedFields": ["userDetails.email", "preferences.twoFactor"],
  "tenantDisposition": "applied",
  "timestamp": "2026-07-30T10:00:00.000Z"
}
```

`sequence` is the acceptance order for the user. `tenantDisposition` is the result of applying the update: `applied` (the update was written), `duplicate` (the same update was already applied), or `stale` (a later update was already applied, so this one was not written). `updateType` is `details` or `kyc`.

`changedFields` contains only field names. The event never contains KYC values, passwords, compliance data, balances, transaction history, tenant credentials, or internal processing state. A KYC update sends this event after it stores the new KYC data. It does not wait for the verification decision. For a KYC update `changedFields` is `[]` when the same data restarted a failed KYC submission or verification.

**`account.status_changed`**

Sent when Spendl detects a change to the user's `userDetails.status`, for example when an administrator suspends, deactivates or reactivates the account. The endpoint key is `account.status_changed`. The legacy alias is `account_status_changed`.

```json
{
  "userId": "507f1f77bcf86cd799439011",
  "email": "john.doe@example.com",
  "previousStatus": "active",
  "accountStatus": "suspended",
  "timestamp": "2026-07-30T10:15:00.000Z"
}
```

No event is sent for the first status Spendl records for a user. Events are sent only for later changes. Delivery occurs at least once. Use `X-Idempotency-Key` to remove duplicates.

**`kyc.documents_completed`**

Legacy alias: `kyc_documents_completed`. Sent after all required KYC documents are uploaded. `status` is the user's KYC state at dispatch time. It is usually `"pending"` while review is queued.

It is sent once per user, by the document upload that first completes the user's KYC: `name`, `surname`, `dob` and `idNumber` are set and at least one identity document (`idProofFront`, `idProofBack`, `proofPassport` or `proofPermit`) is stored. Later uploads do not send it again. After you replace a user's KYC data with [`PATCH /api/ingest/:id/kyc`](#replace-kyc-details), it is sent again by the next document upload that finds the user's KYC complete.

```json
{
  "id": "507f1f77bcf86cd799439011",
  "email": "john.doe@example.com",
  "timestamp": "2026-05-21T14:22:10.456Z",
  "status": "pending"
}
```

**KYC Processing Lifecycle**

Configure an endpoint for each lifecycle event that your integration needs. These callbacks contain operational state only. They do not include KYC field values, uploaded document contents, filenames, storage keys, credentials, or verification audit records.

| Event                    | Emitted when                                                   |
| ------------------------ | -------------------------------------------------------------- |
| `kyc.document_uploaded`  | A KYC document is stored and attached to the user              |
| `kyc.submission_pending` | New KYC data or a replacement document queues a KYC submission |
| `kyc.not_ready`          | Required identity fields or documents are incomplete           |
| `kyc.submitting`         | A KYC submission attempt starts                                |
| `kyc.submitted`          | Spendl accepts the KYC submission                              |
| `kyc.submission_failed`  | The KYC submission fails after all retries                     |
| `kyc.validation_pending` | A new KYC revision queues verification                         |
| `kyc.validation_started` | A verification attempt starts                                  |
| `kyc.validation_failed`  | Verification exhausts all configured retries                   |
| `kyc.superseded`         | New KYC data or a document replaces an earlier revision        |

Attempt events can occur more than once. `attempt` and `maxAttempts` identify the current attempt. Failure events are terminal notifications. A temporary failure before the retry limit does not send one.

A user's lifecycle events are delivered in the order of their KYC state changes. If a delivery fails with a network error or a `5xx` response, the API retries it with the same `X-Idempotency-Key`, and later callbacks for that user wait behind it. A `4xx` response, including `429`, is not retried. A failure payload contains a `reasonCode` from a fixed list, such as `RETRY_EXHAUSTED`, `SUMSUB_DOCUMENTS_REQUESTED` or `SUMSUB_REVIEW_TIMEOUT`. It never contains raw provider or internal error messages.

If all delivery retries fail, or your endpoint returns a `4xx`, the API stops retrying that callback. It then continues with later events for that user.

The API sends the legacy `bank_account_created` callback after the user's lifecycle outcomes. It never overtakes a pending KYC lifecycle event or a newer document or KYC revision.

Example submission callback:

```json
{
  "userId": "507f1f77bcf86cd799439011",
  "email": "john.doe@example.com",
  "status": "submitted",
  "kycRevision": 2,
  "attempt": 1,
  "maxAttempts": 5,
  "timestamp": "2026-09-28T10:30:00.000Z"
}
```

**Wallet Activity Events**

These events report activity on a user's wallet. The six single-operation `*_completed` events (deposit, transfer, load card, purchase voucher, repay debt and send to bank) and the two beneficiary events include a `result` object. `wallet.disbursement_completed` has a `results` array instead, one item per recipient. `wallet.debt_repayment_failure`, `wallet.incoming_credit` and `wallet.send_to_bank_failed` have no `result`.

**`wallet.deposit_completed`**

Legacy alias: `wallet_deposit_completed`. `feeAmount`, `fromSuspense` and `metadata` are as sent, and omitted when not sent. `sourceWallet` is the tenant wallet you sent, in lowercase as in `result.sourceWallet`, and omitted when not sent. `result` is the [Deposit Funds](#deposit-funds) `200` response body, without `success`.

```json
{
  "userId": "507f1f77bcf86cd799439011",
  "amount": 50000,
  "feeAmount": 250,
  "sourceWallet": "507f1f77bcf86cd799439021",
  "metadata": { "source": "mobile_app", "reference": "DEP-123" },
  "result": {
    "journalEntryId": "6641a2b3c4d5e6f708192a3b",
    "userId": "507f1f77bcf86cd799439011",
    "sourceWallet": "507f1f77bcf86cd799439021",
    "amount": 50000,
    "feeAmount": 250,
    "netAmount": 49750,
    "status": "posted"
  }
}
```

**`wallet.transfer_completed`**

Legacy alias: `wallet_transfer_completed`. Internal user-to-user transfer. `feeAmount`, `description` and `metadata` are as sent, and omitted when not sent. `result` is the [Transfer Funds](#transfer-funds) `200` response body, without `success`.

```json
{
  "senderUserId": "507f1f77bcf86cd799439011",
  "receiverUserId": "507f1f77bcf86cd799439012",
  "amount": 1200,
  "feeAmount": 50,
  "description": "Payment for services",
  "metadata": { "invoiceId": "INV-2026-4567" },
  "result": {
    "journalEntryId": "6641a2b3c4d5e6f708192a3b",
    "senderUserId": "507f1f77bcf86cd799439011",
    "receiverUserId": "507f1f77bcf86cd799439012",
    "amount": 1200,
    "feeAmount": 50,
    "netAmount": 1150,
    "status": "posted"
  }
}
```

**`wallet.disbursement_completed`**

A salary or batch payment from a tenant wallet. The API sends this event after the disbursement finishes. It also sends the event when some payments fail.

```json
{
  "senderUserId": "507f1f77bcf86cd799439011",
  "kind": "salary",
  "totalAmount": 150000,
  "paidCount": 1,
  "invitedCount": 1,
  "failedCount": 0,
  "results": [
    { "email": "existing@example.com", "amount": 100000, "status": "posted", "journalEntryId": "..." },
    { "email": "new@example.com", "amount": 50000, "status": "escrowed", "journalEntryId": "...", "expiresAt": "2026-09-05T00:00:00Z" }
  ]
}
```

A disbursement retried with the same `idempotencyKey` sends this event again, describing the whole batch: recipients paid by the earlier attempt are included again as `posted` or `escrowed`, and recipients that failed before may now be paid. Treat events with the same `X-Idempotency-Key` as updates to one batch and merge them by recipient `email`: a `posted` or `escrowed` result with a `journalEntryId` is final and is never replaced by a `failed` result from another event for that key, which may arrive out of order. Never add the totals of two events for the same key together.

**`wallet.load_card_completed`**

Legacy alias: `wallet_load_card_completed`. Wallet → debit card load. The API sends this event after a [Load Card](#load-card) request succeeds. `cardReference`, `withdrawalOption` and `metadata` are as sent, and omitted when not sent. `result` is that request's `200` response body, without `success`; see [Load Card](#load-card) for its fields, including `channel`, `cardCredited` and `paymentMethod` (`FUND_CARD` on the instant channel). `result.status: "posted"` means the wallet was debited and the payment partner accepted the load, not that the card has been credited yet, unless `result.cardCredited` is `true` (the `fund_card` channel), which means the card has been credited.

```json
{
  "userId": "507f1f77bcf86cd799439011",
  "amount": 25000,
  "cardId": "1000001",
  "withdrawalOption": "IMMEDIATE",
  "metadata": { "channel": "api" },
  "result": {
    "journalEntryId": "6641a2b3c4d5e6f708192a3b",
    "userId": "507f1f77bcf86cd799439011",
    "amount": 25000,
    "feeAmount": 500,
    "grossDebit": 25500,
    "paymentMethod": "PAYSHAP",
    "status": "posted",
    "payaccsysRef": "PAY-123",
    "payaccsysFee": 5,
    "payaccsysFeeItt": 500
  }
}
```

**`wallet.purchase_voucher_completed`**

Legacy alias: `wallet_purchase_voucher_completed`. The API sends this event after a [Purchase Voucher](#purchase-voucher-deprecated) request succeeds. `feeAmount` (integer cents), `voucherDetails` and `metadata` are as sent, and omitted when not sent. `result` is that request's `200` response body, without `success`: the wallet was debited `amount + feeAmount` under `journalEntryId`. `POST /api/vouchers/perform` sends the same event with different fields: `userId`, `source: "vouchers.perform"`, then `amount`, `providerCode`, `providerName`, `expectedTotalDebitItt` and `quotedTariffVersion` as sent, and `result`. It has no `feeAmount`, `voucherDetails` or `metadata`. Its `result` has these fields of the perform response, when present: `success`, `status`, `userId`, `amountItt`, `amountRand`, `customerFeeItt`, `totalDebitItt`, `feeIncludesVat`, `tariffId`, `tariffVersion`, `providerCode`, `providerName`, `paymentReference`, `uniqueReference` and `journalEntryId`. It never has voucher credentials or recipient data. `source: "vouchers.perform"` tells the two apart (see [Webhooks](#webhooks)).

```json
{
  "userId": "507f1f77bcf86cd799439011",
  "amount": 10000,
  "feeAmount": 250,
  "voucherDetails": { "provider": "Vodacom" },
  "metadata": { "channel": "api" },
  "result": {
    "journalEntryId": "6641a2b3c4d5e6f708192a3b",
    "userId": "507f1f77bcf86cd799439011",
    "amount": 10000,
    "feeAmount": 250,
    "status": "posted"
  }
}
```

**`wallet.repay_debt_completed`**

Legacy alias: `wallet_repay_debt_completed`. `feeAmount`, `debtDetails` and `metadata` are as sent, and omitted when not sent. `result` is the [Repay Debt](#repay-debt) `200` response body, without `success`: the wallet was debited `amount + feeAmount` under `journalEntryId`.

```json
{
  "userId": "507f1f77bcf86cd799439011",
  "amount": 15000,
  "feeAmount": 150,
  "debtDetails": { "debtId": "DEBT-001", "originalAmount": 50000 },
  "metadata": { "paymentMethod": "wallet_balance" },
  "result": {
    "journalEntryId": "6641a2b3c4d5e6f708192a3b",
    "userId": "507f1f77bcf86cd799439011",
    "amount": 15000,
    "feeAmount": 150,
    "status": "posted"
  }
}
```

**`wallet.debt_repayment_failure`**

Sent when a debt obligation misses its repayment window. A window closes at the installment due date plus the obligation's grace period (`gracePeriodDays`). If the installment is still unpaid when the window closes, the obligation is in arrears.

This event fires **once per obligation**, on the first window it misses. It does not fire again for later missed installments on the same obligation. Spendl checks for missed windows once a day, so the callback usually arrives within a day after the window closes, not at the moment it closes.

*Wire format:* follows the tenant's configured format. *Conditional:* The system sends the event only when the endpoint is configured.

```json
{
  "guid": "0123456789ABCDEF0123456789ABCDEF",
  "machine": "WINDOWS-PC",
  "clientNo": "00000000123456",
  "loanRefNo": "123456_12345",
  "status": "ARREARS",
  "installmentSequence": 3,
  "dueDate": "2026-07-01T00:00:00.000Z",
  "windowEndsAt": "2026-07-11T00:00:00.000Z",
  "gracePeriodDays": 10,
  "expectedAmount": "1500.00",
  "paidAmount": "0.00",
  "installmentsPaid": 2,
  "installmentsTotal": 12,
  "failedAt": "2026-07-12T01:05:00.000Z"
}
```

| Field                 | Type           | Description                                                                                                  |
| --------------------- | -------------- | ------------------------------------------------------------------------------------------------------------ |
| `guid`                | string         | The obligation's unique identifier                                                                           |
| `machine`             | string \| null | Originating machine, echoed from the original obligation request. `null` when the API does not hold it.      |
| `clientNo`            | string \| null | Client reference, echoed from the original obligation request. `null` when the API does not hold it.         |
| `loanRefNo`           | string \| null | Loan reference, echoed from the original obligation request                                                  |
| `status`              | string         | Always `"ARREARS"`                                                                                           |
| `installmentSequence` | number \| null | The 1-based number of the installment whose window closed unpaid                                             |
| `dueDate`             | string \| null | ISO 8601 date the installment was due                                                                        |
| `windowEndsAt`        | string \| null | ISO 8601 date the repayment window closed (`dueDate` plus `gracePeriodDays`)                                 |
| `gracePeriodDays`     | number \| null | Days allowed after the due date before the obligation falls into arrears                                     |
| `expectedAmount`      | string         | The amount the installment expected. A major-unit decimal string with two decimals, for example `"1500.00"`. |
| `paidAmount`          | string         | The amount received against that installment before the window closed. `"0.00"` when nothing was received.   |
| `installmentsPaid`    | number         | Installments fully paid on this obligation so far                                                            |
| `installmentsTotal`   | number         | Total installments on this obligation                                                                        |
| `failedAt`            | string         | ISO 8601 timestamp of when the obligation was marked in arrears                                              |

> **One callback per obligation.** The API records the moment an obligation enters arrears and does not send the event a second time for that obligation. Use `guid` to match the callback to the obligation you created.

**`wallet.incoming_credit`**

Legacy alias: `wallet_incoming_credit`. Sent for each deposit of money from outside Spendl into a user's wallet, as soon as the wallet is credited: for example a bank or instant EFT to the user's deposit reference, a Pay@ payment, a Zapper deposit or a hosted checkout deposit. Transfers between users, deposits funded from a tenant wallet and reward payouts do not send it.

It is also sent when Spendl credits one of your [tenant wallets](#create-tenant-wallet) with your accrued tenant fee share (a `tenant_fee_payout` journal entry) or with loan repayments collected from your users (a `debt_installment_settlement` journal entry). `userId` and `email` are then the tenant wallet's. Other money arriving in a tenant wallet does not send it.

Delivery is best effort. Treat `GET /api/wallet/history/:userId` as the source of truth for a user's deposits, and deduplicate on `X-Idempotency-Key`.

*Conditional:* The system sends the event only when the endpoint is configured.

```json
{
  "userId": "507f1f77bcf86cd799439011",
  "email": "john.doe@example.com",
  "previousBalance": 10000,
  "currentBalance": 15000,
  "amount": 5000,
  "transactionId": "6641a2b3c4d5e6f708192a3b",
  "timestamp": "2026-05-21T16:00:00.000Z"
}
```

| Field             | Type   | Description                                                                                  |
| ----------------- | ------ | -------------------------------------------------------------------------------------------- |
| `userId`          | string | The user's Spendl id                                                                         |
| `email`           | string | The user's email address                                                                     |
| `previousBalance` | number | Wallet balance in ZAR cents immediately before this deposit                                  |
| `currentBalance`  | number | Wallet balance in ZAR cents immediately after this deposit                                   |
| `amount`          | number | ZAR cents credited to the wallet, after any deposit fee (`currentBalance - previousBalance`) |
| `transactionId`   | string | The deposit's `_id` in `GET /api/wallet/history/:userId`                                     |
| `timestamp`       | string | ISO 8601 timestamp of when the wallet was credited                                           |

**`wallet.send_to_bank_completed`**

Legacy alias: `wallet_send_to_bank_completed`. Outbound EFT to a registered beneficiary. The API sends this event after a [Send to Bank](#send-to-bank-eft) request succeeds. `userId`, `amount`, `withdrawalOption`, `beneficiaryId`, `description` and `metadata` are as sent; `description` and `metadata` are omitted when not sent. `result` is that request's `200` response body, without `success`.

```json
{
  "userId": "507f1f77bcf86cd799439011",
  "amount": 50000,
  "withdrawalOption": "ONE_DAY",
  "beneficiaryId": "660a1f77bcf86cd799439099",
  "description": "Payment to supplier",
  "metadata": { "reference": "SUP-2026-001" },
  "result": {
    "journalEntryId": "6641a2b3c4d5e6f708192a3b",
    "userId": "507f1f77bcf86cd799439011",
    "amount": 50000,
    "feeAmount": 449,
    "grossDebit": 50449,
    "paymentMethod": "SAME_DAY",
    "status": "posted",
    "payaccsysRef": "PAY-456",
    "payaccsysFee": 5,
    "payaccsysFeeItt": 500
  }
}
```

| Field                    | Type           | Description                                                                                                                                                                                                         |
| ------------------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `result.journalEntryId`  | string         | The payment's journal entry ID                                                                                                                                                                                      |
| `result.amount`          | integer        | ZAR cents the beneficiary is sent                                                                                                                                                                                   |
| `result.feeAmount`       | integer        | The fee charged, in ZAR cents (see [Send to Bank](#send-to-bank-eft))                                                                                                                                               |
| `result.grossDebit`      | integer        | ZAR cents debited from the wallet (`amount + feeAmount`)                                                                                                                                                            |
| `result.paymentMethod`   | string         | `SAME_DAY` for `ONE_DAY`, and for an `IMMEDIATE` amount above the real-time limit; otherwise `PAYSHAP` or `RTC`                                                                                                     |
| `result.status`          | string         | `posted`: the wallet was debited and the bank-payment partner accepted the payment. It does **not** mean the beneficiary has been paid. If the bank rejects the payment later, the amount is returned to the wallet |
| `result.payaccsysRef`    | string \| null | The bank-payment partner's reference for the payment                                                                                                                                                                |
| `result.payaccsysFee`    | number         | The bank-payment partner's fee in rand, for example `5` (R5.00)                                                                                                                                                     |
| `result.payaccsysFeeItt` | integer        | The same fee in ZAR cents                                                                                                                                                                                           |

**`wallet.send_to_bank_failed`**

A [Send to Bank](#send-to-bank-eft) payment failed, and its whole debit, fee included, was returned to the user's wallet. The API sends this event in two cases:

* The payment partner refused the payment when it was submitted. The request answers `502 PAYACCSYS_LOAD_FAILED` with `data.reversed: true`. The event is still sent if your client stopped waiting, as long as Spendl's own request got that answer. If Spendl did not get that answer (for example `504 REQUEST_TIMEOUT`, `502 UPSTREAM_NETWORK_ERROR` or `WALLET_SEND_TO_BANK_FAILED`), no event is sent: retry with the same key, which replays the refusal and sends the event, or check [wallet history](#transaction-history).
* The bank failed or cancelled a payment it had accepted (a `200` with `status: "posted"`, followed by `wallet.send_to_bank_completed`). This can happen minutes later, or for `ONE_DAY` up to the next business day.

The API sends it only when the tenant has a `wallet.send_to_bank_failed` endpoint configured. A refund reported again, for example on a same-key retry of the payment, is sent with the same `X-Idempotency-Key`, so deduplicate on that header. Nothing is sent when the refund itself failed (`PAYACCSYS_EFT_REVERSAL_FAILED`); Spendl support resolves those. Delivery is best effort: in `GET /api/wallet/history/:userId` the payment shows `status: "reversed"`, with a `reversal` row crediting the full debit.

```json
{
  "userId": "507f1f77bcf86cd799439011",
  "journalEntryId": "6641f0a2c3d4e5f6a7b8c9d0",
  "amount": 50000
}
```

| Field            | Type   | Description                                                                                                                                                                     |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `userId`         | string | The user whose wallet was refunded                                                                                                                                              |
| `journalEntryId` | string | The payment's `journalEntryId`: the value in the send-to-bank response and in `data.journalEntryId` on its errors, and the payment's `_id` in `GET /api/wallet/history/:userId` |
| `amount`         | number | The payment amount in ZAR cents, before the fee. The wallet is refunded the full debit (`grossDebit`), fee included                                                             |

**`wallet.beneficiary_added`**

Legacy alias: `wallet_beneficiary_added`. The API sends this event after an [Add Beneficiary](#add-beneficiary) request succeeds. The top-level fields are as sent; `branchName`, `reference` and `supplierType` are omitted when not sent. `result` is that request's `200` response body, without `success`. `result._id` is the `beneficiaryId` for [Send to Bank](#send-to-bank-eft) and [Remove Beneficiary](#remove-beneficiary).

```json
{
  "userId": "507f1f77bcf86cd799439011",
  "bankName": "FNB",
  "accountNumber": "62000000001",
  "accountType": "Cheque",
  "branchCode": "250655",
  "accountHolder": "Jane Smith",
  "reference": "RENT",
  "supplierType": "Individual",
  "result": {
    "_id": "660a1f77bcf86cd799439099",
    "bankName": "FNB",
    "accountNumber": "62000000001",
    "accountType": "Cheque",
    "branchCode": "250655",
    "branchName": null,
    "accountHolder": "Jane Smith",
    "reference": "RENT",
    "supplierCode": "SUP-123",
    "supplierType": "Individual",
    "isActive": true,
    "createdAt": "2026-05-21T13:30:00.000Z"
  }
}
```

**`wallet.beneficiary_removed`**

Legacy alias: `wallet_beneficiary_removed`. The API sends this event after a [Remove Beneficiary](#remove-beneficiary) request succeeds. `userId` and `beneficiaryId` are the path parameters you sent; `beneficiaryId` is the beneficiary's `_id`. `result` is that request's `200` response body.

```json
{
  "userId": "507f1f77bcf86cd799439011",
  "beneficiaryId": "660a1f77bcf86cd799439099",
  "result": {
    "success": true,
    "message": "Beneficiary removed."
  }
}
```

**Remittance Lifecycle Events**

These events describe customer-visible remittance transitions. Fields ending in `Zar` contain positive integer ZAR cents. `receiveAmount`, on the events that carry it, is the amount the recipient receives in `receiveCurrency`, on the same two-decimal transport scale as the transaction's `receiveAmount`: divide it by 100 for display. Event `timestamp` values use ISO 8601. Spendl creates the timestamp when it emits the event, except that `remittance.cashPickupReady` carries the time the voucher was issued, so a re-send shows the same time. The timestamp can differ from the destination transition time. Every event carries `recipientName` and `recipientSurname`, the recipient's names as the sender entered them on the send; `recipientSurname` is `null` when the sender gave no surname, or only spaces. If `recipientSurname` is missing, for example on a resend of an older delivery, treat it as `null`.

Spendl also emails the sender as the transfer progresses: when it is submitted, completed, failed, cancelled or refunded. For a cash pickup, Spendl emails the voucher code when the voucher is ready, and the completed email when the cash is collected. The API sends each event only when the tenant has an endpoint configured for it. No event is sent when a send is accepted: the send response confirms it, and `remittance.submitted` follows when the transfer reaches the destination network.

Every event except `remittance.refunded` carries `thirdPartyTransId`, Spendl's reference for the payout attempt (quote it to Spendl support), and `attempt`: `1` for the first send, and higher for each retry that issued a new reference, whoever made it. For one transfer, `attempt` only increases, but it can skip numbers. A resend of an older delivery may lack both.

Webhooks can arrive out of order. For one transfer, an event with a higher `attempt` is newer. Within an attempt, ignore a `submitted` that arrives after that attempt's `failed`, `cancelled` or `completed`. `completed` and `refunded` are final for the transfer's status; `cashPickupReady` and `cashPickupCollected` can still follow `completed`.

**`remittance.submitted`**

Sent after the remittance network accepts the transaction in a batch acknowledgement. Spendl then changes the status from `pending` to `submitted`. Final delivery stays asynchronous. It is sent again, with a new `thirdPartyTransId` and a higher `attempt`, each time the network accepts a retry of the transfer.

```json
{
  "id": "66a7f1c9b45e8d0012345678",
  "userId": "507f1f77bcf86cd799439011",
  "tenantId": "tenant-ke",
  "thirdPartyTransId": "SPEN-20260728-001",
  "attempt": 1,
  "recipientName": "Amina",
  "recipientSurname": "Kamau",
  "sendAmountZar": 10000,
  "toCountry": "KE",
  "toCurrency": "KES",
  "paymentType": "wallet",
  "receiveAmount": 67750,
  "receiveCurrency": "KES",
  "timestamp": "2026-07-28T12:15:02.000Z"
}
```

`thirdPartyTransId` and `attempt` identify the accepted attempt.

**`remittance.completed`**

Sent only after the destination confirms delivery **and** Spendl has finished settling the transfer. If settling fails, the transfer returns to `processing`, and this event is sent once settling succeeds. For a cash pickup it is sent once: when the voucher is issued, or, if the cash is collected before the voucher is reported issued (for example a transfer that reached `cash_pickup_ready` first), when the cash is collected; only that collected event carries `voucherCollected: true`. It never carries the voucher code: [`remittance.cashPickupReady`](#remittancecashpickupready) does.

```json
{
  "id": "66a7f1c9b45e8d0012345678",
  "userId": "507f1f77bcf86cd799439011",
  "tenantId": "tenant-ke",
  "thirdPartyTransId": "SPEN-20260728-001",
  "attempt": 1,
  "recipientName": "Amina",
  "recipientSurname": "Kamau",
  "sendAmountZar": 10000,
  "toCountry": "KE",
  "receiveAmount": 67750,
  "receiveCurrency": "KES",
  "paymentType": "wallet",
  "timestamp": "2026-07-28T12:18:45.000Z"
}
```

`thirdPartyTransId` and `attempt` identify the attempt that delivered. `voucherCollected: true` appears only on a cash pickup completed by collection; otherwise it is absent.

**`remittance.failed`**

Sent for each failed payout attempt, when the remittance network rejects a batch item or confirms a definitive error for the transfer. A retry that fails again sends it again, with a new `thirdPartyTransId` and a higher `attempt`. This event does not mean that the wallet was refunded: the transfer stays debited. [Retry it](#retry-failed-transfer) if `statusCode` allows; otherwise Spendl handles it. A retry returns it to `submitted`, and you receive the later events. Contact support about a transfer that stays `failed`.

```json
{
  "id": "66a7f1c9b45e8d0012345678",
  "userId": "507f1f77bcf86cd799439011",
  "tenantId": "tenant-ke",
  "thirdPartyTransId": "SPEN-20260728-001",
  "attempt": 1,
  "recipientName": "Amina",
  "recipientSurname": "Kamau",
  "recipientPartnerCode": "KE-MPESA",
  "sendAmountZar": 10000,
  "toCountry": "KE",
  "statusCode": "ER106",
  "timestamp": "2026-07-28T12:45:00.000Z"
}
```

`statusCode` contains the remittance network's acknowledgement or status code, or `null` when no network code is available. `thirdPartyTransId` and `attempt` identify the failed attempt. `recipientPartnerCode` is the `partnerCode` of the send.

**`remittance.cancelled`**

Sent when the remittance network cancels a transfer before it completes: `MR107` (a cash-pickup voucher was cancelled while the transfer was `cash_pickup_ready`) or `MR109` (the transfer was cancelled). A voucher cancelled after its transfer completed doesn't send it: see [Cash Pickup Vouchers](#cash-pickup-vouchers). No refund is booked automatically. Spendl reviews the transfer and then retries or refunds it, and a refund sends `remittance.refunded`. A retry that is cancelled again sends it again, with a new `thirdPartyTransId` and a higher `attempt`.

```json
{
  "id": "66a7f1c9b45e8d0012345678",
  "userId": "507f1f77bcf86cd799439011",
  "tenantId": "tenant-ke",
  "thirdPartyTransId": "SPEN-20260728-001",
  "attempt": 1,
  "recipientName": "Amina",
  "recipientSurname": "Kamau",
  "sendAmountZar": 10000,
  "toCountry": "KE",
  "statusCode": "MR109",
  "timestamp": "2026-07-28T12:05:00.000Z"
}
```

`statusCode` is the remittance network's status code, `MR107` or `MR109`. `thirdPartyTransId` and `attempt` identify the cancelled attempt. Customers cannot cancel a remittance, so `USER_CANCEL` is no longer sent.

**`remittance.cashPickupReady`**

Sent once per voucher, when the voucher is issued. It usually arrives just after `remittance.completed`. It carries `voucherCode`, the code the recipient needs to collect the cash, and `cashPickupPartner`, where they collect it. `voucherCode` is sensitive. Send it only to the intended recipient. Do not log it. A redelivery has the same `X-Idempotency-Key`; deduplicate on it, as with every other event. If Spendl retries a failed cash pickup, a new voucher is issued with a new code, and its event has a new `thirdPartyTransId`, a higher `attempt` and a new idempotency key under the same `id`. Always show the latest code.

```json
{
  "id": "66a7f1c9b45e8d0012345678",
  "userId": "507f1f77bcf86cd799439011",
  "tenantId": "tenant-ke",
  "recipientName": "Amina",
  "recipientSurname": "Kamau",
  "voucherCode": "CP-834921",
  "cashPickupPartner": "Example Cash Network",
  "sendAmountZar": 10000,
  "receiveAmount": 67750,
  "receiveCurrency": "KES",
  "toCountry": "KE",
  "paymentType": "cash_pickup",
  "thirdPartyTransId": "SPEN-20260728-001",
  "attempt": 1,
  "timestamp": "2026-07-28T12:18:46.000Z"
}
```

`voucherCode` is always set. `cashPickupPartner` can be `null` when no partner is recorded for the transfer. `thirdPartyTransId` and `attempt` identify the voucher's attempt. `receiveAmount` uses the same two-decimal transport scale as the transaction's `receiveAmount`: divide it by 100 for display. If you missed this event, read `voucherCode` from [Check Transaction Status](#check-transaction-status).

**`remittance.cashPickupCollected`**

Sent once, when the recipient collects the cash of a cash pickup whose transfer became `completed` when its voucher was issued. Collection is usually reported at least a day after the voucher is issued. A cash pickup collected before its transfer completed sends `remittance.completed` with `voucherCollected: true` instead, never both. Spendl sends it only after it has sent, or tried to send, [`remittance.cashPickupReady`](#remittancecashpickupready) for the transfer, so handle it even if you have no voucher on record. It never carries the voucher code: the code is withheld once the voucher is collected. The endpoint key is `remittance.cashpickupcollected`, in lowercase, and an `RPC` endpoint receives that name as `method`.

```json
{
  "id": "66a7f1c9b45e8d0012345678",
  "userId": "507f1f77bcf86cd799439011",
  "tenantId": "tenant-ke",
  "thirdPartyTransId": "SPEN-20260728-001",
  "attempt": 1,
  "recipientName": "Amina",
  "recipientSurname": "Kamau",
  "sendAmountZar": 10000,
  "toCountry": "KE",
  "receiveAmount": 67750,
  "receiveCurrency": "KES",
  "timestamp": "2026-07-29T09:40:12.000Z"
}
```

`timestamp` is when Spendl recorded the collection. `thirdPartyTransId` and `attempt` identify the voucher's attempt. `receiveAmount` uses the same two-decimal transport scale as on `remittance.cashPickupReady`: divide it by 100 for display. A transfer's cash is collected once, so the event has one idempotency key per transfer. If you missed this event, read `voucherStatus` from [Check Transaction Status](#check-transaction-status).

**`remittance.refunded`**

Sent after Spendl posts the refund journal. This journal returns the remittance debit and fee to the user's wallet.

```json
{
  "id": "66a7f1c9b45e8d0012345678",
  "userId": "507f1f77bcf86cd799439011",
  "tenantId": "tenant-ke",
  "recipientName": "Amina",
  "recipientSurname": "Kamau",
  "sendAmountZar": 10000,
  "toCountry": "KE",
  "feeAmountZar": 500,
  "totalRefundZar": 10000,
  "reason": "Admin manual refund",
  "timestamp": "2026-07-28T12:05:00.000Z"
}
```

`totalRefundZar` is the full original wallet debit. `sendAmountZar` includes the fee. The refund is the amount sent for conversion plus `feeAmountZar`, so it normally equals `sendAmountZar`.

**KYC Status Transitions**

The Public API sends these events immediately for its own verification outcomes, with `kycStatus` `Pending`, `Approved` or `Rejected`. Spendl also sends them when it detects a KYC status change made outside the Public API, and passes that status value through without normalisation. Treat the event name as the signal, and accept `kycStatus` as a free-form string, compared without regard to case.

`kyc.approved` can follow `kyc.rejected` for the same user when Spendl compliance approves a user that verification rejected, and `kyc.rejected` can follow `kyc.approved` when Spendl compliance withdraws an approval. Treat the latest event as the user's KYC status.

**`kyc.approved`**

Legacy alias: `kyc_approved`.

```json
{
  "userId": "507f1f77bcf86cd799439011",
  "email": "john.doe@example.com",
  "kycStatus": "Approved",
  "timestamp": "2026-05-21T14:15:00Z"
}
```

**`kyc.rejected`**

Legacy alias: `kyc_rejected`. `rejectionReason` tells you why verification failed, in text that you can show to the user. It is always present on this event, and is `null` only when no reason is available.

```json
{
  "userId": "507f1f77bcf86cd799439011",
  "email": "john.doe@example.com",
  "kycStatus": "Rejected",
  "rejectionReason": "The name you entered does not match the name registered to your ID number. Please ensure your first name and surname are entered exactly as they appear on your identity document.",
  "timestamp": "2026-05-21T15:00:00Z"
}
```

**`kyc.review_required`**

Legacy alias: `kyc_review_required`. Sent when KYC enters manual review or enhanced due diligence. For Spendl-verified tenants, the API sends this event as soon as verification enters review. The tenant record's KYC status stays `Pending`, and `Pending` is the `kycStatus` value that the API sends. Treat the event itself as the review signal.

For a user created with [Create User from Sumsub Share Token](#create-user-from-sumsub-share-token) whose Sumsub review has not finished 48 hours after the token was redeemed, the API also sends this event with `reasonCode: "SUMSUB_REVIEW_TIMEOUT"` and stops waiting for Sumsub.

For such a user whose Sumsub review cannot finish, the API sends this event with `reasonCode: "SUMSUB_DOCUMENTS_REQUESTED"` and stops waiting, usually within a few minutes of the token being redeemed. Sumsub is waiting for the person because the shared verification does not satisfy Spendl's verification level: a step is not included in it, or a shared item failed Spendl's own check. Contact Spendl with the `userId`; the event does not say which. If Sumsub reports neither, the 48-hour notice above applies instead.

`reviewReasonCodes` lists why Spendl verification sent the user to review. The key is always present. It is `[]` when no Spendl check explains the review: a review set on your side, a Sumsub review, or either Sumsub notice above. A user can have more than one code. The list is sorted and has no repeats. Spendl's compliance team works every review; a code tells your support team what is being checked, not that the user must act.

```json
{
  "userId": "507f1f77bcf86cd799439011",
  "email": "john.doe@example.com",
  "kycStatus": "Pending",
  "reviewReasonCodes": ["NAME_MATCH_LOW_CONFIDENCE"],
  "timestamp": "2026-05-21T15:30:00Z"
}
```

**Review reason codes**

| Code                               | Meaning                                                                                                                             |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `NAME_MATCH_LOW_CONFIDENCE`        | The name entered is close to, but not exactly, the name on the national identity register, for example a spelling difference.       |
| `COMPLIANCE_REVIEW`                | Spendl's compliance team must review the user. No further detail is shared. Do not ask the user to resubmit.                        |
| `DOCUMENT_CHECK_UNAVAILABLE`       | The identity document could not be read automatically, so it is checked by hand.                                                    |
| `DOCUMENT_AUTHENTICITY_UNVERIFIED` | The identity document was read, but its authenticity could not be confirmed automatically.                                          |
| `ID_VERIFICATION_UNAVAILABLE`      | The ID number could not be checked against the national identity register because the check was unavailable.                        |
| `SCREENING_UNAVAILABLE`            | A compliance screening check was unavailable.                                                                                       |
| `POR_NAME_MISMATCH`                | The name on the proof of residence does not match the name submitted. It may be in another person's name, so it is checked by hand. |
| `POR_ADDRESS_MISMATCH`             | The address on the proof of residence does not match the residential address submitted.                                             |
| `POR_DOCUMENT_OUTDATED`            | The proof of residence is older than 3 months.                                                                                      |
| `POR_DOCUMENT_FUTURE_DATED`        | The date on the proof of residence is in the future.                                                                                |
| `POR_DATE_UNVERIFIED`              | The date on the proof of residence could not be read, so it is checked by hand.                                                     |
| `POR_DOCUMENT_UNAVAILABLE`         | The proof of residence could not be fetched, so it is checked by hand.                                                              |

`POR_*` codes are no longer sent from v1.87. A user who went to review before then may still show one.

New codes may be added. Treat a code you do not recognise as a general review.

**Wallet & Compliance Status Transitions**

Spendl sends these events when it detects a change to the user's wallet or compliance status. It passes status fields through without changes.

Spendl records each transition once and then delivers it at least once. A user's status events arrive one at a time, in the order they were detected, after any of that user's earlier KYC lifecycle events. A redelivery carries the same `X-Idempotency-Key`; deduplicate on it.

**`wallet.suspended`**

Legacy alias: `wallet_suspended`.

```json
{
  "userId": "507f1f77bcf86cd799439011",
  "email": "john.doe@example.com",
  "walletStatus": "SUSPENDED",
  "timestamp": "2026-05-21T16:30:00Z"
}
```

**`wallet.closed`**

Legacy alias: `wallet_closed`.

```json
{
  "userId": "507f1f77bcf86cd799439011",
  "email": "john.doe@example.com",
  "walletStatus": "CLOSED",
  "timestamp": "2026-05-21T17:00:00Z"
}
```

**`compliance.hold_set`**

Legacy alias: `compliance_hold_set`. Sent when the system places a compliance hold on a user. A hold prevents wallet activity.

```json
{
  "userId": "507f1f77bcf86cd799439011",
  "email": "john.doe@example.com",
  "complianceStatus": "HOLD",
  "timestamp": "2026-05-21T17:30:00Z"
}
```

**`compliance.hold_cleared`**

Legacy alias: `compliance_hold_cleared`. Sent when the system releases a compliance hold.

```json
{
  "userId": "507f1f77bcf86cd799439011",
  "email": "john.doe@example.com",
  "complianceStatus": "CLEAR",
  "timestamp": "2026-05-21T18:00:00Z"
}
```

#### Idempotency Keys

Every dispatch includes `X-Idempotency-Key`: an opaque key, **stable across redeliveries** of the same event. Use it to remove duplicates. Compare keys whole, and do not parse them or rely on their format. The event family determines when the key changes:

| Event family                                                                                                                                                        | Key                                                                                                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Default (most lifecycle events)                                                                                                                                     | One key per event and record                                                                                                                                   |
| Account updates                                                                                                                                                     | One key per accepted update                                                                                                                                    |
| Wallet activity events (`wallet.*_completed`)                                                                                                                       | One key per event and wallet operation                                                                                                                         |
| KYC lifecycle transitions                                                                                                                                           | One key per event and KYC revision                                                                                                                             |
| KYC attempt transitions (`submitting`, `submitted`, terminal failures, validation start)                                                                            | One key per event, KYC revision and attempt                                                                                                                    |
| KYC document uploads                                                                                                                                                | One key per upload                                                                                                                                             |
| KYC status changes made outside the Public API                                                                                                                      | One key per transition. A KYC status change that recurs on the same KYC revision, such as a user rejected again after they were approved again, gets a new key |
| Account, wallet and compliance status transitions (`account.status_changed`, `compliance.hold_set`, `compliance.hold_cleared`, `wallet.suspended`, `wallet.closed`) | One key per transition. A transition that recurs later, such as a wallet suspended again after it was reactivated, gets a new key                              |
| Public API-owned `kyc.approved` / `kyc.rejected`                                                                                                                    | One key per event and KYC revision. When Spendl compliance changes an outcome already sent for the same KYC revision, the new event gets a new key             |
| `kyc.review_required` from Spendl verification                                                                                                                      | Stable across retries of the same submission. A KYC resubmission produces a new key                                                                            |
| `kyc.review_required` for an unfinished Sumsub review                                                                                                               | One key per KYC revision and Sumsub applicant                                                                                                                  |
| `wallet.debt_repayment_failure`                                                                                                                                     | One key per obligation, because the event is sent once per obligation                                                                                          |
| `wallet.incoming_credit`                                                                                                                                            | One key per deposit                                                                                                                                            |
| `wallet.send_to_bank_failed`                                                                                                                                        | One key per refunded payment, however the failure was reported                                                                                                 |
| Remittance events                                                                                                                                                   | One key per event name and transfer                                                                                                                            |
| `remittance.submitted`, `remittance.failed`, `remittance.cancelled`, `remittance.cashPickupReady`                                                                   | One key per payout attempt: a retry's events get new keys, and a retried cash pickup's new voucher a new key                                                   |

#### Delivery, Headers & Wire Formats

All outbound webhooks use the same delivery process:

**Headers**

Every dispatch includes:

| Header              | Description                                                                                                                                                                                                                            |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Content-Type`      | `application/json` for REST/RPC, `application/x-www-form-urlencoded` for FORM                                                                                                                                                          |
| `X-Idempotency-Key` | An opaque key, stable for each logical delivery. The API reuses the value across retries. Use it to remove duplicates on your side; do not parse it. See [Idempotency Keys](#idempotency-keys).                                        |
| `X-Signature`       | Integrity and authenticity signature over the exact request body bytes. The value is `hmac-sha256=<hex>` when a tenant HMAC secret is configured, and `sha256=<hex>` otherwise. See [Signature Verification](#signature-verification). |
| `Authorization`     | Present when your tenant is configured with `BASIC` or `JWT` authentication. The API omits the header for `NONE`.                                                                                                                      |

**Wire Format**

Each tenant endpoint uses one of three wire formats. Ask your account manager to configure the format:

* **`REST`** *(default)* — The API `POST`s the payload as JSON, exactly as shown in the sections above.
* **`RPC`** — The payload is wrapped in a JSON-RPC 2.0 envelope:

  ```json
  {
    "jsonrpc": "2.0",
    "id": "<uuid>",
    "method": "bank_account_created",
    "params": {
      "success": true,
      "account": {
        "spendlUserId": "507f1f77bcf86cd799439011",
        "bankAccountNumber": "1234567890",
        "branchCode": "250655",
        "bankName": "ABSA",
        "accountHolderName": "John Doe",
        "uniqueDepositReference": "ACM00000001",
        "currency": "ZAR"
      }
    }
  }
  ```

  `method` is the event name in lowercase, so a camelCase event arrives as, for example, `remittance.cashpickupcollected`. An RPC endpoint can report a failure through the HTTP status. It can also return HTTP 200 with `result.status >= 400`. A `5xx` HTTP status or a `result.status` of `500` or more causes a retry. A `4xx` HTTP status or a `result.status` from `400` to `499` is a permanent failure and is not retried.
* **`FORM`** — The API flattens the whole payload to `application/x-www-form-urlencoded`. It joins nested keys with `.`. For example, the KYC callback becomes `success=true&account.spendlUserId=507f...&account.bankAccountNumber=1234567890&...`.

**Authentication**

Spendl supports three authentication schemes for each tenant endpoint:

| Scheme  | `Authorization` Header       |
| ------- | ---------------------------- |
| `NONE`  | *(the API sends no header)*  |
| `BASIC` | `Basic <base64-credentials>` |
| `JWT`   | `Bearer <token>`             |

Spendl stores credentials in the secure tenant configuration. Contact your account manager to update or rotate the credentials.

**Signature Verification**

Every dispatch includes `X-Signature`. Spendl calculates the signature from the **exact HTTP request body bytes**. For `REST` and `RPC`, these bytes are UTF-8 JSON. For `FORM`, the bytes are the URL-encoded string. The format is `<scheme>=<lowercase-hex>`:

| Scheme        | When Used                                                                                                                                             | Header Value                     |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| `hmac-sha256` | Your tenant has an `hmacSecret` configured. This is the recommended scheme. It verifies both **integrity** and **authenticity**.                      | `X-Signature: hmac-sha256=<hex>` |
| `sha256`      | No `hmacSecret` is configured. This is the fallback scheme. It verifies **integrity only**, because anyone with the body bytes can produce this hash. | `X-Signature: sha256=<hex>`      |

To enable HMAC mode, add `hmacSecret` through Spendl secure settings. Ask your account manager to set or rotate the secret.

If you have an `hmacSecret`, reject any `X-Signature` that is not `hmac-sha256`. Anyone can compute a plain `sha256` value, so never accept one as a fallback once you have a secret.

**Node.js (Express) verification example**

```js
const crypto = require("crypto");

// secret: your hmacSecret, or null if you have none. Spendl trims surrounding
// whitespace from the secret before signing, so the sample trims it too.
// rawBody: the exact request body bytes (a Buffer), captured before parsing.
function verifySpendlSignature(rawBody, header, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof header !== "string") return false;
  const sep = header.indexOf("=");
  if (sep < 1) return false;
  const scheme = header.slice(0, sep);
  const hex = header.slice(sep + 1);
  if (!/^[0-9a-f]{64}$/.test(hex)) return false;

  const key = typeof secret === "string" ? secret.trim() : "";
  let expected;
  if (key) {
    // With an hmacSecret, accept only hmac-sha256. Reject sha256= and anything else.
    if (scheme !== "hmac-sha256") return false;
    expected = crypto.createHmac("sha256", key).update(rawBody).digest();
  } else {
    // Without an hmacSecret, Spendl sends sha256= (integrity only).
    if (scheme !== "sha256") return false;
    expected = crypto.createHash("sha256").update(rawBody).digest();
  }

  const received = Buffer.from(hex, "hex");
  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

// Express: keep the raw bytes while parsing (use the same verify option on express.urlencoded for FORM endpoints).
// const keepRawBody = (req, res, buf) => { req.rawBody = buf; };
// app.use(express.json({ verify: keepRawBody }));
// app.use(express.urlencoded({ extended: false, verify: keepRawBody }));
// const ok = verifySpendlSignature(req.rawBody, req.get("X-Signature"), process.env.SPENDL_HMAC_SECRET || null);
```

**Bash / openssl example**

```bash
# HMAC mode
echo -n "$RAW_BODY" | openssl dgst -sha256 -hmac "$SPENDL_HMAC_SECRET" | awk '{print "hmac-sha256="$2}'

# Fallback mode
echo -n "$RAW_BODY" | openssl dgst -sha256 | awk '{print "sha256="$2}'
```

> **Use `timingSafeEqual`** or an equivalent constant-time function. This function prevents timing attacks during signature comparison.
>
> **Capture the raw body** before the framework parses JSON. Serializing the parsed object again can change byte order or whitespace. These changes can break verification.
>
> The plain `sha256` fallback detects transport corruption. For production traffic, always configure an `hmacSecret`.

***

### Data Reference

#### User Fields

Send these fields under `userDetails` in the standard format:

| Field    | Type   | Required | Description                                                             |
| -------- | ------ | -------- | ----------------------------------------------------------------------- |
| `email`  | string | Yes      | Valid email address, unique ignoring case. Stored trimmed and lowercase |
| `status` | string | No       | One of: `active`, `inactive`, `suspended`, `pending`                    |

#### KYC Data Fields

Send these fields under `kycDetails.kycData` in standard format or directly in flat format:

| Field                      | Type    | Description                                                                                                                                                                                                                                                                                                                         |
| -------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `productType`              | string  | Account type: `"Wallet"`, `"Smart"`, `"Savvy"`, `"Guru"`. Defaults to `"Wallet"` for flat-format payloads when omitted. **Required** if `identityType` is supplied. See [Account Types](#account-types)                                                                                                                             |
| `identityType`             | string  | Identity document type: `"ID_CARD"`, `"GREEN_BOOK"`, `"PASSPORT"`, `"ASYLUM_SEEKER"`, `"REFUGEE_PERMIT"`. **Required** if `productType` is supplied. Must be valid for the chosen `productType` — see [FICA Identity Requirements](#fica-identity-requirements). Needed to send remittances (see [Sender Profile](#sender-profile)) |
| `name`                     | string  | First name. **Required.** Send it as it appears on the identity document, with any apostrophes, accents and hyphens; the identity document check ignores them (accents on Latin letters only)                                                                                                                                       |
| `surname`                  | string  | Last name. **Required.** Send it as it appears on the identity document, with any apostrophes, accents and hyphens; the identity document check ignores them (accents on Latin letters only)                                                                                                                                        |
| `dob`                      | string  | Date of birth (ISO 8601). **Required.**                                                                                                                                                                                                                                                                                             |
| `idNumber`                 | string  | Identity document number. Needed to send remittances (see [Sender Profile](#sender-profile))                                                                                                                                                                                                                                        |
| `idIssue`                  | string  | Identity document issue date                                                                                                                                                                                                                                                                                                        |
| `idExpiry`                 | string  | Identity document expiry date                                                                                                                                                                                                                                                                                                       |
| `identityIssueCountry`     | string  | Country that issued the identity document. Needed to send remittances (see [Sender Profile](#sender-profile))                                                                                                                                                                                                                       |
| `phone`                    | string  | Primary phone number. Needed to send remittances (see [Sender Profile](#sender-profile))                                                                                                                                                                                                                                            |
| `altPhone`                 | string  | Alternate phone number                                                                                                                                                                                                                                                                                                              |
| `altEmail`                 | string  | Secondary email address                                                                                                                                                                                                                                                                                                             |
| `nationality`              | string  | ISO 3166-1 alpha-2 country code (e.g., `"ZA"`) or country name                                                                                                                                                                                                                                                                      |
| `gender`                   | string  | `M` or `F` (`Male`, `Female`, `O` and `Other` are also accepted). Used by identity verification — see [Verification fields](#verification-fields)                                                                                                                                                                                   |
| `title`                    | string  | Title: `"Dr"`, `"Me"`, `"Miss"`, `"Mr"`, `"Mrs"`, `"Ms"`, `"Other"` or `"Prof"`                                                                                                                                                                                                                                                     |
| `languageIndicator`        | string  | Preferred language                                                                                                                                                                                                                                                                                                                  |
| `suitableContactTime`      | string  | Preferred contact time, 24-hour `HH:mm` (e.g., `"12:00"`). `"12h00"` is still accepted                                                                                                                                                                                                                                              |
| `residenceIndicator`       | string  | Residence indicator                                                                                                                                                                                                                                                                                                                 |
| `residenceCountry`         | string  | Country of residence (ISO code)                                                                                                                                                                                                                                                                                                     |
| `pepPip`                   | string  | Politically exposed person / prominent influential person declaration                                                                                                                                                                                                                                                               |
| `permitType`               | string  | Permit type (for non-citizens)                                                                                                                                                                                                                                                                                                      |
| `permitNumber`             | string  | Permit number                                                                                                                                                                                                                                                                                                                       |
| `permitIssue`              | string  | Permit issue date                                                                                                                                                                                                                                                                                                                   |
| `permitExpiry`             | string  | Permit expiry date                                                                                                                                                                                                                                                                                                                  |
| `company`                  | string  | Employer or company name                                                                                                                                                                                                                                                                                                            |
| `employmentStatus`         | string  | e.g., `"employed"`, `"self-employed"`, `"unemployed"`                                                                                                                                                                                                                                                                               |
| `sourceOfFunds`            | string  | Primary income source                                                                                                                                                                                                                                                                                                               |
| `intendedPurposeOfAccount` | string  | Intended purpose of the account                                                                                                                                                                                                                                                                                                     |
| `streetNumber`             | string  | Street number                                                                                                                                                                                                                                                                                                                       |
| `addressLine1`             | string  | Primary address line                                                                                                                                                                                                                                                                                                                |
| `addressLine2`             | string  | Secondary address line                                                                                                                                                                                                                                                                                                              |
| `suburb`                   | string  | Suburb or district                                                                                                                                                                                                                                                                                                                  |
| `city`                     | string  | City name. Needed to send remittances (see [Sender Profile](#sender-profile))                                                                                                                                                                                                                                                       |
| `province`                 | string  | State or province. For a card: a South African province name or abbreviation (e.g., `"Gauteng"` or `"GP"`) or `"Lesotho"`                                                                                                                                                                                                           |
| `postalCode`               | string  | Postal code                                                                                                                                                                                                                                                                                                                         |
| `country`                  | string  | Country name                                                                                                                                                                                                                                                                                                                        |
| `addressType`              | string  | Address type                                                                                                                                                                                                                                                                                                                        |
| `residenceStatus`          | string  | Residence status                                                                                                                                                                                                                                                                                                                    |
| `tncAccepted`              | boolean | Whether terms and conditions were accepted                                                                                                                                                                                                                                                                                          |
| `tncAcceptedAt`            | string  | ISO 8601 timestamp of acceptance                                                                                                                                                                                                                                                                                                    |

#### Attribution Fields

The API adds these read-only attribution fields to each record that you create:

| Field               | Type   | Description                                      |
| ------------------- | ------ | ------------------------------------------------ |
| `createdByApiKeyId` | string | Your API key ID                                  |
| `createdByTenant`   | string | Your organisation name (from your API key label) |
| `createdAt`         | string | ISO 8601 creation timestamp                      |
| `updatedAt`         | string | ISO 8601 last-update timestamp                   |

KYC document uploads include per-document attribution:

| Field                | Type   | Description                             |
| -------------------- | ------ | --------------------------------------- |
| `uploadedByApiKeyId` | string | API key that uploaded the document      |
| `uploadedByTenant`   | string | Organisation that uploaded the document |
| `uploadedAt`         | string | ISO 8601 upload timestamp               |

#### Sync Pipeline Statuses

Returned by [GET /api/ingest/status/:id](#check-ingestion-status):

| Phase           | Field                  | Possible Values                                                                                                        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| --------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Registration    | `registrationStatus`   | `pending`, `registered`, `failed`                                                                                      | Whether the user was registered in Spendl                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Account Details | `detailsSyncStatus`    | `pending`, `syncing`, `synced`, `failed`, `null`                                                                       | Whether the latest account details have been applied                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| KYC Submission  | `kycSubmissionStatus`  | `pending`, `submitted`, `failed`, `not_ready`                                                                          | Whether KYC data was forwarded                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| KYC Validation  | `kycValidation.status` | `pending`, `in_progress`, `activated`, `tgpd_rejected`, `tgpd_review`, `failed`, `superseded` (legacy: `tgpd_pending`) | The outcome of KYC verification. `activated` means approved and active. `activated` with `kycStatus: Rejected` means that Spendl compliance later withdrew the approval. `tgpd_rejected` with `kycStatus: Approved` means that Spendl compliance approved the user after verification rejected them. `tgpd_review` means that manual review is required (see [`kyc.review_required`](#kycreview_required)). `superseded` means that a later KYC update restarted verification. `tgpd_pending` is deprecated and appears only on older records. |
| Callback        | `callbackStatus`       | `pending`, `sent`, `failed`, `null`                                                                                    | Whether the webhook was delivered                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

> `not_ready` means that the user's KYC data is incomplete. Required personal fields can be missing: `name`, `surname`, or `dob`. Documents for the user's FICA tier can also be missing. See [FICA Identity Requirements](#fica-identity-requirements). The system checks again during later processing cycles.

#### Debt Processing Statuses

Returned by [GET /api/debt/status/:guid](#check-debt-obligation-status):

| Status            | Description                                        |
| ----------------- | -------------------------------------------------- |
| `pending`         | Obligation received, not yet processed             |
| `forwarded`       | Obligation processed; the callback is not sent yet |
| `callback_sent`   | Callback delivered — fully complete                |
| `callback_failed` | Obligation processed, callback delivery failed     |
| `failed`          | Processing failed (see `errorMessage` field)       |

### Crypto API

Use the Crypto API to manage a user's crypto balances, deposits, withdrawals, and market sells. All endpoints require a Bearer token. All endpoints are tenant-scoped.

Identify the user with `userId` as a query parameter on GET requests and in the JSON body on POST requests. Market data does not take a user id.

`userId` is the user's Spendl id (24 hexadecimal characters, as returned by user ingestion). Any other format returns `422 VALIDATION_ERROR`. The user must belong to your tenant: an unknown user, or a user of another tenant, returns `404 USER_NOT_FOUND` and nothing else happens.

Supported assets today: USDT, USDC, ETH, BTC, SOL, XRP, AVAX, BNB, DOGE, LINK, SHIB, TRX. A pair is the asset plus `ZAR`, for example `BTCZAR`.

A filled sell is **not** a wallet credit and **not** an instant card load. Poll the order status until the order is filled. Spendl loads the proceeds to the user's card later, in a separate step that this API does not report.

#### Conventions

* A GET request that acts on a user requires `userId`.
* `POST /api/crypto/withdrawals` and `POST /api/crypto/place-order` require an idempotency key. Send it as the `X-Idempotency-Key` header or as `idempotencyKey` in the body. The key must be 8–128 characters. A missing key returns `422 MISSING_IDEMPOTENCY_KEY`. Body and header values that conflict return `422 IDEMPOTENCY_KEY_MISMATCH`. Do not reuse a key for a different request.
* Use one idempotency key per user action and keep it until you have a final answer. If the request times out or fails with a network error, returns a 5xx whose message says to retry with the same idempotency key (such as `502 UPSTREAM_NETWORK_ERROR`), or returns `409 CRYPTO_RECONCILE_PENDING`, `409 IDEMPOTENCY_KEY_IN_PROGRESS` or `409 ORDER_IN_FLIGHT`, retry with the **same** key. Not every 5xx is a lost answer: `CRYPTO_NOT_CONFIGURED` (`503` or `500`) and a `502` with the message `Crypto service is temporarily unavailable` (a temporary Spendl-side error) carry no such message; contact Spendl if they persist. `409 CRYPTO_NOT_SUBMITTED` means the earlier attempt never reached the provider and nothing moved; submit again with a new key. `409 IDEMPOTENCY_KEY_PAYLOAD_MISMATCH` means the key was already used with a different body: resend the original body, and use a new key only for a genuinely new request. A retry with the same key returns the original result and never sells or withdraws twice. A new key is a new order or withdrawal.
* An XRP deposit address can include a destination tag. Send both the address and the tag on chain.
* Place-order usually returns `202`. Poll `GET /api/crypto/order-status/:orderId`. While the order is pending, that GET can return `204 No Content` with an empty body. Continue to poll. Do not treat `204` as terminal or as a JSON parse failure.

#### Deposit flow

1. Call `GET /api/crypto/deposit-addresses?userId=...` once the user's KYC is approved.
2. Send the chain transaction to the returned address (and tag when present).
3. Poll `GET /api/crypto/deposits` and `GET /api/crypto/balances`.

#### Withdrawal flow

1. Call `GET /api/crypto/withdrawals-config/:currency` and `GET /api/crypto/service-providers?userId=...`.
2. Create the withdrawal with `POST /api/crypto/withdrawals` and a unique idempotency key. If the request times out, or returns a 5xx whose message says to retry with the same idempotency key, the withdrawal may still have been sent: retry with the **same** key until you get the final result.
3. Poll `GET /api/crypto/withdrawals/:withdrawalId`.

#### Sell flow

1. Call `POST /api/crypto/estimate-trade` (quote only; no idempotency header).
2. Place a market **SELL** with `POST /api/crypto/place-order` and a unique idempotency key. The user needs a linked card; otherwise place-order returns `400 CARD_REQUIRED`.
3. Poll `GET /api/crypto/order-status/:orderId`. A **204 No Content** response means that the order is still pending. Continue to poll. The response is not terminal and is not a JSON parse failure. A filled order does not credit the Spendl wallet and does not load a card.

Poll until you get a terminal result (`FILLED`, `FAILED` or `400 TOO_SMALL`). If you stop early, Spendl completes the sale later, which delays the card payout.

#### Market data

```
GET /api/crypto/market-data
GET /api/crypto/market-data?pairs=BTCZAR,ETHZAR
GET /api/crypto/market-data/BTCZAR
```

Both routes accept only these pairs, in upper or lower case: USDTZAR, USDCZAR, ETHZAR, BTCZAR, SOLZAR, XRPZAR, AVAXZAR, BNBZAR, DOGEZAR, LINKZAR, SHIBZAR, TRXZAR. Any other pair returns `400 UNSUPPORTED_PAIR`; a `:pair` under 4 or over 16 characters fails validation first with `422 VALIDATION_ERROR`. In `pairs`, one unsupported pair refuses the whole list.

#### Deposit addresses

```
GET /api/crypto/deposit-addresses?userId=64b7f0c2a1d3e4f5a6b7c8d9
```

Needs approved KYC: any other KYC status returns `403 KYC_REQUIRED` and no addresses. Addresses already issued to a user stay live: a deposit sent to one is still credited, even while this read returns `403`.

```bash
curl -s "$BASE/api/crypto/deposit-addresses?userId=64b7f0c2a1d3e4f5a6b7c8d9" \
  -H "Authorization: Bearer $TOKEN"
```

#### Deposits

```
GET /api/crypto/deposits?userId=64b7f0c2a1d3e4f5a6b7c8d9
```

#### Balances

```
GET /api/crypto/balances?userId=64b7f0c2a1d3e4f5a6b7c8d9
```

```bash
curl -s "$BASE/api/crypto/balances?userId=64b7f0c2a1d3e4f5a6b7c8d9" \
  -H "Authorization: Bearer $TOKEN"
```

#### Service providers

```
GET /api/crypto/service-providers?userId=64b7f0c2a1d3e4f5a6b7c8d9
```

#### Withdrawals config

```
GET /api/crypto/withdrawals-config/BTC?userId=64b7f0c2a1d3e4f5a6b7c8d9
```

`:currency` must be one of the [supported assets](#crypto-api), in upper or lower case. Any other coin returns `400 UNSUPPORTED_CURRENCY`; a `:currency` under 2 or over 16 characters fails validation first with `422 VALIDATION_ERROR`.

#### Create withdrawal

```
POST /api/crypto/withdrawals
X-Idempotency-Key: <8-128 unique chars>
Authorization: Bearer <token>
Content-Type: application/json

{
  "userId": "64b7f0c2a1d3e4f5a6b7c8d9",
  "currency": "BTC",
  "amount": "0.01",
  "address": "bc1qexample"
}
```

```bash
curl -s -X POST "$BASE/api/crypto/withdrawals" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"userId":"64b7f0c2a1d3e4f5a6b7c8d9","currency":"BTC","amount":"0.01","address":"bc1qexample"}'
```

Optional body fields: `beneficiaryName`, `isCorporate`, `isSelfHosted`, `networkType`, `serviceProviderId`, `serviceProviderName`.

`currency` must be one of the [supported assets](#crypto-api), in upper or lower case. Any other coin returns `400 UNSUPPORTED_CURRENCY`: nothing is sent, and the idempotency key stays unused. A `currency` under 2 or over 16 characters fails validation first with `422 VALIDATION_ERROR`.

If the request times out, or returns a 5xx whose message says to retry with the same idempotency key (such as `502 UPSTREAM_NETWORK_ERROR`), the withdrawal may still have been sent. Retry the same request with the **same** idempotency key until you get the final result. Do not use a new key, because a new key sends a second withdrawal. `409 CRYPTO_RECONCILE_PENDING` means the same; `data.pendingId` identifies the withdrawal when it is available. `CRYPTO_NOT_CONFIGURED` (`503` or `500`) and a `502` with the message `Crypto service is temporarily unavailable` (a temporary Spendl-side error) carry no such message; contact Spendl if they persist.

#### List and get withdrawals

```
GET /api/crypto/withdrawals?userId=64b7f0c2a1d3e4f5a6b7c8d9
GET /api/crypto/withdrawals/:withdrawalId?userId=64b7f0c2a1d3e4f5a6b7c8d9
GET /api/crypto/withdrawal-addresses?userId=64b7f0c2a1d3e4f5a6b7c8d9
```

The list returns `{ "withdrawals": [ ... ] }`. Get-by-id returns `{ "withdrawal": { ... } }`.

#### Transactions

```
GET /api/crypto/transactions?userId=64b7f0c2a1d3e4f5a6b7c8d9&limit=20&offset=0
```

`offset` cannot exceed 500.

#### Estimate trade

```
POST /api/crypto/estimate-trade
Content-Type: application/json

{
  "userId": "64b7f0c2a1d3e4f5a6b7c8d9",
  "pair": "BTCZAR",
  "quantity": "0.01",
  "withdrawalOption": "ONE_DAY"
}
```

`quantity` can be a JSON number or a numeric string, for example `0.01` or `"0.01"`. `withdrawalOption` is `IMMEDIATE` or `ONE_DAY`. This call does not place an order.

```bash
curl -s -X POST "$BASE/api/crypto/estimate-trade" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"userId":"64b7f0c2a1d3e4f5a6b7c8d9","pair":"BTCZAR","quantity":"0.01","withdrawalOption":"ONE_DAY"}'
```

#### Place order

```
POST /api/crypto/place-order
X-Idempotency-Key: <8-128 unique chars>
Authorization: Bearer <token>
Content-Type: application/json

{
  "userId": "64b7f0c2a1d3e4f5a6b7c8d9",
  "pair": "BTCZAR",
  "side": "SELL",
  "quantity": "0.01",
  "withdrawalOption": "ONE_DAY"
}
```

The API accepts only a market SELL. `side` is optional and defaults to `SELL`. Any other value, including lowercase `sell`, returns `422 VALIDATION_ERROR`.

The usual success status is `202`:

```json
{
  "orderId": "0199a3b2-7c4d-7e8f-9a0b-1c2d3e4f5a6b",
  "customerOrderId": "itt-3f9c0d2e8b7a6f5e4d3c2b1a0f9e",
  "withdrawalOption": "ONE_DAY"
}
```

Poll the order status with `orderId`. Treat `customerOrderId` as an opaque string. A retry with the same idempotency key returns the same value.

A user without a linked card gets `400 CARD_REQUIRED` and nothing is sold.

If the request times out, or returns a 5xx whose message says to retry with the same idempotency key (such as `502 UPSTREAM_NETWORK_ERROR`), the order may still have been placed. Retry with the **same** idempotency key, as for `409 CRYPTO_RECONCILE_PENDING` below. `CRYPTO_NOT_CONFIGURED` (`503` or `500`) and a `502` with the message `Crypto service is temporarily unavailable` (a temporary Spendl-side error) carry no such message; contact Spendl if they persist.

If the response is `409 CRYPTO_RECONCILE_PENDING`, the order may already have been accepted and is still being confirmed. Retry the same request with the **same** idempotency key until you get the final result. Do not use a new key, because a new key places a second order. `data.customerOrderId` identifies the order when it is available.

```bash
curl -s -X POST "$BASE/api/crypto/place-order" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"userId":"64b7f0c2a1d3e4f5a6b7c8d9","pair":"BTCZAR","side":"SELL","quantity":"0.01","withdrawalOption":"ONE_DAY"}'
```

#### Order status

```
GET /api/crypto/order-status/:orderId?userId=64b7f0c2a1d3e4f5a6b7c8d9&pair=BTCZAR
```

Poll until the order reaches a terminal status. **204 No Content** means that the order is still pending. Continue to poll. `204` is not a terminal result and is not a JSON parse failure, because the body is empty. A filled sell is not a wallet credit and not an instant card load.

| Response                       | Meaning                                                                            | Body                                                                                                       |
| ------------------------------ | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `204`                          | Pending                                                                            | Empty. Continue to poll                                                                                    |
| `200` `status: "PARTIAL"`      | Partly filled and still open                                                       | `orderId`, `status`, `executedQuantity`, `requestedQuantity`, `orderStatusType`. Continue to poll          |
| `200` `status: "FAILED"`       | Terminal. Nothing was sold                                                         | `orderId`, `status`, `orderStatusType`, and sometimes `executedQuantity` (`0`) and `requestedQuantity`     |
| `200` `status: "FILLED"`       | Terminal. Sold                                                                     | See below. Every later poll returns the same body                                                          |
| `400` `TOO_SMALL`              | Terminal. The order filled, but nothing is left after fees, so nothing is paid out | Error envelope. `data` can include `reason` and the fee breakdown. Every later poll returns the same error |
| `409` `ORDER_SETTLE_IN_FLIGHT` | Filled and still settling                                                          | Error envelope. Poll again in a few seconds                                                                |

A filled order:

```json
{
  "orderId": "0199a3b2-7c4d-7e8f-9a0b-1c2d3e4f5a6b",
  "status": "FILLED",
  "pair": "BTCZAR",
  "asset": "BTC",
  "executedQty": 0.01,
  "executedZar": 12000,
  "tradeFees": 12,
  "handlingFees": 239.76,
  "withdrawalFeeZar": 9,
  "bankDepositFeeZar": 2.75,
  "finalAmountCredited": 11739.24,
  "expectedCardCreditZar": 11736.49,
  "price": 1200000,
  "filledAt": "2026-09-30T09:15:42.000Z",
  "withdrawalOption": "ONE_DAY"
}
```

| Field                   | Type           | Description                                                              |
| ----------------------- | -------------- | ------------------------------------------------------------------------ |
| `executedQty`           | number         | Quantity of `asset` sold                                                 |
| `executedZar`           | number         | Gross ZAR value of the sale                                              |
| `tradeFees`             | number         | Trading fee in ZAR                                                       |
| `handlingFees`          | number         | Spendl handling fee in ZAR                                               |
| `withdrawalFeeZar`      | number         | Payout fee in ZAR for the chosen `withdrawalOption`                      |
| `bankDepositFeeZar`     | number         | Bank deposit fee in ZAR                                                  |
| `finalAmountCredited`   | number         | ZAR after trading, handling and payout fees, before the bank deposit fee |
| `expectedCardCreditZar` | number         | Expected card credit in ZAR after all fees. For display only             |
| `price`                 | number \| null | Average fill price in ZAR per unit, when known                           |
| `pair`, `asset`         | string \| null | The sold pair and asset, when known                                      |
| `filledAt`              | string \| null | Fill time, UTC ISO 8601, when known                                      |
| `withdrawalOption`      | string         | `IMMEDIATE` or `ONE_DAY`                                                 |

#### Error envelope

```json
{
  "error": {
    "message": "An idempotency key is required for crypto withdrawals and place-order",
    "code": 422,
    "type": "MISSING_IDEMPOTENCY_KEY"
  }
}
```

| Error Type                         | HTTP Code                                        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ---------------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `VALIDATION_ERROR`                 | 422                                              | A parameter is invalid, for example a `userId` that is not a Spendl id or a `side` other than `SELL`                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `MISSING_IDEMPOTENCY_KEY`          | 422                                              | The withdrawal or place-order request has no idempotency key                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `IDEMPOTENCY_KEY_MISMATCH`         | 422                                              | The body key and the header key differ                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `USER_NOT_FOUND`                   | 404                                              | The `userId` does not exist in your tenant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `KYC_REQUIRED`                     | 403                                              | The user's KYC is not approved. Deposit addresses, withdrawals and place-order only                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `ACCOUNT_RESTRICTED`               | 403                                              | The user's account is restricted from sending money. Withdrawals and place-order only. Retrying does not help                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `TENANT_SUSPENDED`                 | 403                                              | Your tenant is suspended. Retrying does not help; contact Spendl                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `INSUFFICIENT_SCOPE`               | 403                                              | The token has no `read` scope (GET) or no `write` scope (POST)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `CRYPTO_RECONCILE_PENDING`         | 409                                              | A place-order or withdrawal may already have been accepted and is still being confirmed. Retry with the **same** idempotency key; never a new one. `data` can include `customerOrderId` (orders), `pendingId` (withdrawals) and `pair`                                                                                                                                                                                                                                                                                                                               |
| `CRYPTO_NOT_CONFIGURED`            | 503 or 500                                       | Crypto is not enabled for this tenant. Retrying does not help; contact Spendl                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `CRYPTO_PROVIDER_ERROR`            | 4xx or 5xx                                       | The crypto provider rejected or could not process the request. The HTTP code is the provider's result, or `502`                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `CRYPTO_*_FAILED`                  | `502`, or the status the crypto service returned | The endpoint's own failure type, for example `CRYPTO_PLACE_ORDER_FAILED`, used when the crypto service fails without a more specific type. On a read, a `502` or `503` has the message `Upstream service unavailable` (`Upstream server error` for a `500`). On a withdrawal or place-order, a `5xx` message says to retry with the same idempotency key, because the request may still have gone through. A `502` with the message `Crypto service is temporarily unavailable` is a temporary Spendl-side error (this type or `CRYPTO_PROVIDER_ERROR`); retry later |
| `UPSTREAM_NETWORK_ERROR`           | 502                                              | Network timeout or connectivity failure. On a withdrawal or place-order the request may still have gone through: retry with the same idempotency key, as the message says                                                                                                                                                                                                                                                                                                                                                                                            |
| `CRYPTO_NOT_SUBMITTED`             | 409                                              | An earlier withdrawal attempt with this key never reached the provider; nothing moved. Submit again with a new idempotency key                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `IDEMPOTENCY_KEY_IN_PROGRESS`      | 409                                              | A withdrawal or place-order with this key is still being processed. Retry with the **same** key to get the final result                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `IDEMPOTENCY_KEY_PAYLOAD_MISMATCH` | 409                                              | The key was already used with a different request body. Resend the original body; use a new key only for a genuinely new request                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `ORDER_IN_FLIGHT`                  | 409                                              | Place-order only: another sell of the same pair for this user is still being placed. Nothing was sold for this request. Wait a moment and retry with the **same** key                                                                                                                                                                                                                                                                                                                                                                                                |
| `CARD_REQUIRED`                    | 400                                              | Place-order only: the user has no linked card. Nothing was sold. `data.reason` is `CARD_REQUIRED`                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `ORDER_SETTLE_IN_FLIGHT`           | 409                                              | Order status only: the sale is filled and its proceeds are still being settled. Poll again in a few seconds                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `TOO_SMALL_AFTER_BANK`             | 400                                              | Estimate only: nothing would reach the card after the bank deposit fee. `data` carries the estimate breakdown with `cardNetAfterBankZar: 0`                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `TOO_SMALL`                        | 400                                              | Place-order: nothing is left after fees, and nothing is sold. Order status: the order filled but nothing is left after fees; this is terminal. There is no other minimum. `data` can include `reason` and the fee breakdown                                                                                                                                                                                                                                                                                                                                          |
| `NO_SUBACCOUNT`                    | 400                                              | The user has no crypto account yet. `GET /api/crypto/deposit-addresses` creates it once the user's KYC is approved                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `BENEFICIARY_REQUIRED`             | 400                                              | Withdrawal without `beneficiaryName`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `SERVICE_PROVIDER_REQUIRED`        | 400                                              | Withdrawal to an exchange wallet (`isSelfHosted` not `true`) without `serviceProviderId` or `serviceProviderName`                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `WITHDRAWALS_DISABLED`             | 400                                              | Withdrawals of this coin are currently disabled                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `BELOW_MIN`                        | 400                                              | The amount is below the coin's minimum; `data.minimumWithdrawAmount` gives it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `INSUFFICIENT_BALANCE`             | 400                                              | The amount plus the network fee is more than the available balance                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `UNSUPPORTED_PAIR`                 | 400                                              | Market data only: the pair is not supported. See [Market data](#market-data)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `UNSUPPORTED_CURRENCY`             | 400                                              | Withdrawals config and create withdrawal only: the coin is not one of the [supported assets](#crypto-api). No withdrawal is sent. `data.currency` can give the coin                                                                                                                                                                                                                                                                                                                                                                                                  |

On a withdrawal or place-order, a `408` or `429 CRYPTO_PROVIDER_ERROR` may have gone through: retry with the same key. `INSUFFICIENT_BALANCE`, `BELOW_MIN`, `WITHDRAWALS_DISABLED`, `NO_SUBACCOUNT` (withdrawals), `TOO_SMALL`, `INVALID_INPUT` for a destination tag the coin does not take (withdrawals), or a provider `4xx CRYPTO_PROVIDER_ERROR` (other than `408` and `429`) that refuses the withdrawal or order itself moved nothing, but spend the key for 24 hours: a retry returns the same error. Other `400`s (for example `UNSUPPORTED_CURRENCY` and most `INVALID_INPUT`s) leave the key unused.

A `401` from these endpoints always means that your Bearer token is missing, invalid or expired. A Spendl-side error is never reported as `401` or `403`.

#### Wallet Error Codes

| Error Type                       | HTTP Code | Description                                                                                                                                                                                       |
| -------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `WALLET_DEPOSIT_FAILED`          | 5xx       | Outcome unknown: the deposit may have moved. Retry with the same key                                                                                                                              |
| `WALLET_TRANSFER_FAILED`         | 5xx       | Outcome unknown: the transfer may have moved. Retry with the same key; see [Error Outcomes](#error-outcomes)                                                                                      |
| `WALLET_LOAD_CARD_FAILED`        | 5xx       | Outcome unknown: the card load may have moved. Retry with the same key                                                                                                                            |
| `CARD_NOT_FOUND`                 | 404       | Card load `cardId` is not one of the user's cards                                                                                                                                                 |
| `CARD_NOT_FUNDABLE`              | 422       | Card load, `fund_card` channel only: the card is closed or expired, and the wallet was refunded (`data.reversed: true`). Spends the key; do not retry with this card. See [Load Card](#load-card) |
| `WALLET_SEND_TO_BANK_FAILED`     | 5xx       | Outcome unknown: the payment may have moved. Retry with the same key; see [Error Outcomes](#error-outcomes)                                                                                       |
| `WALLET_PURCHASE_VOUCHER_FAILED` | 5xx       | Outcome unknown: the purchase may have moved. Retry with the same key                                                                                                                             |
| `WALLET_REPAY_DEBT_FAILED`       | 5xx       | Outcome unknown: the repayment may have moved. Retry with the same key                                                                                                                            |
| `WALLET_BALANCE_FETCH_FAILED`    | 502       | The wallet balance could not be retrieved. Retry later                                                                                                                                            |
| `WALLET_HISTORY_FETCH_FAILED`    | 502       | The wallet history could not be retrieved. Retry later                                                                                                                                            |
| `INSUFFICIENT_FUNDS`             | 422       | User does not have enough funds                                                                                                                                                                   |
| `BENEFICIARY_NOT_FOUND`          | 404       | Beneficiary does not exist or is inactive                                                                                                                                                         |
| `UPSTREAM_NETWORK_ERROR`         | 502       | Network timeout or connectivity failure                                                                                                                                                           |

***

### Cards API

Use the Cards API to read a user's Spendl Card. The API returns the card list, masked card details, the balance, transactions, monthly funding limits, the bank account used to load the card, and what a user still needs before Spendl can issue a card. All endpoints are `GET`. All endpoints require a Bearer token with the `read` scope and are tenant-scoped. The API is read-only. It does not support card lifecycle operations such as freeze, PIN, and reissue.

Identify the user with `userId` in the path. Get a user's `cardId` values from `GET /api/cards/:userId`. With a `cardId`, use `POST /api/wallet/load-card` to top up the card.

#### Conventions

* All monetary fields are **integer ZAR cents**. Their names end in `Itt`. No response contains a decimal amount.
* Card numbers are always masked, for example `400000****0002`. No endpoint returns a full card number or a CVV.
* All card reads except [card readiness](#card-readiness) require the user's KYC to be `Approved`. Other requests return `403 KYC_REQUIRED`.
* A user without a card returns an empty `cards` list. This is not an error. The `funding-account` response then has `accountNumber: null`.
* A `userId` from another tenant, or an unknown `userId`, returns `404 USER_NOT_FOUND`. A `cardId` that does not belong to the user returns `404 CARD_NOT_FOUND`.
* `cardId` is an **opaque string** of at most 64 characters. Store it and send it back exactly as you received it. Do not parse it and do not assume a format.
* All timestamps (`dateIssued`, and the transaction `date` and `clearedDate`) are UTC ISO 8601, for example `2026-01-01T00:00:00Z`. They are `null` when the card issuer has no value.
* `cardStatus` is always one of the values below. `feeType` and `provisionStatus` are open lists. Spendl can add new values without a version change, so handle an unrecognised value gracefully.

| `cardStatus` | Meaning                                                                        |
| ------------ | ------------------------------------------------------------------------------ |
| `ACTIVE`     | The card is active. This is the only status in which the card is fully usable. |
| `INACTIVE`   | The card is not active                                                         |
| `LOCKED`     | The card is locked                                                             |
| `RESTRICTED` | The card issuer has restricted the card                                        |
| `LOST`       | The card was reported lost                                                     |
| `STOLEN`     | The card was reported stolen                                                   |
| `EXPIRED`    | The card has expired                                                           |
| `CLOSED`     | The card is closed                                                             |
| `UNKNOWN`    | The card issuer did not report a recognised status                             |

#### List cards

```
GET /api/cards/:userId
```

```bash
curl -s "$BASE/api/cards/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer $TOKEN"
```

```json
{
  "userId": "507f1f77bcf86cd799439011",
  "cards": [
    {
      "cardId": "1000001",
      "maskedCardNumber": "400000****0002",
      "cardStatus": "ACTIVE",
      "dateIssued": "2026-01-01T00:00:00Z",
      "currency": "ZAR"
    }
  ]
}
```

If the card issuer cannot serve the details of one card, that card degrades to `{ "cardId": "…", "detailsUnavailable": true }`. The whole list does not fail.

#### Card details

```
GET /api/cards/:userId/card/:cardId
```

Returns `{ "userId": "…", "card": { … } }` with the same masked card shape as the list.

#### Card balance

```
GET /api/cards/:userId/card/:cardId/balance
```

```json
{
  "cardId": "1000001",
  "availableItt": 125050,
  "actualItt": 130000,
  "currency": "ZAR",
  "cardStatus": "ACTIVE",
  "asOf": "2026-09-23T10:15:00.000Z"
}
```

The balance can be up to about 30 seconds old. `asOf` is the time at which the Public API served the response, not the time the balance was read.

#### Card transactions

```
GET /api/cards/:userId/card/:cardId/transactions?from=2026-08-25&to=2026-09-23
```

* `from` and `to` use the format `YYYY-MM-DD` and are inclusive. If you omit `to`, it defaults to today in South African time. If you omit `from`, it defaults to 29 days before the effective `to`. The response echoes the effective window.
* The card issuer serves at most **90 days** of history. A wider window returns `422 CARD_DATE_RANGE_TOO_LARGE`. Malformed or inverted dates return `422 CARD_DATE_RANGE_INVALID`.

```json
{
  "cardId": "1000001",
  "from": "2026-08-25",
  "to": "2026-09-23",
  "transactions": [
    {
      "transId": "TX-99812",
      "description": "POS Purchase - Woolworths",
      "date": "2026-09-22T14:03:11.000Z",
      "clearedDate": "2026-09-23T02:00:00.000Z",
      "debitItt": 24999,
      "creditItt": 0,
      "amountItt": -24999,
      "currency": "ZAR",
      "isFee": false,
      "feeType": null
    }
  ]
}
```

**Polling.** There is no cursor and no card-transaction webhook. This is an issuer constraint. To track new activity, poll a short trailing window. Every 1–5 minutes is reasonable. Remove duplicates with `transId`. `amountItt` is negative for a debit and positive for a credit. `isFee` and `feeType` classify issuer fees.

`isFee` is the issuer's own fee flag. `feeType` is the issuer's fee type, or `null` when the issuer supplies none. Known `feeType` values are listed below. This is an open list, so handle an unrecognised value gracefully.

`EFT_IN_FEE`, `RTC_IN_FEE`, `POS_FEE`, `POS_SIGNATURE_FEE`, `POS_PIN_DECLINE_FEE`, `POS_SIG_DECLINE_FEE`, `ECOM_3DS_FEE`, `SMS_NOTIFICATION_FEE`, `SMS_OTP_FEE`, `CARD_ACTION_SMS_FEE`, `STATEMENT_FEE`, `IVR_FEE`, `AVAIL_FUNDS_DECLINE_FEE`.

#### Funding limits

```
GET /api/cards/:userId/limits
```

```json
{
  "userId": "507f1f77bcf86cd799439011",
  "productType": "Savvy",
  "periodKey": "2026-09",
  "periodStart": "2026-08-31T22:00:00.000Z",
  "periodEnd": "2026-09-30T21:59:59.999Z",
  "fundingLimitItt": 10000000,
  "fundingUsedItt": 250000,
  "fundingRemainingItt": 9750000
}
```

These are **funding** limits. They are the KYC-tier cap on how much you can load onto the card in each calendar month: Smart R25,000, Savvy R100,000, and Guru R500,000. They are not a spending limit on the card itself. The month window follows South African local time. `fundingUsedItt` is the month's total of posted card loads, including load fees. The Spendl app enforces the cap against the same figure. `productType` echoes the tier on record. If a user's tier is missing, or is outside the three card tiers, the API reports the Savvy cap. The Spendl app applies the same default.

#### Funding account

```
GET /api/cards/:userId/funding-account
```

```json
{
  "userId": "507f1f77bcf86cd799439011",
  "bank": "Bank Zero Mutual Bank",
  "accountType": "Current",
  "branchCode": "888000",
  "branchName": "UNIVERSAL",
  "accountNumber": "1234567890",
  "currency": "ZAR",
  "provisionStatus": "Provisioned"
}
```

`accountNumber` is `null` until Spendl provisions a card. `provisionStatus` gives the reason. This is not an error state. Known `provisionStatus` values are `Provisioned`, `Pending`, and `Failed`. The value is `null` when card provisioning has not started. This is an open list.

#### Card readiness

```
GET /api/cards/:userId/readiness
```

Before Spendl can issue a card, the user needs a card product, complete KYC details, and the correct documents. This endpoint reports exactly what is still missing. It works **before** KYC approval, and it never changes the user.

```json
{
  "userId": "507f1f77bcf86cd799439011",
  "productType": "Savvy",
  "cardEligible": true,
  "ready": false,
  "missingFields": ["gender", "province"],
  "invalidFields": [{ "field": "dob", "reason": "must be a YYYY-MM-DD date" }],
  "missingDocuments": ["idProofFront"]
}
```

* `cardEligible` is `true` when `productType` is `Smart`, `Savvy`, or `Guru`. A `Wallet` user has no card.
* `ready` is `true` only when the user is card-eligible and all three lists are empty.
* Field names are the [KYC Data Fields](#kyc-data-fields) names. Document names are the `documentType` values that you use when you upload KYC documents.
* The report reflects the KYC details and documents last submitted to Spendl. After you update KYC or upload a document, check again when the submission completes.

**What a card needs**

| Requirement           | Details                                                                                                                                                                                                                                                      |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Fields                | `productType`, `identityType`, `name`, `surname`, `dob` (`YYYY-MM-DD`), `phone`, `idNumber`, `gender`, `title`, `nationality`, `addressLine1`, `suburb`, `city`, `province`, `postalCode`                                                                    |
| South African ID      | For `ID_CARD` and `GREEN_BOOK`, `idNumber` must be a valid 13-digit South African ID number whose first six digits match `dob` (`YYMMDD`)                                                                                                                    |
| Passport holders      | `idExpiry`                                                                                                                                                                                                                                                   |
| Guru passport holders | `permitNumber`, `permitIssue`, `permitExpiry`                                                                                                                                                                                                                |
| ID document           | `idProofFront` and `idProofBack` for `ID_CARD` (only `idProofFront` if your tenant is set up for [ID card front only](#fica-identity-requirements)). `idProofFront` for `GREEN_BOOK`. `proofPassport` for `PASSPORT`, `ASYLUM_SEEKER`, and `REFUGEE_PERMIT`. |
| Work permit           | `proofPermit` for Guru passport holders. No tier needs `proofRes` (proof of residence)                                                                                                                                                                       |

#### Cards Error Types

| Error Type                       | HTTP Code | Description                                               |
| -------------------------------- | --------- | --------------------------------------------------------- |
| `KYC_REQUIRED`                   | 403       | The user's KYC is not `Approved`                          |
| `USER_NOT_FOUND`                 | 404       | The user is unknown or belongs to another tenant          |
| `CARD_NOT_FOUND`                 | 404       | The `cardId` is not one of the user's cards               |
| `CARD_DATE_RANGE_INVALID`        | 422       | `from` or `to` is malformed, or `from` is after `to`      |
| `CARD_DATE_RANGE_TOO_LARGE`      | 422       | The window exceeds the issuer's 90-day cap                |
| `CARD_BALANCE_FETCH_FAILED`      | 502       | The card balance could not be retrieved. Retry later      |
| `CARD_DETAILS_FETCH_FAILED`      | 502       | The card details could not be retrieved. Retry later      |
| `CARD_TRANSACTIONS_FETCH_FAILED` | 502       | The card transactions could not be retrieved. Retry later |
| `CARD_LIMITS_FETCH_FAILED`       | 502       | Funding usage is temporarily unavailable                  |
| `CARD_PROVIDER_ERROR`            | varies    | The card provider rejected the request                    |
| `CARDS_NOT_CONFIGURED`           | 500       | The card provider is not configured for this environment  |
| `UPSTREAM_NETWORK_ERROR`         | 502       | Network timeout or connectivity failure                   |

***

### Journal API

Use the Journal API to read your own double-entry ledger: one journal entry by its ID, a filtered list of entries, an activity summary, and the trial balance. All endpoints are `GET`, need a Bearer token with the `read` scope, and are read-only. Every request reads only your tenant's ledger, which the access token decides; no parameter can select another tenant.

A journal entry is one money movement: a deposit, a transfer, a card load, a payout, and so on. The wallet mutations return its ID as `journalEntryId`, and [Transaction History](#transaction-history) returns it as `_id`. Use [Get Journal Entry](#get-journal-entry) to read that entry later, for example to reconcile it.

#### Journal Conventions

* Amounts are **integer ZAR cents** (`1 cent = 0.01 ZAR`).
* Each entry has two or more lines in `entries`. A line debits (positive `amount`) or credits (negative `amount`) one ledger account, and the lines of an entry always sum to zero. A user's wallet account has the code `2000-<userId>`; system accounts have four-digit codes.
* Fee lines: `4010` (Tenant fee revenue) holds the fee you set with `feeAmount` (`requestedFeeAmount` on a Pay@ or Zapper deposit) and, where Spendl has agreed one with you, your share of Spendl's voucher payout fee or of the remittance service fee (Spendl's remittance fee revenue `4100` holds the rest of that fee; a remittance refund returns both); `4000` (Transaction fees) holds Spendl's own provider tariff (`providerFeeAmount`), less any share of it on `4010`; `5000` (Payment processing fees) holds payment processing costs, booked by `provider_fee` entries; these move no money between you, your users and Spendl. An entry can carry more than one `4000` or `5000` line; sum by account code. A `fee_reclassification` entry re-tags a fee that was booked on `4000` earlier (to `4010`, or to Spendl's tariff); it moves no money between you, your users and Spendl. A `tenant_fee_payout` entry credits your accrued tenant fee share to you: it debits `4010` by its whole balance and credits one of your [tenant wallets](#create-tenant-wallet) (`2000-<tenantWalletUserId>`).
* Voucher payout fee share: on a `voucher_payout_settlement`, `metadata.feeAmount` and `providerFeeAmount` are the whole fee; the `4010` credit is your share and `4000` holds the rest, so read the split from the lines. A share booked after the fee arrives as a `fee_reclassification` entry (debit `4000`, credit `4010`) whose `sourceJournalEntryId` is the `voucher_payout_settlement`. A `tenant_fee_payout` pays it out with the rest of `4010`.
* `status` is `posted`, `reversed`, `pending`, or `failed`. Entries are never edited: a correction is a new `reversal` entry. When the original then shows `status: "reversed"`, its `reversedBy` is set to the reversal's ID and the reversal's `reversalOf` to the original. Other reversals leave the original `posted` and both fields `null`.
* `userId` is the user the entry belongs to, or `null` for a system entry. `initiatedBy` says who started it: `user`, `system`, `admin`, `cron`, or `api`, or `null` when unknown.
* `metadata` carries only the fee fields that [Wallet Operations](#wallet-operations) describes (`amount`, `feeAmount`, `netAmount`, `grossAmount`, `requestedFeeAmount`, `providerFeeAmount`, each when present), `sourceJournalEntryId` and `sourceWallet` when present, and the `partner` metadata you supplied. `sourceJournalEntryId` is the ID of the entry in your ledger that this entry was booked for: for example, a `voucher_payout_settlement` carries the ID of the `voucher_payout` whose fee it records. Read that entry with [Get Journal Entry](#get-journal-entry). `sourceWallet` is on a `deposit` funded from one of your tenant wallets: the `_id` of that tenant wallet, in lowercase.
* `type` is one of: `deposit`, `transfer`, `transfer_escrow`, `fiat_withdrawal`, `card_load`, `voucher_purchase`, `voucher_redemption`, `voucher_settlement`, `voucher_payout`, `voucher_payout_settlement`, `debt_repayment`, `debt_installment`, `debt_settlement_batch`, `expense_recording`, `reversal`, `payat_deposit`, `payat_settlement`, `payat_payout_auth`, `payat_payout_completion`, `payat_payout_void`, `zapper_payment`, `zapper_refund`, `zapper_deposit`, `zapper_settlement`, `checkout_deposit`, `checkout_settlement`, `request_payment`, `remittance_submit`, `remittance_settled`, `remittance_refund`, `remittance_manual_refund`, `remittance_fx_settlement`, `crypto_pool_credit`, `crypto_card_load`, `reconciliation_adjustment`, `fee_reclassification`, `provider_fee`, `tenant_fee_payout`, `debt_installment_settlement`, or `other`. `other` is an entry type Spendl has not published yet, and Spendl can add types without a version change, so handle an unrecognised value gracefully.
* Dates accept an ISO 8601 date (`2026-10-15`) or timestamp (`2026-10-15T08:00:00Z`). `dateTo` is inclusive: a date without a time covers that whole UTC day.

#### Get Journal Entry

```
GET /api/journal/entries/:journalId
```

| Parameter   | In   | Required | Description                                                                 |
| ----------- | ---- | -------- | --------------------------------------------------------------------------- |
| `journalId` | Path | Yes      | The entry's ID (24 hexadecimal characters), as returned in `journalEntryId` |

```bash
curl -s "$BASE/api/journal/entries/6641a1b2c3d4e5f6a7b8c9d0" \
  -H "Authorization: Bearer $TOKEN"
```

**Response (200 OK):**

```json
{
  "_id": "6641a1b2c3d4e5f6a7b8c9d0",
  "type": "deposit",
  "status": "posted",
  "userId": "507f1f77bcf86cd799439011",
  "initiatedBy": "user",
  "entries": [
    { "accountCode": "2000-507f1f77bcf86cd799439021", "amount": 50000 },
    { "accountCode": "2000-507f1f77bcf86cd799439011", "amount": -49750 },
    { "accountCode": "4010", "amount": -250 }
  ],
  "metadata": { "amount": 50000, "feeAmount": 250, "netAmount": 49750, "sourceWallet": "507f1f77bcf86cd799439021" },
  "reversalOf": null,
  "reversedBy": null,
  "postedAt": "2026-10-15T08:00:01.120Z",
  "createdAt": "2026-10-15T08:00:01.002Z"
}
```

This `deposit` entry is funded from a tenant wallet: the tenant wallet's `2000-<tenantWalletUserId>` account is debited the gross `amount`, the user's wallet is credited the net amount and `4010` the fee. `metadata.sourceWallet` names the tenant wallet. A deposit funded from the suspense account debits the suspense account instead of a tenant wallet and has no `metadata.sourceWallet`.

The API returns the entry in any status, including `pending` and `failed`. An entry that is not in your ledger returns `404 JOURNAL_ENTRY_NOT_FOUND`, whether it does not exist or belongs to another tenant.

#### List Journal Entries

```
GET /api/journal/entries?status=posted&dateFrom=2026-10-01&limit=50
```

| Parameter     | In    | Required | Description                                                                                                                                                                                                                                                        |
| ------------- | ----- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `page`        | Query | No       | Page number, 1–1000 (default: 1)                                                                                                                                                                                                                                   |
| `limit`       | Query | No       | Entries per page, 1–200 (default: 20)                                                                                                                                                                                                                              |
| `sort`        | Query | No       | `postedAt` or `status`; prefix `-` for descending (default: `-postedAt`)                                                                                                                                                                                           |
| `type`        | Query | No       | An entry type from [Conventions](#journal-conventions), except `other` and `remittance_fx_settlement`                                                                                                                                                              |
| `status`      | Query | No       | `posted`, `reversed`, `pending`, or `failed`                                                                                                                                                                                                                       |
| `dateFrom`    | Query | No       | Earliest `postedAt` (inclusive)                                                                                                                                                                                                                                    |
| `dateTo`      | Query | No       | Latest `postedAt` (inclusive)                                                                                                                                                                                                                                      |
| `userId`      | Query | No       | Only entries for this user. Needs `dateFrom` (see below)                                                                                                                                                                                                           |
| `initiatedBy` | Query | No       | Who started the entry: `user`, `system`, `admin`, `cron`, or `api` (ignored when `userId` is set). Needs `dateFrom`                                                                                                                                                |
| `accountCode` | Query | No       | Only entries with a line on this system account: `1000`, `1100`, `1200`, `1210`, `1220`, `1300`, `1310`, `1500`, `1510`, `1600`, `1610`, `1620`, `1700`, `1800`, `1900`, `2200`, `2210`, `2300`, `2400`, `2410`, `3900`, `4000`, `4010`, `4100`, `5000`, or `5100` |
| `minAmount`   | Query | No       | Smallest amount in cents: the entry's amount, or with `accountCode` the amount of a line on that account (see below). Needs `dateFrom`                                                                                                                             |
| `maxAmount`   | Query | No       | Largest amount in cents, read the same way as `minAmount`. Needs `dateFrom`                                                                                                                                                                                        |

`minAmount` and `maxAmount` filter on the entry's amount: the sum of its debit (positive) lines, for example `50000` for the deposit in [Get Journal Entry](#get-journal-entry). With `accountCode`, they filter instead on a line on that account, by its amount without the sign, so a debit or a credit line can match, and both limits apply to that same line.

A query that uses `userId`, `initiatedBy`, `accountCode`, `minAmount`, or `maxAmount` must give `dateFrom`, and the period from `dateFrom` to `dateTo` (default: now) can be at most **366 days**. Otherwise it returns `422 JOURNAL_DATE_RANGE_TOO_LARGE` with `data.maxDays: 366`. To cover more, request consecutive periods. A query that uses only `type`, `status`, `sort`, and the dates has no date limit. Spendl may lift the limit for a filter later, but will not add one to a query that has none today.

**Response (200 OK):**

```json
{
  "items": [
    {
      "_id": "6641a1b2c3d4e5f6a7b8c9d0",
      "type": "deposit",
      "status": "posted",
      "userId": "507f1f77bcf86cd799439011",
      "initiatedBy": "user",
      "entries": [ { "accountCode": "2000-507f1f77bcf86cd799439021", "amount": 50000 }, { "accountCode": "2000-507f1f77bcf86cd799439011", "amount": -49750 }, { "accountCode": "4010", "amount": -250 } ],
      "metadata": { "amount": 50000, "feeAmount": 250, "netAmount": 49750, "sourceWallet": "507f1f77bcf86cd799439021" },
      "reversalOf": null,
      "reversedBy": null,
      "postedAt": "2026-10-15T08:00:01.120Z",
      "createdAt": "2026-10-15T08:00:01.002Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 50,
  "totalPages": 1
}
```

Each item has the fields of [Get Journal Entry](#get-journal-entry).

#### Journal Summary

```
GET /api/journal/summary?dateFrom=2026-10-01&dateTo=2026-10-15
```

| Parameter  | In    | Required | Description                                              |
| ---------- | ----- | -------- | -------------------------------------------------------- |
| `dateFrom` | Query | No       | Start of the period by `postedAt` (default: 30 days ago) |
| `dateTo`   | Query | No       | End of the period, inclusive (default: now)              |

The period can be at most **366 days**, counting an omitted `dateFrom` as 30 days ago and an omitted `dateTo` as now. A longer period returns `422 JOURNAL_DATE_RANGE_TOO_LARGE` with `data.maxDays: 366`. To cover more, request consecutive periods.

**Response (200 OK):**

```json
{
  "period": { "from": "2026-10-01T00:00:00.000Z", "to": "2026-10-16T00:00:00.000Z" },
  "totals": {
    "deposits": { "count": 42, "totalCents": 2100000 },
    "transfers": { "count": 7, "totalCents": 85000 },
    "ownAccountTransfers": { "count": 2, "totalCents": 20000 }
  },
  "byDay": [
    { "date": "2026-10-01", "count": 3, "totalCents": 150000, "byType": { "deposit": { "count": 3, "totalCents": 150000 } } }
  ],
  "feeByDay": [ { "date": "2026-10-01", "revenueCents": 750, "expenseCents": 0 } ],
  "accountBalances": { "1000": { "name": "Treasury pool", "balanceCents": 1250000 } }
}
```

`totals` always lists `deposits`, `cardLoads`, `reversals`, `expenses`, `fiatWithdrawals`, `voucherPayouts`, `payatDeposits`, `zapperDeposits`, `zapperPayments`, `checkoutDeposits`, `remittanceSubmits`, `transfers`, and `ownAccountTransfers`; a type with no entries has `count: 0`. `ownAccountTransfers` counts moves between a user's main balance and their sub-accounts; they are `transfer` entries, but they are not included in `transfers`, and `byDay[].byType` counts them as `own_account_transfer`, not `transfer`. `own_account_transfer` is a summary bucket only, not an entry type: the entries `type` filter does not accept it, and `type=transfer` returns these moves together with the other transfers. `totalCents` sums the absolute amount of each entry's first line. The totals are gross: every entry in the period counts at its full amount under its own type, including one that was reversed later, and a reversal counts as an entry of its own, in `reversals` and as type `reversal` in `byDay` (its `count` and `totalCents` included), on the day it was posted. Reversals are not netted against the entries they reverse. If Spendl adds net figures, they will be new fields, and these fields keep their meaning. `byDay[].byType` uses the entry types in [Conventions](#journal-conventions), `other` included, and `own_account_transfer`. `period.to` is exclusive when `dateTo` is a date without a time: it is the next UTC midnight. `accountBalances` lists your active system accounts by code, without per-user wallet accounts. `feeByDay[].revenueCents` sums the fee revenue credited to `4000`, `4010` and `4100`, and `expenseCents` the payment processing costs debited to `5000`.

#### Trial Balance

```
GET /api/journal/trial-balance
```

**Response (200 OK):**

```json
{
  "balanced": true,
  "totalBalance": 0,
  "accountCount": 128,
  "assetTotal": 1250000,
  "liabilityTotal": -1240000,
  "equityTotal": 0,
  "revenueTotal": -10000,
  "expenseTotal": 0,
  "inactiveAccountCount": 2,
  "inactiveBalance": 0
}
```

`totalBalance` sums every account balance in your ledger, deactivated accounts included, and is `0` in a healthy ledger: `balanced` is `true` exactly then. `inactiveBalance` is the part of it still held by deactivated accounts. If `balanced` is `false`, contact your Spendl account manager.

#### Journal Error Types

| Error Type                           | HTTP Code | Description                                                                                                                                                              |
| ------------------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `VALIDATION_ERROR`                   | 422       | A malformed `journalId`, or a query parameter outside the values above (including a `type` or `accountCode` that is not listed)                                          |
| `JOURNAL_DATE_RANGE_TOO_LARGE`       | 422       | The summary period, or the period of an entries query that filters by user, initiator, account, or amount, is longer than 366 days or has no `dateFrom` (`data.maxDays`) |
| `INVALID_DATE`                       | 400       | `dateFrom` or `dateTo` is not a valid date                                                                                                                               |
| `INVALID_DATE_RANGE`                 | 400       | `dateFrom` is after `dateTo`                                                                                                                                             |
| `INVALID_AMOUNT_RANGE`               | 400       | `minAmount` is greater than `maxAmount`                                                                                                                                  |
| `FORBIDDEN`                          | 403       | This API key cannot read journal entries                                                                                                                                 |
| `JOURNAL_ENTRY_NOT_FOUND`            | 404       | No entry with this `journalId` in your ledger                                                                                                                            |
| `JOURNAL_ENTRY_FETCH_FAILED`         | 502       | The entry could not be retrieved. Retry later                                                                                                                            |
| `JOURNAL_ENTRIES_FETCH_FAILED`       | 502       | The entry list could not be retrieved. Retry later                                                                                                                       |
| `JOURNAL_SUMMARY_FETCH_FAILED`       | 502       | The summary could not be retrieved. Retry later                                                                                                                          |
| `JOURNAL_TRIAL_BALANCE_FETCH_FAILED` | 502       | The trial balance could not be retrieved. Retry later                                                                                                                    |
| `UPSTREAM_NETWORK_ERROR`             | 502       | Network timeout or connectivity failure                                                                                                                                  |

***

### Support

For technical questions or problems, contact your Spendl integration partner or account manager.

* 2026-11-17: v1.108 — Unsupported crypto coins, card load history line, set-password invite
  * **Changed:** [Withdrawals config](#withdrawals-config) and [Create withdrawal](#create-withdrawal) return `400 UNSUPPORTED_CURRENCY` for a coin that is not one of the [supported assets](#crypto-api).

No withdrawal is sent, and the idempotency key stays unused.

A value under 2 or over 16 characters still fails validation first with `422 VALIDATION_ERROR`.

The [crypto error table](#error-envelope) lists it

* **Changed:** in [Transaction History](#transaction-history), a `card_load` description gives only the amount loaded onto the card, for example `Card load of R40.00`.

The fee and the payment method stay in `metadata` (`feeAmount`, `paymentMethod`)

* **Corrected:** [Update Account Details](#update-account-details): after an email change, the set-password invite is sent to the new address only if your tenant sends Spendl's set-password emails.

These are on by default, even when your tenant's other emails are switched off

* Bumped public API doc version to 1.108
* 2026-11-16: v1.107 — Spendl compliance's suspensions stay in place
  * **Changed:** an account Spendl compliance has suspended or deleted keeps that status until Spendl changes it.

[Update Account Details](#update-account-details) refuses a `userDetails.status` for it with `409 ACCOUNT_HELD`, and nothing is applied.

[Replace KYC Details](#replace-kyc-details) still replaces the KYC data and restarts KYC, but the account status is no longer reset to `pending` or set to `active`, and a verification that needs review can be approved only once Spendl changes the status.

A suspension you made yourself works as before

* Bumped public API doc version to 1.107
* 2026-11-16: v1.106 — Deposits are funded from a tenant wallet
  * **Changed:** [`POST /api/wallet/deposit`](#deposit-funds) requires `sourceWallet` unless `fromSuspense` is `true`.

Without it the API returns `422 SOURCE_WALLET_REQUIRED` and credits nothing

* **New:** `sourceWallet`, the `SOURCE_WALLET_FORBIDDEN`, `SOURCE_WALLET_NOT_FOUND`, `SOURCE_WALLET_SAME_AS_USER`, `SOURCE_WALLET_BALANCE_SHORT` and `FROMSUSPENSE_AND_SOURCEWALLET_CONFLICT` errors, the `IDEMPOTENCY_KEY_MISMATCH` rule for a deposit retried with a different `amount` or `sourceWallet`, and `sourceWallet` in the response and in [`wallet.deposit_completed`](#walletdeposit_completed)
* **Changed:** the tenant wallet is debited `amount`, and these deposits do not send [`wallet.incoming_credit`](#walletincoming_credit)
* **New:** the `deposit` journal entry's `metadata` carries `sourceWallet`, in lowercase (see [Journal Conventions](#journal-conventions))
* Bumped public API doc version to 1.106
* 2026-11-14: v1.105 — Only uploaded documents count for KYC
  * **Changed:** a required [FICA document](#fica-identity-requirements) is present only when you have uploaded it with [KYC document upload](#kyc-document-upload).

A value sent in a `kycData` document field (`idProofFrontFile`, `idProofBackFile`, `passportProofFile`, `permitProofFile`, `proofOfResidenceFile`) on ingest or [Replace KYC Details](#replace-kyc-details) is still stored, but no longer counts as the document.

Before, any text in the field counted.

A user with such a value and no upload stays `not_ready` until you upload the document.

A user who is already approved is not re-checked; the rule applies from their next KYC replacement or document upload.

From then the user's KYC is pending, and money actions that need approved KYC are refused, until every required document has been uploaded and verified.

No request is rejected that was accepted before

* Bumped public API doc version to 1.105
* 2026-11-14: v1.104 — A new email resets the user's sign-in
  * **Changed:** [Update Account Details](#update-account-details): changing a user's email to a different address signs them out everywhere and removes their password, passkeys and linked social sign-in.

Two-factor authentication stays on, so they will still need their authenticator app.

A set-password link sent to the old address stops working.

The user signs in with an email code at the new address, and gets a set-password invite there if your tenant sends Spendl's set-password emails and the account is not `suspended`, `inactive` or `deleted`.

If emails are switched on for your tenant, Spendl also emails the previous address to say the sign-in email changed; that email doesn't show the new address.

If the account now belongs to someone else and they can't pass two-factor authentication, contact Spendl support to clear it.

The response and the `account.updated` webhook are unchanged

* Bumped public API doc version to 1.104
* 2026-11-13: v1.103 — Market data for one pair accepts only supported pairs
  * **Changed:** `GET /api/crypto/market-data/:pair` returns `400 UNSUPPORTED_PAIR` for a pair outside the supported list, as `GET /api/crypto/market-data` already did.

Before, it could return `200` with zero prices or with data for that pair.

[Market data](#market-data) lists the supported pairs, and the [crypto error table](#error-envelope) lists `UNSUPPORTED_PAIR`

* Bumped public API doc version to 1.103
* 2026-11-13: v1.102 — Health check body
  * **Changed:** [Endpoint Summary](#endpoint-summary): GET /health answers 200 {"ok": true} while the API is up and 503 {"ok": false} while it is starting or stopping; the body carries nothing else
  * Bumped public API doc version to 1.102
* 2026-11-13: v1.101 — Money actions are refused while replaced documents are incomplete
  * **Fixed:** when a registered user's KYC is restarted by an upload ([Replacing Documents After Registration](#replacing-documents-after-registration)) and a required document is still missing, money actions that need approved KYC are now refused from the next sync run, normally within a minute.

`kycStatus` was already `Pending` from the upload; before, an approved user could still use those actions until the remaining documents were uploaded.

For a user already in this position the actions are refused after the release, as the periodic recheck reaches them

* Bumped public API doc version to 1.101
* 2026-11-12: v1.100 — Debt offer decision deadline
  * **Changed:** [Offer Window](#offer-window) and [Debt Offer Decision](#debt-offer-decision): a decision for a claimed offer is accepted until the window closes or 24 hours after Spendl last sent you the loan-decision request, whichever is later.

After that the claim expires, normally within a minute, and a final decision returns `409 OFFER_EXPIRED`.

Before, a late decision had no deadline

* Bumped public API doc version to 1.100
* 2026-11-12: v1.99 — Add Beneficiary and Load Card errors
  * **Added:** `422 PAYACCSYS_SUPPLIER_FAILED` on [Add Beneficiary](#add-beneficiary) and [Load Card](#load-card) (`eft` channel).

The payment provider did not accept the details.

Nothing is added or debited.

This error is not new; it was missing from the guide

* **Changed:** [Add Beneficiary](#add-beneficiary) checks the user's KYC data first and returns `422 INCOMPLETE_KYC`, with `data.missingFields`, when `lastName`, `idNumber` or `identityType` is missing for an `Individual` beneficiary.

Before, the same add failed with `422 PAYACCSYS_SUPPLIER_FAILED`.

A missing `identityType` is now read from a valid South African ID number, so those adds succeed

* Bumped public API doc version to 1.99
* 2026-11-11: v1.98 — Temporary errors
  * **Added:** [Temporary Errors](#temporary-errors): `404 SERVICE_NOT_AVAILABLE` and `404 SERVICE_NOT_FOUND` are temporary.

Retry after a short wait, with the same idempotency key on a money route

* **Changed:** these errors now have a plain `message` and no `data`.

Before, both named internal services.

`code` and `type` are unchanged

* **Changed:** [Error Outcomes](#error-outcomes) lists `REQUEST_REJECTED` and `REQUEST_SKIPPED` under "May have moved", with `REQUEST_TIMEOUT`
* Bumped public API doc version to 1.98
* 2026-11-10: v1.97 — Debt ingest identifier checks; duplicate guid detail
  * **Changed:** [Ingest Debt Obligation](#ingest-debt-obligation) returns `422 VALIDATION_ERROR` when `guid` or `loan_ref_no` is an object or array, or `client_no` is not a string.

`data.invalidFields` names the fields.

Before, a numeric `client_no` returned a 500

* **Changed:** a `409 DUPLICATE_GUID` includes `data.processingStatus` only when the existing obligation is yours.

For any other match it returns `data.guid` only

* Bumped public API doc version to 1.97
* 2026-11-09: v1.96 — Debt obligations without bank fields; loan repayments paid into your tenant wallet
  * **New:** [Ingest Debt Obligation](#ingest-debt-obligation) accepts an obligation without the three bank fields when Spendl has set up your tenant to receive loan repayments into your tenant wallet.

Other tenants are unchanged.

Once Spendl sets this up, repayments on obligations you send from then on are paid into your tenant wallet, whether or not you send bank fields

* **New:** journal entry type `debt_installment_settlement`: loan repayments collected from your users, paid into one of your [tenant wallets](#create-tenant-wallet).

It appears only in a tenant wallet's history, and you can filter journal entries on it

* **New:** [`wallet.incoming_credit`](#walletincoming_credit) is sent for a `debt_installment_settlement`, with the tenant wallet's `userId` and `email`, as it is for a `tenant_fee_payout`
* **Changed:** a due `debt_installment` is now collected automatically when money reaches the user's main balance, such as a deposit, a Pay@ payment, a transfer from another user (including a disbursement from your tenant wallet) or a refund posted as its own entry, for example a Zapper refund.

A `reversal`, such as a refunded send-to-bank payment, and a move between the user's own accounts do not trigger it.

Before, only a deposit triggered it

* Bumped public API doc version to 1.96
* 2026-11-09: v1.95 — ID card front only
  * **New:** Spendl can set up your tenant so that an `ID_CARD` user needs only `idProofFront`.

`idProofBack` is then optional for [KYC completion](#kyc-completion-requirements) and [card readiness](#card-readiness).

Every other requirement is unchanged, and so is every tenant that is not set up for it.

See [FICA Identity Requirements](#fica-identity-requirements)

* Bumped public API doc version to 1.95
* 2026-11-07: v1.93 — Journal entries name their source entry; voucher payout fee shares on `4010`
  * **New:** a journal entry's `metadata` can carry `sourceJournalEntryId`, the ID of the entry in your ledger that it was booked for.

For example, a `voucher_payout_settlement` carries the ID of the `voucher_payout` whose fee it records, so you can match the fee to the payout.

Entries without it are unchanged.

See [Journal Conventions](#journal-conventions)

* **Changed:** where Spendl has agreed a share of its voucher payout fee with you, the `voucher_payout_settlement` credits your share to `4010` and the rest to `4000`.

`providerFeeAmount` stays the whole fee, so read the split from the entry's lines.

A share booked after the fee arrives as a separate `fee_reclassification` entry (debit `4000`, credit `4010`) whose `sourceJournalEntryId` is the `voucher_payout_settlement`

* Bumped public API doc version to 1.93
* 2026-11-06: v1.92 — Retry a failed remittance; recipient phone numbers checked before the debit
  * **New:** [Retry Failed Transfer](#retry-failed-transfer), `POST /api/remittance/transactions/:transactionId/retry-edit`: retry a `failed` transfer with corrected recipient details, without a new debit.

The failure's network code decides which fields can change; an `ER111` or `ER200` failure can also be retried once unchanged.

It needs remittances enabled and an idempotency key

* **Changed:** [`remittance.failed`](#remittancefailed) is sent for each failed attempt, so a retry that fails again sends it again.

[`remittance.submitted`](#remittancesubmitted) is sent again when a retry is accepted.

Each attempt's events get their own idempotency key ([Idempotency Keys](#idempotency-keys)), and so does [`remittance.cancelled`](#remittancecancelled) when a retry is cancelled again

* **New:** every remittance event except `remittance.refunded` carries `attempt` (`1` for the first send, higher for each retry) and `thirdPartyTransId`, the attempt's reference (until now only on `remittance.cashPickupReady`).

Webhooks can arrive out of order: see [Remittance Lifecycle Events](#remittance-lifecycle-events) for how to order them.

`remittance.failed` also carries `recipientPartnerCode`, the `partnerCode` of the send

* **New:** the transaction in send, retry, list, get and status responses carries the same `thirdPartyTransId` and `attempt`, for its current attempt
* **Clarified:** a `transactionId` that is not a valid transaction ID returns `400 INVALID_ID` on [Get Transaction](#get-transaction), [Check Transaction Status](#check-transaction-status) and [Retry Failed Transfer](#retry-failed-transfer)
* **Changed:** [Validate Recipient](#validate-recipient) answers a wallet or cash-pickup `msisdn` that is not 7 to 15 digits in international format (a local number starting with `0` is not), or a wallet number without the destination's dialling code, with `422 INVALID_RECIPIENT_MSISDN`.

A malformed number returned `503 VALIDATION_SERVICE_UNAVAILABLE` before.

[Initiate Send](#initiate-send) refuses such a `recipientMsisdn` with the same error, before the wallet is debited

* **Clarified:** `statusCode` on `remittance.failed`, and `networkStatusCode`, are `null` when no network code is available
* Bumped public API doc version to 1.92
* 2026-11-06: v1.91 — Guide cleanup; three responses return fewer fields
  * **Changed:** [`GET /api/payat/transactions/:id`](#get-apipayattransactionsid) returns exactly the fields of a [`GET /api/payat/transactions`](#get-apipayattransactions) item.

Fields that were never documented are no longer included

* **Changed:** the user in a [`POST /api/ingest`](#ingest-users) response no longer includes `userDetails.password` or `userDetails.emailConfirmation`.

Both were always `null`

* **Changed:** the user in a [`POST /api/ingest/sumsub`](#create-user-from-sumsub-share-token) response now has the same fields as in a `POST /api/ingest` response: it no longer includes `userDetails.password`, `userDetails.emailConfirmation` or `debtOffer`
* **Corrected:** the fee you set on a deposit, a transfer or a Zapper deposit is booked to `4010`, not `4000`, in the OpenAPI spec, as this guide already said
* **Corrected:** [Add Beneficiary](#add-beneficiary) does not replay a retry: a retry for the same account returns `409 DUPLICATE_ENTRY`
* **Corrected:** after a `502 TENANT_DB_WRITE_ERROR`, `BACKEND_FORWARD_ERROR` or `CALLBACK_ENQUEUE_ERROR` on debt ingest, the obligation is already recorded.

Do not resend it; check its status instead, and contact support if it is still `failed` after an hour

* **Corrected:** a same-key retry of a Pay@ or Zapper deposit returns the original result only once the first request has finished; until then, or if it failed, it returns a `409`
* **Corrected:** [KYC document upload](#kyc-document-upload): a PDF over 4 MB returns `500 PDF_CONVERSION_ERROR`.

Keep PDFs to 4 MB or less

* **Corrected:** a [Zapper deposit](#post-apiwalletdepositzapper) that is not set up returns `500 INTERNAL_ERROR` (this guide said `ZAPPER_NOT_CONFIGURED`)
* **Corrected:** webhook delivery is retried only after a network error or a `5xx` response.

A `4xx`, including `429`, is not retried

* **Corrected:** a remittance in `failed` is not final: Spendl retries it, and a retry returns it to `submitted`.

The wallet is not refunded automatically

* **Documented:** `400 INVALID_AMOUNT` on disbursements, the Zapper deposit `409` responses for a reused idempotency key (`IDEMPOTENCY_KEY_MISMATCH`, `ZAPPER_INITIATION_PENDING`, `ZAPPER_INITIATION_PREVIOUSLY_FAILED`), and the Pay@ deposit ones (`IDEMPOTENCY_KEY_MISMATCH`, `PAYAT_INITIATION_PENDING`, `PAYAT_INITIATION_PREVIOUSLY_FAILED`)
* **Corrected:** the [`wallet.beneficiary_added`](#walletbeneficiary_added) and [`wallet.beneficiary_removed`](#walletbeneficiary_removed) examples.

`result` is the Add (without `success`) or Remove Beneficiary response body.

The beneficiary's ID is `result._id` on an add and `beneficiaryId` on a removal, with no `bene_` prefix

* **Documented:** [Send to Bank](#send-to-bank-eft) speeds and fees, with the `fees`, `payshapBanks`, `rtcBanks` and `payshapThresholdZar` fields of [`GET /api/wallet/participating-banks`](#reference-data); its `422 BENEFICIARY_NOT_REGISTERED` and `422 BANK_NOT_ELIGIBLE_FOR_IMMEDIATE` errors; [Remove Beneficiary](#remove-beneficiary) as a soft delete, with `404 NOT_FOUND`; and how to link a `reversal` in [Transaction History](#transaction-history) to the entry it marks `reversed`
* Wording cleanup across the guide, the OpenAPI spec and the Postman collections.

No other API behaviour changed

* Bumped public API doc version to 1.91
* 2026-11-06: v1.90 — Update Account Details accepts only its documented fields
  * **Changed:** [`PATCH /api/ingest/:id/details`](#update-account-details) returns `422 PROTECTED_FIELDS` for any field other than `userDetails.email`, `userDetails.status`, `clientNo` and `preferences`.

An undocumented field was accepted before

* Bumped public API doc version to 1.90
* 2026-11-06: v1.89 — Fill missing KYC details without restarting KYC
  * **New:** [`PATCH /api/ingest/:id/kyc/fill`](#fill-missing-kyc-details) adds `phone`, `city` or `identityIssueCountry` to an approved user's KYC data where it is empty.

KYC is not restarted and no webhook is sent.

`dryRun: true` checks a request without changing anything

* **Changed:** [Sender Profile](#sender-profile) points to it for these fields, and gives their formats
* **Unchanged:** [Replace KYC Details](#replace-kyc-details) still replaces all KYC data and restarts KYC.

Include the filled fields in any later replacement

* Bumped public API doc version to 1.89
* 2026-11-06: v1.88 — Crypto deposit addresses need approved KYC
  * **Changed:** [`GET /api/crypto/deposit-addresses`](#deposit-addresses) returns `403 KYC_REQUIRED` unless the user's KYC is approved, including for a user who already has addresses.

Request addresses after the user is approved

* **Changed:** the `KYC_REQUIRED` message on deposit addresses, withdrawals and place-order now reads "Approved KYC is required for this crypto action".

The code and status are unchanged

* **Unchanged:** balances, deposits, withdrawal history and the other crypto reads.

Withdrawals and place-order already needed approved KYC

* Bumped public API doc version to 1.88
* 2026-11-03: v1.87 — Guru no longer needs a proof of residence
  * **Changed:** a Guru user no longer needs `proofRes` (proof of residence) for KYC or a card.

A Guru user waiting only for `proofRes` continues automatically.

A Guru passport holder still needs `proofPermit` (work permit).

See [FICA Identity Requirements](#fica-identity-requirements) and [Card readiness](#card-readiness)

* **Changed:** `POR_*` [review reason codes](#review-reason-codes) are no longer sent
* **Unchanged:** you can still upload `proofRes`.

Guru still needs the residential address fields `addressLine1`, `suburb`, `city`, `province` and `postalCode`, as every card tier does

* Bumped public API doc version to 1.87
* 2026-11-02: v1.86 — Pay@ cash withdrawal is not available
  * **Changed:** [`POST /api/wallet/withdrawal/payat`](#post-apiwalletwithdrawalpayat) returns `403 PAYAT_PAYOUT_NOT_ENABLED`.

No PIN is issued and nothing moves.

A PIN issued before this change cannot be used

* **Unchanged:** [`GET /api/payat/account/:userId`](#get-apipayataccountuserid) still returns the `payout` block, which cannot be used yet.

[Withdrawal status](#get-apipayatwithdrawalstatuswithdrawalrequestid) and [list](#get-apipayatwithdrawallistuserid) still answer for earlier PINs.

Pay@ deposits are not affected

* **Corrected:** withdrawal status does not return `expired`.

A PIN's status is available until shortly after `expiresAt`, then returns `404 PAYOUT_PIN_NOT_FOUND`

* **Corrected:** the OpenAPI description of [`POST /api/wallet/deposit/payat`](#post-apiwalletdepositpayat) now says the fee you set goes to `4010` and the provider fee to `4000`, as this guide does.

Other Pay@ text was clarified; behaviour is unchanged

* Bumped public API doc version to 1.86
* 2026-11-02: v1.85 — Remittance sender profile, KYC replacement, name check and history types documented
  * No API behaviour changed; the guide now describes existing behaviour
  * New [Sender Profile](#sender-profile): the KYC fields a remittance send needs and how `422 INCOMPLETE_KYC` names them
  * [Replace KYC Details](#replace-kyc-details): every accepted change restarts KYC, even for an approved user (a PATCH answered with `unchanged: true` changes nothing).

Omitted fields are removed.

Money actions that need approved KYC are refused until the user is approved again

* [Initiate Send](#initiate-send): `termsAcceptedAt` must be the boolean `true`
* [Validate Recipient](#validate-recipient): when `nameCheck` is present, and the `502 UPSTREAM_NETWORK_ERROR` timeout
* New [History Types](#history-types) for Transaction History
* OpenAPI spec aligned with enforced validation (`termsAcceptedAt` required, field lengths, `nameCheck` not nullable, history `status` enum).

Regenerate any generated client

* Wording and example cleanup across the guide; no API behaviour changed.

The OpenAPI `S3Keys` component is now named `KycDocumentUploads` (the `s3Keys` field is unchanged), and `complianceDetails` is no longer listed as an ingest or account-details input.

If you verify webhook signatures and have an `hmacSecret`, accept only `hmac-sha256` (see the updated [Signature Verification](#signature-verification) sample)

* Bumped public API doc version to 1.85
* 2026-10-31: v1.84 — Remittance exchange errors: `422` when refused, `503` before any debit
  * **Effective from** the release that enables this in each environment.

Until then, sends answer as they did before

* **Changed:** [send](#initiate-send) returns `FX_PROVIDER_REJECTED` only as `422`, with `data.reversed: true`: the send was debited, then refunded, and the key is spent; use a new key.

Before, it carried the exchange provider's own `4xx` status

* **Changed:** when the exchange provider refuses the exchange request itself (as invalid, not authorised or forbidden), the send is refunded and returns `422 FX_PROVIDER_REJECTED` with `data.reversed: true`.

It returned `422 CURRENC_TRADE_AMBIGUOUS` before, and the debit stayed held until support confirmed the outcome.

`CURRENC_TRADE_AMBIGUOUS` is unchanged: any exchange answer that is not a definite refusal still means the outcome could not be confirmed, so keep the key and check [List Transactions](#list-transactions) or contact support

* **Changed:** when a send's exchange rate expires during the send before the exchange is made, the send is refunded and returns `409 QUOTE_EXPIRED` with `data.reversed: true`: get a new quote and use a new key.

Before, it could return `FX_PROVIDER_REJECTED` or `TRADE_LIMIT_EXCEEDED`, also refunded.

A send made with its `quoteId` may first be re-priced once at the current rate (a quote is indicative until the send accepts it).

If that re-price gets no rate, the send returns `503 FX_PROVIDER_UNAVAILABLE` when it comes before the debit (nothing moved), or `409 QUOTE_EXPIRED` with `data.reversed: true` when it comes after; a re-priced exchange that is refused returns `FX_PROVIDER_REJECTED` or `TRADE_LIMIT_EXCEEDED`, refunded, as for any send.

When it cannot be confirmed whether the exchange was made before the rate expired, the send returns `422 CURRENC_TRADE_AMBIGUOUS` and the debit is held: keep the key

* **New:** send can return `503 FX_PROVIDER_UNAVAILABLE` when no live exchange rate could be obtained.

It is returned before the wallet is debited, so the request moved nothing: retry later with the same key, with a new quote if the old one expired.

Before, a send that could not price its exchange was debited, then refunded, and answered `FX_PROVIDER_REJECTED`, `TRADE_LIMIT_EXCEEDED` or a `5xx` `INTERNAL_ERROR`

* **Documented:** [Get Quote](#get-quote) can return `503 FX_PROVIDER_UNAVAILABLE` when no live exchange rate could be obtained; you can retry.

It already could

* **Documented:** [send](#initiate-send) can return `422 INVALID_QUOTE_TOKEN` when the quote could not be verified as the send was processed, for example because it expired on the way.

It is returned before the wallet is debited.

If an earlier attempt with the same key moved money, a retry gets that attempt's outcome instead, so this error means nothing moved: get a new quote and send it with the same key.

It already could

* **Documented:** a retry with the same key (with a new quote, or none) of a send that returned `422 CURRENC_TRADE_AMBIGUOUS` returns it again, with `data.reversed: false`, until support resolves it; it already did.

If the exchange went through, such a retry then answers like any other retry of that send: its transaction with `duplicate: true` while the send is in flight or delivered, or `422 PRIOR_ATTEMPT_UNRESOLVED` if its payout later fails, is cancelled or is refunded.

If the debit is refunded instead, the error carries `data.reversed: true`, and only then is the key spent.

Until then, keep the key

* **Clarified:** a [quote](#get-quote) lasts at most 50 seconds by default (Spendl may raise this to 59) and can be much shorter.

Each quote's own `expiresIn` is authoritative.

The guide no longer says the longest quote is about 56 seconds

* **Clarified:** the OpenAPI spec for [send](#initiate-send) now lists every status in the send error table.

Its `422` names the errors that must keep the idempotency key (`CURRENC_TRADE_AMBIGUOUS`, `PRIOR_ATTEMPT_UNRESOLVED`), those that spend it (`TRADE_LIMIT_EXCEEDED`, `FX_PROVIDER_REJECTED`, `IDEMPOTENCY_KEY_ALREADY_USED`, `AMOUNT_TOO_SMALL`) and those that move nothing, `INVALID_QUOTE_TOKEN` among them.

It also lists `404 USER_NOT_FOUND`, `429 SEND_IN_PROGRESS` and any other `5xx`, after which you retry with the same key.

A `QUOTE_EXPIRED` without `data.reversed` keeps the key.

The spec change adds no behaviour of its own; the send changes are the bullets above.

If you generate a client from the spec, regenerate it

* Bumped public API doc version to 1.84
* 2026-10-30: v1.83 — Journal amount filters read the entry's amount; summary totals are gross
  * **Changed:** on [List Journal Entries](#list-journal-entries), `minAmount` and `maxAmount` without `accountCode` filter on the entry's amount, the sum of its debit lines.

Before, they compared single lines, and `maxAmount` without `accountCode` did not narrow the results.

With `accountCode` they still filter on a line on that account, debit or credit, with both limits on that same line.

The 366-day period rule is unchanged

* **Docs:** [Journal Summary](#journal-summary) totals are gross: a reversed entry still counts in full under its own type, and its reversal counts separately, in `reversals` and as type `reversal` in `byDay`, on the day it was posted.

Any net figures Spendl adds will be new fields; the existing fields keep their meaning

* **New:** `totals.ownAccountTransfers` and `byDay[].byType.own_account_transfer` count moves between a user's main balance and their sub-accounts.

They are `transfer` entries, but they are counted only in `ownAccountTransfers`, not in `transfers`.

`own_account_transfer` is a summary bucket only and cannot be used as a `type` filter

* **Changed:** [Deposit Funds](#deposit-funds) with `fromSuspense: true` (`admin` scope) is refused with `422 SUSPENSE_BALANCE_SHORT` when the suspense account holds less than `amount`.

Nothing is credited

* Bumped public API doc version to 1.83
* 2026-10-30: v1.82 — A passport whose document could not be checked is held for review
  * **Fixed:** when the identity document check could not run on a foreign passport, KYC was rejected with "Please try again in a few minutes", and a retry met the same error.

It is now held for review: `kyc.review_required` with `DOCUMENT_CHECK_UNAVAILABLE`, as for other identity documents.

Nothing to change on your side

* Bumped public API doc version to 1.82
* 2026-10-30: v1.81 — Corrections: deposit reference, Pay@ prefix, Pay@ redirect base
  * **Corrected:** [Create Tenant Wallet](#create-tenant-wallet) and the deposit reference examples: show the reference exactly as returned (`ACM00000001`).

Spendl matches it with or without the hyphen and in any letter case, but not with spaces inside it.

Examples now use 8 digits

* **Corrected:** [Pay@ Integration](#pay-integration): deposits and withdrawals both use the issuer prefix `13044` in staging and production (this guide said `13013` for deposits).

Don't hard-code it; show `accountNumber` as returned

* **Corrected:** until Spendl enables Pay@ redirects for your tenant, Pay@ deposits fail with a `422`, for example `PAYAT_DIGIAPI_UNAUTHORIZED_HOST` (this guide said they proceed without redirect URLs).

Spendl enables them during onboarding.

Added that error to the deposit's common errors

* Bumped public API doc version to 1.81
* 2026-10-29: v1.80 — Transaction History withholds Spendl-only metadata
  * **Changed:** [Transaction History](#transaction-history) `metadata` no longer returns fields that only Spendl uses.

Every documented field, including the fee fields and `tenantFeePayout.statement`, is unchanged, and so are each item's `type`, `description` and `entries`

* Bumped public API doc version to 1.80
* 2026-10-28: v1.79 — Tenant fee payouts
  * **New:** journal entry type `tenant_fee_payout`: Spendl credits your accrued tenant fee share to one of your [tenant wallets](#create-tenant-wallet), debiting `4010` by its whole balance and crediting the tenant wallet (`2000-<tenantWalletUserId>`).

The Journal API returns it with `initiatedBy: "admin"` and `metadata.amount` (the amount paid), and it is filterable with `type`.

See [Journal Conventions](#journal-conventions)

* **New:** in the tenant wallet's [Transaction History](#transaction-history), the payout's description is `Tenant fee payout` and its `metadata.tenantFeePayout.statement` breaks the amount down by product since the previous payout.

Transaction History lists the statement's fields

* **Changed:** `4010` (Tenant fee revenue) also holds your share of the remittance service fee, where Spendl has agreed one with you; `4100` holds the rest of that fee.

See [Journal Conventions](#journal-conventions)

* **New:** [`wallet.incoming_credit`](#walletincoming_credit) is sent for a tenant fee payout, with the tenant wallet's `userId` and `email`.

Other money arriving in a tenant wallet still does not send it

* Until tenant fee payouts are live in an environment, no `tenant_fee_payout` entries appear there
* Bumped public API doc version to 1.79
* 2026-10-28: v1.78 — Instant card loads
  * **New:** [Load Card](#load-card) can credit the card instantly (`channel: "fund_card"`), switched on per environment by Spendl; until then nothing changes (`channel: "eft"`).

The response now carries `channel` and `cardCredited` (`true` when the card has been credited), and so does the [`wallet.load_card_completed`](#walletload_card_completed) webhook's `result`.

On `fund_card` the fee is a flat amount whatever `withdrawalOption` is, `paymentMethod` is `FUND_CARD` and `payaccsysRef` is `CL<journalEntryId>`

* **New:** `422 CARD_NOT_FUNDABLE` on the `fund_card` channel: the card is closed or expired, and the wallet was refunded (`data.reversed: true`)
* **New:** the `data.result` of a load-card `409 DUPLICATE_IDEMPOTENCY_KEY` carries `channel` and `cardCredited` too.

A settled `fund_card` load reads `channel: "fund_card"`, `cardCredited: true`; an `eft` load, or a `fund_card` load that never posted, reads `cardCredited: false`; a failed or held `fund_card` retry gets the first attempt's error (its `502`, or `422 CARD_NOT_FUNDABLE` for a closed or expired card).

A `409` whose `data.result` is present but has neither field was recorded before these fields existed; treat it as `eft`.

A `409` with no `data.result` (the key was first used in another request) says nothing about this load: check [Transaction History](#transaction-history).

See [Idempotency](#idempotency)

* **New:** `cardLoad` on `GET /api/wallet/participating-banks`: the channel, the flat load fee and the card's receive fee (see [Reference Data](#reference-data))
* **Unchanged:** `502 PAYACCSYS_LOAD_AMBIGUOUS` (`data.reversed: false`) still means the outcome is unknown and the wallet is still debited; never retry with a new key.

Its message is generic and says not to retry: that means not with a new key, and a same-key retry is safe.

On `fund_card` Spendl holds the load and settles it or refunds the wallet, usually within 30 minutes.

It stays held longer while the card's records can't be read, or when the card provider's answer was lost (for example, a timeout) and the card shows no credit: Spendl then refunds it only after confirming the outcome with the card provider.

No webhook is sent for that later outcome: retry with the same key (`409 DUPLICATE_IDEMPOTENCY_KEY` with `data.result`: settled; `502 PAYACCSYS_LOAD_FAILED` with `data.reversed: true`: refunded; `502 PAYACCSYS_LOAD_AMBIGUOUS` again: still held) or check [Transaction History](#transaction-history).

A retry whose user or card check fails (for example `404 CARD_NOT_FOUND` once the card is unlinked) says nothing about the load: check Transaction History or contact support.

See [held loads](#held-fund_card-loads)

* **Changed:** on `fund_card`, `502 PAYACCSYS_LOAD_FAILED` means the wallet was refunded (`data.reversed: true`).

As the first answer, the request never reached the card provider; on a same-key retry it can also mean Spendl refunded a held load later

* **Changed:** a wallet request whose answer breaks off partway, or runs out of time while it arrives, now returns `502 UPSTREAM_NETWORK_ERROR` (the outcome is unknown; retry with the same key), as a request that fails to connect does, instead of an unlisted `500`
* **Timeouts:** a `fund_card` load can take up to about 50 seconds.

Allow at least 65 seconds in your HTTP client for `POST /api/wallet/load-card`

* **Docs:** Load Card's errors now list `500 INTERNAL_ERROR`, `502 UPSTREAM_NETWORK_ERROR` and `504 REQUEST_TIMEOUT` (the outcome is unknown; retry with the same key), and [Error Outcomes](#error-outcomes) links to Load Card, where `422 CARD_NOT_FUNDABLE` spends the key.

`409 CARD_ACCOUNT_MISSING` is `eft` only.

Every wallet route's `409 DUPLICATE_IDEMPOTENCY_KEY` now reads the same: with `data.result`, act on its `status` (`posted` processed; `pending` retry later with the same key; `reversed` later reversed, so check before trying again; `failed` moved nothing); without it, check the transaction history.

[Wallet Error Codes](#wallet-error-codes) lists `CARD_NOT_FUNDABLE`.

[Idempotency](#idempotency): a `409` whose `data.result.status` is `pending` means the first request is still running; retry later with the same key.

The errors of Load Card, [Deposit Funds](#deposit-funds), [Transfer Funds](#transfer-funds), [Send to Bank](#send-to-bank-eft) and [Repay Debt](#repay-debt) now end with a catch-all row: any other `5xx`, or no response, means the outcome is unknown; retry with the same key, which never moves money twice.

* `cardLoad` is cached for up to 5 minutes by default, like the rest of the participating-banks response, so it can lag a channel switch; the load-card response's `channel` is the one that was used
  * **Docs:** a same-key `load-card` or `send-to-bank` retry sent while the first request is still waiting for the payment provider returns `502 PAYACCSYS_LOAD_AMBIGUOUS` or `502 PAYACCSYS_EFT_AMBIGUOUS` (`data.reversed: false`), not a `409` with `status: "pending"`.

This is unchanged behaviour, now documented: retry later with the same key, which returns the first request's outcome once it has finished (a held `fund_card` load keeps returning `502 PAYACCSYS_LOAD_AMBIGUOUS` until Spendl settles or refunds it).

See [Load Card](#load-card) and [Idempotency](#idempotency)

* Bumped public API doc version to 1.78
* 2026-10-28: v1.77 — Voucher payouts: `needs_review` status
  * **New:** [Get Payout Status](#get-payout-status), and a retry of `POST /api/vouchers/perform` with the same idempotency key, can return `status: "needs_review"` with `success: false`.

Spendl could not confirm the payout's outcome automatically, so the payout is waiting for manual review.

It is not final: it can still become `completed`, or `failed` with the debit returned to the wallet.

Until then the debit stays in place.

Do not submit a new payout for it; tell the user that the payout is being reviewed and that they can contact support.

No webhook is sent for this status

* Bumped public API doc version to 1.77
* 2026-10-26: v1.76 — Fee accounts: your fee on `4010`, Spendl's tariff on `4000`
  * **Effective from** the release that enables this in each environment.

Until then, `4000` still receives the fee you set and no `fee_reclassification` or `provider_fee` entries appear

* **Changed:** the fee you set with `feeAmount` is now booked on the new system account `4010` (Tenant fee revenue) instead of `4000`.

`4000` (Transaction fees) now holds only Spendl's own provider tariff (`providerFeeAmount` on Pay@ and Zapper deposits, the pass-through fee on card loads and send-to-bank).

A deposit or transfer with a fee therefore shows a `4010` line where it showed a `4000` line; a Pay@ or Zapper deposit with both fees shows one `4010` and one `4000` line.

See [Journal Conventions](#journal-conventions)

* **New:** journal entry types `fee_reclassification` (re-tags a fee booked on `4000` before this change; moves no money) and `provider_fee` (books payment processing costs on `5000`; no wallet lines).

Both are filterable with `type`.

Entries of either type recorded before this change were `other`

* **New:** `accountCode=4010` on [List Journal Entries](#list-journal-entries), and `4010` in the summary's `accountBalances`
* **Changed:** in [Journal Summary](#journal-summary), `feeByDay[].expenseCents` counts payment processing costs (`5000`) only: it no longer counts remittance settlement principal (`5100`).

`revenueCents` counts `4000`, `4010` and `4100`, so it still includes the fee you set

* **Changed:** [Transaction History](#transaction-history) reports Spendl's tariff and payment processing costs under `4000` and `5000`, as the Journal API does
* **Unchanged:** every line still carries a four-digit system account code or your user's `2000-<userId>`.

An entry can carry more than one `4000` or `5000` line; sum by account code.

`metadata` carries the same fee fields as before

* Bumped public API doc version to 1.76
* 2026-10-26: v1.75 — Remittance status codes and name-check message
  * [Check Transaction Status](#check-transaction-status) now returns in `networkStatusCode` only the payment network's own status code, and `null` otherwise.

Before, it could carry a Spendl status code.

`statusCode` on [`remittance.failed`](#remittancefailed) and [`remittance.cancelled`](#remittancecancelled) follows the same rule.

Keep using `status` for lifecycle decisions

* A name check that could not be completed now returns `responseMsg: "Name check could not be completed"`, with `responseCode: "ERROR"` as before
* Bumped public API doc version to 1.75
* 2026-10-26: v1.74 — Remittance webhooks without an endpoint leave no audit failure
  * No audit failure is recorded any more when you have no endpoint for a remittance event: the API silently skips it, as it does `wallet.incoming_credit`.

Nothing you receive changes

* Bumped public API doc version to 1.74
* 2026-10-23: v1.73 — Cash pickup collected webhook
  * **New:** [`remittance.cashPickupCollected`](#remittancecashpickupcollected) is sent once when the cash of a cash pickup that became `completed` when its voucher was issued (`MR101`) is collected.

It carries the transfer's `id`, `recipientName`, `recipientSurname`, `sendAmountZar`, `toCountry`, `receiveAmount` and `receiveCurrency`, never the voucher code.

Previously no webhook was sent for a later collection: [Check Transaction Status](#check-transaction-status) showed it in `voucherStatus`, and still does.

A voucher cancelled after its transfer completed still sends no webhook

* Its endpoint key is `remittance.cashpickupcollected`, in lowercase, and an `RPC` endpoint receives that name as `method`.

[Endpoint key routing](#callback-event-model) now states that every camelCase event routes by its lowercase name, as `remittance.cashPickupReady` always has (`remittance.cashpickupready`)

* **New:** every remittance webhook (`remittance.submitted`, `remittance.completed`, `remittance.failed`, `remittance.cancelled`, `remittance.cashPickupReady`, `remittance.cashPickupCollected` and `remittance.refunded`) carries `recipientSurname` next to `recipientName`: the recipient's surname as the sender entered it on the send, or `null` when the sender gave no surname, or only spaces.

A webhook for an event Spendl emitted before it added this field, such as a resend of an older delivery, has no `recipientSurname`; treat a missing field as `null`.

The examples of these events now show every field each one carries: `remittance.submitted` and `remittance.completed` also show `paymentType`, `receiveAmount` and `receiveCurrency`, `remittance.cancelled` and `remittance.refunded` also show `toCountry`, and `remittance.refunded` shows both name fields, all of which they already carry

* Bumped public API doc version to 1.73
* 2026-10-23: v1.72 — Payday loan decisions
  * New endpoint `POST /api/debt/decision`, also served at `POST /api/decision-callback`, records your final approve or decline for a debt offer.

Send the `uuid` of the loan-decision request Spendl sent you for the offer; the eligibility offer `uuid` is also accepted

* An approval must carry `capital`, `initiation_fee`, `repayment_total`, `due_date` and an assessment id, and `repayment_total` must equal `capital` plus `initiation_fee`.

It needs no `loan_id`: the loan reference is issued when the customer accepts the loan

* Amounts carry at most two decimals and totals are compared in cents, so an approval with cents (`2000.10` + `150.20` = `2150.30`) is accepted.

`capital` must be greater than zero, at most R8,000 and inside the offer's `capital_range`; `initiation_fee` at most R1,050; affordability figures at most R10,000,000.

`due_date` must be a valid ISO 8601 date naming a day that exists (`2026-02-30` is refused).

`term` is a whole number from 1 to 6, and `1` for a `payday_loan`.

Text fields are at most 200 characters

* A final decision needs an offer the customer claimed inside its 48-hour window with credit-check consent.

An approval that arrives after the window, for a claim made inside it, is accepted, and the customer has 24 hours from the approval to sign and accept

* An exact repeat of a stored decision returns `acknowledged`, also after the window has closed.

A stored `pending` is replaced by the `approved` or `declined` that follows it; a `pending` that arrives after an answer, or for an offer that was not claimed in time, is acknowledged and not stored; a different final decision returns `409 DUPLICATE_DECISION`

* Every decision callback, accepted or refused, is written to the debt audit log with its decision fields, never `affordability_summary`
* New errors: `409 DUPLICATE_DECISION`, `409 OFFER_NOT_CLAIMED`, `409 OFFER_EXPIRED`, `409 OFFER_CONSENT_MISSING`, `422 OFFER_NOT_FOUND`, `422 PRODUCT_TYPE_MISMATCH`, `422 CAPITAL_OUTSIDE_OFFER_RANGE`, `503 DECISION_WRITE_CONTENTION` (retryable)
* Documented the 48-hour offer window (see Offer Window).

`POST /api/debt/eligibility` is unchanged: `capital_range.max` stays optional

* Bumped public API doc version to 1.72
* 2026-10-23: v1.71 — Cash pickup vouchers, quote expiry and undelivered events
  * **Changed:** a cash-pickup transfer becomes `completed` (`networkStatusCode` `MR101`) when its voucher is issued, not when the cash is collected.

`voucherCode` is returned by [Check Transaction Status](#check-transaction-status) and, new in this release, by [Get Transaction](#get-transaction); it can be `null` for a short time after `completed`, so poll until it is set, and contact Spendl support if it is still `null` after 30 minutes.

It is withheld once the voucher is collected or cancelled.

For a wallet or bank transfer, Check Transaction Status now returns `null`, where it carried the network's own reference.

A voucher cancelled after completion leaves the transfer `completed` with `voucherStatus: cancelled`.

Both responses carry `Cache-Control: no-store`.

[List Transactions](#list-transactions) and the send response never contain it.

The recipient must show the voucher code and a government-issued ID in the name on the transfer to collect the cash, so send the recipient's name exactly as it appears on their ID; only the recipient can collect.

See [Cash Pickup Vouchers](#cash-pickup-vouchers)

* **New:** `voucherStatus` (`issued`, `collected`, `cancelled` or `null`) and `voucherCollected` on the status, transaction, list and send responses.

They can appear on any transaction; for a wallet or bank transfer, or one sent before this release, they are `null` and `false` or absent.

No webhook is sent when a completed transfer's voucher is later collected or cancelled: read `voucherStatus`

* **New:** `voucherPartner` on [Check Transaction Status](#check-transaction-status): the cash-pickup partner where the recipient collects the cash, or `null` for a wallet or bank transfer or when no partner is recorded.

[Get Transaction](#get-transaction) already returns it

* **Changed:** [`remittance.cashPickupReady`](#remittancecashpickupready) is sent once, when the voucher is issued, usually just after `remittance.completed`.

It carries `voucherCode` and `cashPickupPartner`, and now also `sendAmountZar`, `receiveAmount`, `receiveCurrency`, `paymentType` and `thirdPartyTransId` (Spendl's reference for this payout attempt; quote it to Spendl support).

If Spendl retries a failed cash pickup, a new voucher is issued with a new code and a new idempotency key, so always show the latest code.

`remittance.completed` does not carry the code.

For a cash pickup it is sent once: when the voucher is issued (`MR101`), or, if the cash is collected before the voucher is reported issued (for example a transfer that reached `cash_pickup_ready` first), when the cash is collected; only that collected event carries `voucherCollected: true`

* **Changed:** customers can no longer cancel a remittance.

[Cancel Transaction](#cancel-transaction) always returns `422 NOT_CANCELLABLE`, including for a cash-pickup voucher, and nothing changes.

To stop a transfer, contact Spendl support.

The `remittance.refunded` example `reason` is now `Admin manual refund`

* **Fixed:** a quote is valid for 50 seconds by default, not about 30; use the quote's `expiresIn`.

A send with an expired quote is rejected with `409 QUOTE_EXPIRED`; the guide said the service gets a new quote.

Get a new quote and show the user its pricing

* **Removed:** `remittance.created` was documented but never sent.

The `sweep.*` events, `remittance.rateRefreshFailed`, `remittance.reconciliationUploaded` and `remittance.reconciliationFailed` are no longer sent and are removed from the guide

* **Removed:** `remittance.escalated` is no longer sent.

Follow a transfer through its lifecycle events and [Check Transaction Status](#check-transaction-status), and quote its `id` to Spendl support

* Bumped public API doc version to 1.71
* 2026-10-22: v1.70 — Journal API: read your ledger and look up a journal entry by its ID
  * New `GET /api/journal/entries/:journalId`: one journal entry by the `journalEntryId` a wallet mutation returned, in any status, with its double-entry lines, user, initiator, reversal links and fee metadata.

An entry outside your ledger returns `404 JOURNAL_ENTRY_NOT_FOUND`

* New `GET /api/journal/entries`: your journal entries, filtered by type, status, `postedAt` range, user, initiator, system account or amount, 1–200 per page.

A user, initiator, account, or amount filter needs a period of at most 366 days

* New `GET /api/journal/summary`: entry counts and totals by type, a daily series, daily fee revenue and expense, and system account balances for a period of at most 366 days (default: the last 30 days); a longer period returns `422 JOURNAL_DATE_RANGE_TOO_LARGE`
* New `GET /api/journal/trial-balance`: the sum of every account balance in your ledger, `0` when it balances
* All four need the `read` scope and read only your tenant's ledger
* Bumped public API doc version to 1.70
* 2026-10-22: v1.69 — Polled KYC webhooks get a new key for each occurrence
  * **Changed:** `kyc.approved`, `kyc.rejected` and `kyc.review_required` sent for a KYC status change detected by polling now get a new key for each occurrence.

Before, the same change happening twice on one `kycRevision` (for example a user rejected, approved again and rejected again) repeated the first key, so removing duplicates by key could drop the later event.

See [Idempotency Keys](#idempotency-keys)

* A redelivery still carries the same key, and a webhook already queued keeps the key it was queued with
* Nothing to change if you remove duplicate webhooks by the full idempotency key and don't parse it
* Bumped public API doc version to 1.69
* 2026-10-21: v1.68 — Spendl compliance can withdraw a KYC approval
  * **New:** Spendl compliance can withdraw the KYC approval of a user.

The user's `kycStatus` changes from `Approved` to `Rejected`, and an `active` account returns to `pending`.

`syncDetails.kycValidation` is unchanged.

See [Check ingestion status](#check-ingestion-status)

* You then receive [`kyc.rejected`](#kycrejected) after the earlier `kyc.approved`, with a `rejectionReason` you can show the user, followed by `account.status_changed` if the account was `active`, and `compliance.hold_set` unless a compliance hold was already in place.

The `kyc.rejected` carries a new idempotency key, distinct from the earlier events'.

See [Idempotency Keys](#idempotency-keys)

* To verify the user again, replace their KYC data or a document.

Spendl compliance reviews that verification before the user can be approved again

* Treat the latest KYC event as the user's current status, stop money actions for a user whose `kycStatus` is no longer `Approved`, and remove duplicate webhooks by the full idempotency key.

Don't read `kycValidation.status: activated` alone as approved: check `kycStatus`

* Bumped public API doc version to 1.68
* 2026-10-20: v1.67 — Spendl compliance can approve a user that verification rejected
  * **New:** Spendl compliance can approve a user whose KYC verification rejected them (`syncDetails.kycValidation.status: tgpd_rejected`).

The user's `kycStatus` becomes `Approved` and the account is activated.

`kycValidation.status` stays `tgpd_rejected` and `kycValidation.rejectionReason` becomes `null`.

See [Check ingestion status](#check-ingestion-status)

* You then receive [`kyc.approved`](#kycapproved) after the earlier `kyc.rejected`, followed by `account.status_changed` if the account was not yet active, and `compliance.hold_cleared` if a compliance hold was in place.

The `kyc.approved` carries a new idempotency key, distinct from the earlier events'.

See [Idempotency Keys](#idempotency-keys)

* Nothing to change if you remove duplicate webhooks by the full idempotency key and treat the latest KYC event as the user's current status.

Don't read `kycValidation.status: tgpd_rejected` alone as rejected: check `kycStatus`

* Bumped public API doc version to 1.67
* 2026-10-19: v1.66 — Proof of residence checked automatically, with a new review code
  * **Changed:** a user whose proof of residence matches, and who passes every other check, is approved without manual review
  * **New review code:** `POR_NAME_MISMATCH`: the name on the proof of residence does not match the name submitted.

The user goes to review, not rejection.

`POR_ADDRESS_MISMATCH`, `POR_DOCUMENT_OUTDATED` and `POR_DOCUMENT_FUTURE_DATED` can now be sent too.

See [Review reason codes](#review-reason-codes)

* Bumped public API doc version to 1.66
* 2026-10-19: v1.65 — A name with an apostrophe, accent or hyphen no longer fails the document check
  * **Fixed:** the identity document and proof of residence checks now tolerate common differences in how a name is written, such as apostrophes, accents, hyphens and spacing.

A surname sent as O'Neill and read as ONEILL is no longer rejected with "The surname you entered does not match the surname on your uploaded document."

* Keep sending names as they appear on the identity document.

To re-verify a user rejected for this reason, upload their identity document again

* Bumped public API doc version to 1.65
* 2026-10-19: v1.64 — An incomplete compliance screening result now holds the user for review
  * **Fixed:** a compliance screening result that could not be fully read now holds the user for review (`SCREENING_UNAVAILABLE`), as a screening that could not run already did
  * Bumped public API doc version to 1.64
* 2026-10-16: v1.63 — A disbursement retry completes the batch
  * **Changed:** a same-key retry of `POST /api/wallet/disburse` completes the remaining recipients; already-paid recipients return their original `journalEntryId` as `posted` or `escrowed` and are not paid again.

Spendl records the disbursement just before its first payment.

A retry after that skips the whole-batch balance check and has `idempotentReplay: true`, which does not mean anyone was paid

* **Changed:** the key belongs to one disbursement.

A retry with a different `senderUserId`, recipient list or amount returns `409 IDEMPOTENCY_KEY_MISMATCH`, and nobody is paid.

The order of the recipients does not matter

* A first attempt still returns `400 INSUFFICIENT_FUNDS` before any payment when the total exceeds the available funds; a same-key retry after it checks the balance again.

See [Disburse retries](#disburse-retries)

* `503 INTERNAL_ERROR` means Spendl could not record the disbursement.

That attempt started no new payments, but an earlier or concurrent attempt with the same key may have paid recipients.

Retry with the same idempotency key and payload

* To retry recipients reported `failed`, resend the whole batch with the same key: a recipient that failed after a timeout may still have been paid.

See [Disburse retries](#disburse-retries)

* Bumped public API doc version to 1.63
* 2026-10-16: v1.62 — Error outcomes, reserved key prefixes and wallet webhook examples
  * **Changed:** `/api/vouchers/*` and `/api/remittance/*` now have a 50-second limit, as the wallet routes do.

A request that runs long is answered with a `5xx`: at the latest `504 REQUEST_TIMEOUT` after 50 seconds, and often sooner with another `5xx`, such as `504 VOUCHER_PAYOUT_PERFORM_FAILED`, a `502 VOUCHER_PAYOUT_NETWORK_ERROR` or `502 UPSTREAM_NETWORK_ERROR`, or a plain-text `504` from the network edge.

The request may still complete.

Treat these timeout and network answers, or no response, as unknown, not failed.

Keep the key: for a voucher payout, poll status with it; otherwise retry with it.

A remittance send needs a new quote first (see [Error Outcomes](#error-outcomes)).

`500 VOUCHER_PAYOUT_REVERSAL_FAILED` is not one of these: stop and escalate it

* **New:** [Error Outcomes](#error-outcomes): for transfer and send-to-bank, which errors mean nothing moved, may have moved, or moved, and what to do for each, with links to the outcome rules of the other money routes.

The [remittance send](#initiate-send) errors table now gives each error's outcome, and the Zapper withdrawal, crypto and disburse sections say which `4xx` errors spend the key or leave earlier payments in place

* **New:** keys with a reserved prefix are refused.

A key that starts with a reserved prefix returns `422 VALIDATION_ERROR` before anything moves, on the wallet money routes, Zapper withdrawals and remittance sends; on disburse it fails every recipient inside a `200`.

See [Idempotency](#idempotency)

* **Fixed:** remittance `409 QUOTE_EXPIRED` with `data.reversed: true` (the debit was refunded) spends the key: send a new quote with a new key.

Previously the guide said to always retry with the same key, which then returns `422 IDEMPOTENCY_KEY_ALREADY_USED`.

Without `data.reversed`, that request moved nothing, but it says nothing about an earlier attempt with the key: send a new quote with the same key, which returns the earlier transaction if it went through

* **Fixed:** the `wallet.deposit_completed`, `wallet.transfer_completed`, `wallet.load_card_completed`, `wallet.purchase_voucher_completed`, `wallet.repay_debt_completed` and `wallet.send_to_bank_completed` examples showed `result` fields these webhooks never had.

`result` is the route's `200` response body without `success`.

On send-to-bank and load-card, `status: "posted"` means debited and accepted by the payment partner, not yet paid.

The webhooks did not change

* **Fixed:** send-to-bank `WALLET_SEND_TO_BANK_FAILED`, with any `5xx`, means the outcome is unknown, not that the payment was refunded: retry with the same key.

[`wallet.send_to_bank_failed`](#walletsend_to_bank_failed) follows only if the payment is later failed and refunded, and a missing webhook does not mean the payment succeeded

* **Fixed:** in [Transaction History](#transaction-history), a refunded send-to-bank or card load now shows `displayStatus: "reversed"`, matching its `status`; it showed `pending` before.

The guide now says what `displayStatus` means

* Bumped public API doc version to 1.62
* 2026-10-16: v1.61 — Webhook when a send-to-bank payment fails and is refunded
  * **New:** [`wallet.send_to_bank_failed`](#walletsend_to_bank_failed) is sent when a [Send to Bank](#send-to-bank-eft) payment fails and its whole debit, fee included, is returned to the wallet: when the payment partner refuses it at submission (`502 PAYACCSYS_LOAD_FAILED` with `data.reversed: true`, when Spendl received the refusal), and when the bank fails or cancels a payment it had accepted.

The payload has `userId`, `journalEntryId` and `amount` (ZAR cents, before the fee)

* Key: `wallet.send_to_bank_failed:{userId}:{journalEntryId}`.

A refund reported again, for example on a same-key retry, reuses it

* Additive and opt-in: the API sends it only when you have a `wallet.send_to_bank_failed` endpoint configured.

Ask your account manager to add one.

Nothing else changes

* Bumped public API doc version to 1.61
* 2026-10-15: v1.60 — Sending the same KYC again no longer restarts verification
  * **Changed:** `PATCH /api/ingest/:id/kyc`: a PATCH whose data and documents equal what we already hold no longer restarts verification; the response has `unchanged: true`.

Nothing is written or queued, so an approval or a rejection and the compliance screening stay as they are, a verification already running continues, and no webhook is sent.

`changedFields` is `[]`, `syncStatus` is the account's current KYC submission status, `callbackStatus` is `enqueued`, `retryScheduled` is `false`, and `updateId` is the original KYC update's id when we still hold it.

Previously every PATCH reset the KYC to pending and ran verification again

* While the account's KYC submission or verification has `failed`, the same data still restarts both, as before.

After a rejection, correct the data or contact Spendl support to have verification re-run

* **Changed:** `changedFields` on the KYC PATCH response and its `account.updated` webhook now lists only the `kycData` fields whose value changed, including fields the new data no longer has.

Previously it listed every field sent

* Additive: `unchanged` appears only on such a response, and it is the only signal that a KYC PATCH changed nothing: `changedFields` is also `[]` when the same data restarts a failed KYC submission or verification, on the response and on its `account.updated` webhook
* The data is compared with what we hold as we store it: a text field stores a number as JavaScript's `String()` writes it (`27821234567` equals a held `"27821234567"`), and `tncAccepted` and `samePostal` store `true`, `"true"`, `"yes"`, `1` or `"1"` as `true` and `false`, `"false"`, `"no"`, `0` or `"0"` as `false`.

A PATCH that only changes the JSON type of a named KYC field (a text field, `tncAccepted` or `samePostal`; e.g.

`false` for `"false"`) is unchanged.

Any other difference, including case, spaces, a leading zero and a date written another way, is a change and restarts verification as before.

Values inside an object field are compared as sent

* Spendl now keeps these stored values wherever it holds the user's KYC data (`false`, not the `"false"` sent)
* Bumped public API doc version to 1.60
* 2026-10-14: v1.59 — Voucher payouts: amount steps and recipient error details
  * `GET /api/vouchers/providers/:providerCode/limits` now returns `amountStepItt` for a product that pays out only in whole multiples of a fixed amount, such as Nedbank Cardless Withdrawal (`1000`, R10.00).

Other products do not return the field

* `POST /api/vouchers/quote` and `POST /api/vouchers/perform` reject an amount that is not a multiple of `amountStepItt` with `422 VOUCHER_PAYOUT_AMOUNT_OUT_OF_RANGE`, a message that names the step, and `data.reason: "AMOUNT_STEP"` with `data.amountStepItt`, before any money moves.

An amount outside the limits gets the same type with its usual message and no `data.reason`

* `422 VOUCHER_PAYOUT_INVALID_RECIPIENT` now names the field in `data.field` and, when present, the reason in `data.reason`: `SA_ID_LENGTH`, `SA_ID_INVALID`, `DATE_INVALID`, `DOB_ID_MISMATCH`, `MOBILE_INVALID`, `COUNTRY_INVALID`, `COUNTRY_REQUIRED` or `REQUIRED`.

`DATE_INVALID`, `COUNTRY_INVALID` and `COUNTRY_REQUIRED` are not returned yet.

Documented the accepted formats of `idType`, `idNumber`, `dateOfBirth`, `gender`, `mobile` and `countryOfIssue`

* `recipient.nationality` is deprecated.

It is accepted but ignored

* **Changed:** a same-key retry of a voucher payout that ended in `VOUCHER_PAYOUT_FAILED` now returns `422 VOUCHER_PAYOUT_FAILED` again when the details are unchanged.

Previously it returned the undocumented `422 VOUCHER_PAYOUT_PERFORM_FAILED`.

Use a new idempotency key to try again

* Documented that `VOUCHER_PAYOUT_FAILED` is the only `422` on perform that spends the idempotency key.

Every other `422`, `INSUFFICIENT_FUNDS` included, is returned before any money moves: resending the same key after `INSUFFICIENT_FUNDS` performs the payout once the wallet is funded

* Documented `409 VOUCHER_PAYOUT_PERFORM_FAILED` for a key already used for a payout with different details, which the API already returned.

With a `5xx` status, the same type means the outcome is unknown: keep the key and poll status.

Branch on the HTTP status, not only on the type

* Bumped public API doc version to 1.59
* 2026-10-14: v1.58 — The original outcome on a same-key retry
  * `409 DUPLICATE_IDEMPOTENCY_KEY` on `POST /api/wallet/deposit`, `transfer`, `load-card`, `send-to-bank`, `purchase-voucher` and `repay-debt` now carries `data.result`: the first request's outcome, with the field names and units of that route's success response.

See [Idempotency](#idempotency) for the fields per route

* `data.result` is included only when the key was first used in a request of yours for the same operation and the same user.

Its `status` is the transaction's current status: usually `posted`; `reversed` means the money was later returned to the wallet

* Additive: `data.key` and `data.existingEntryId` are unchanged.

A same-key retry of a failed or unconfirmed `load-card` or `send-to-bank` still returns its first error

* Bumped public API doc version to 1.58
* 2026-10-13: v1.57 — A pending remittance can no longer be cancelled
  * **Changed:** `POST /api/remittance/transactions/:transactionId/cancel` now returns `422 NOT_CANCELLABLE` for a `pending` transfer.

The exchange rate is booked and funded when the transfer is sent, so the transfer goes ahead.

Previously a `pending` transfer that had not yet been submitted was cancelled and its wallet refunded

* Cancelling an uncollected cash-pickup voucher works as before
* `remittance.cancelled` now comes only from the remittance network (`MR107`, `MR109`).

It is no longer sent with `statusCode: "USER_CANCEL"`.

The `remittance.refunded` example `reason` is now `User cancelled`, as sent for a voucher cancel

* Bumped public API doc version to 1.57
* 2026-10-13: v1.56 — Error codes the API already returns are now documented
  * No API behaviour changed.

These codes were returned before but were not listed

* `PATCH /api/ingest/:id/details`: `422 VALIDATION_ERROR` and `422 INVALID_EMAIL` for a bad email, and `409 ACCOUNT_UPDATE_CONFLICT`
* `PATCH /api/ingest/:id/kyc`: `422 UNSAFE_FIELDS` and `409 ACCOUNT_UPDATE_CONFLICT`
* `POST /api/ingest/sumsub`: `422 UNSAFE_FIELDS`, and `422 VALIDATION_ERROR` for a body that is not a single object
* `POST /api/kyc/...`: `422 USER_EMAIL_MISSING`, `422 USER_NAME_MISSING`, `422 FILE_READ_ERROR`, `500 STORAGE_ERROR` and `500 DATABASE_UPDATE_ERROR`
* `POST /api/remittance/send`: `422 INVALID_QUOTE`
* Bumped public API doc version to 1.56
* 2026-10-13: v1.55 — Sumsub users get their gender from a South African ID number
  * For a user created with `POST /api/ingest/sumsub`: when Sumsub holds no gender for the applicant and the verified document is a South African ID (`ID_CARD` or `GREEN_BOOK`) with a valid ID number, the API now stores the gender (`M` or `F`) encoded in that number.

Previously `gender` was left empty and listed in `sumsub.unmappedIdentityFields`

* A gender Sumsub does hold is used as before.

For a passport or a foreign ID, a missing `gender` is still left empty and listed

* Users created before this change are not updated
* A South African ID number must now start with a calendar date (`YYMMDD`) to count as valid.

[Card readiness](#card-readiness) already required the first six digits to match `dob`, so its report changes only when `dob` is missing or malformed: an `idNumber` such as one starting `900230` is then listed in `invalidFields`

* Bumped public API doc version to 1.55
* 2026-10-12: v1.54 — Pay@ reads check that the user is yours
  * **Changed:** `GET /api/payat/account/:userId`, `GET /api/payat/transactions` and `GET /api/payat/withdrawal/list/:userId` now return `403 FORBIDDEN` when `userId` is not one of your users, and `422 VALIDATION_ERROR` when it is not a 24-character hex ID.

Reads for your own users are unchanged

* Documented `403 FORBIDDEN` for a `userId` that is not one of your users on `POST /api/wallet/deposit/payat`, `POST /api/wallet/withdrawal/payat`, `POST /api/wallet/deposit/zapper`, `POST /api/wallet/withdrawal/zapper` and `POST /api/vouchers/perform`, which these routes already returned.

[Wallet Operations](#wallet-operations) now lists which routes answer `403 FORBIDDEN` and which answer `404 USER_NOT_FOUND`

* Documented the amount limits on Pay@ deposits and withdrawals: an amount outside the fixed range returns `422 VALIDATION_ERROR`, and `BELOW_MINIMUM_AMOUNT`, `EXCEEDS_MAXIMUM_AMOUNT` and `PAYOUT_AMOUNT_OUT_OF_RANGE` apply only where Spendl has configured narrower limits
* `POST /api/wallet/load-card`'s errors now list `404 USER_NOT_FOUND` and `422 MISSING_IDEMPOTENCY_KEY`
* Documented `422 INVALID_USER_ID` on `GET /api/ingest/status/:id` for a malformed ID
* The Pay@, Zapper and disbursement error tables now list the `401` types the API returns (`NO_AUTH_HEADER`, `INVALID_AUTH_FORMAT`, `INVALID_TOKEN`, `NO_TENANT_ON_TOKEN`) in place of `NO_TENANT_ON_CONTEXT`, which these routes do not return
* Apart from the three Pay@ reads, no behaviour changed
* Bumped public API doc version to 1.54
* 2026-10-12: v1.53 — Zapper withdrawal validation corrected
  * `POST /api/wallet/withdrawal/zapper` no longer answers a well-formed request with `422 VALIDATION_ERROR` "The 'idempotencyKey' field is required." That field is not part of this route; `withdrawalRequestId` remains the only idempotency token you send
  * A validation error on a Zapper route now names only fields of that route.

A `withdrawalRequestId` the payment service rejects is reported as `withdrawalRequestId`

* Documented `502 ZAPPER_WITHDRAWAL_INITIATE_FAILED` on `POST /api/wallet/withdrawal/zapper`: the payment service could not process the request, and your input did not cause it
* Bumped public API doc version to 1.53
* 2026-10-12: v1.52 — Account status follows activation
  * `userStatus` on `GET /api/ingest/status` now follows the account status in Spendl.

It becomes `active` when verification approves the user, and it reflects later changes such as a suspension.

Previously it could stay `pending` for an active, approved account

* Documented the fixed values of `userStatus` (`pending`, `active`, `suspended`, `inactive`) and `kycStatus` (`Not Started`, `Pending`, `Approved`, `Rejected`) on `GET /api/ingest/status`.

The `kyc.approved` and `kyc.rejected` examples now show the values the API sends for its own outcomes (`Approved`, `Rejected`); webhooks for status changes made outside the API still carry the tenant's value

* Bumped public API doc version to 1.52
* 2026-10-12: v1.51 — Earlier notice when a Sumsub review cannot finish
  * For a user created with `POST /api/ingest/sumsub`: when the shared verification does not satisfy Spendl's verification level (a step is not included in it, or a shared item fails Spendl's own check), Sumsub waits for the person and the review cannot finish.

The API now sends `kyc.review_required` with `reasonCode: "SUMSUB_DOCUMENTS_REQUESTED"`, usually within a few minutes.

Previously you received `SUMSUB_REVIEW_TIMEOUT` after 48 hours

* `GET /api/ingest/status/:id` reports `sumsub.lastErrorCode: "SUMSUB_DOCUMENTS_REQUESTED"` for such a user
* `SUMSUB_REVIEW_TIMEOUT` is unchanged for a review that is still running after 48 hours
* `sumsub.shareToken` is used without any whitespace around it
* Bumped public API doc version to 1.51
* 2026-10-12: v1.50 — Remittances must be enabled for your tenant
  * **Breaking:** `POST /api/remittance/quote`, `/name-check`, `/validate` and `/send` now need remittances enabled for your tenant.

Spendl enables them on request.

Otherwise they return `403 REMITTANCE_NOT_ENABLED`, and nothing is quoted, checked or sent.

Previously any `write` key could call them

* When the API cannot confirm that remittances are enabled, these four requests return `503 REMITTANCE_UNAVAILABLE`, and you can retry
* Corridors, banks, transactions, status, statistics, user limits and cancellation are unchanged
* Bumped public API doc version to 1.50
* 2026-10-10: v1.49 — Hosted checkout deposits
  * New `POST /api/wallet/deposit/checkout`: creates a hosted checkout session for a wallet top-up and returns `sessionId` and `redirectUrl`.

The user pays by card, Capitec Pay or bank transfer on the hosted page, and Spendl credits the wallet asynchronously

* New `GET /api/wallet/deposit/checkout/status/:sessionId`: `pending`, `completed`, `failed`, `expired` or `cancelled`; `credited: true` is the success signal.

Final `feeAmount`, `netAmount` and `paymentMethod` appear once credited

* An idempotency key is required.

One key creates one session per tenant; a same-key retry returns the same session with `idempotentReplay: true`, and a key reused for a different user, amount or fee returns `409 IDEMPOTENCY_KEY_MISMATCH`

* New error types `CHECKOUT_SESSION_FAILED`, `CHECKOUT_SESSION_UNCONFIRMED`, `CHECKOUT_SESSION_NOT_FOUND` and `CHECKOUT_STATUS_FETCH_FAILED`.

A `CHECKOUT_SESSION_FAILED` message says whether to retry with the same idempotency key or a new one

* `wallet.incoming_credit` is sent for hosted checkout credits too, with the same payload and key as other deposits
* No existing endpoint, field, error type or webhook changed
* 2026-10-10: v1.48 — Tenant wallets use the `tenant_wallet` scope
  * `POST /api/wallet/tenant-wallets` and `POST /api/wallet/disburse` now use the new [`tenant_wallet` scope](#scopes) as well as `write`.

Spendl grants it on request.

Previously they needed the `admin` scope

* A `write` key without it receives `403 INSUFFICIENT_SCOPE` with `data.requiredScope: "tenant_wallet"` instead of `403 FORBIDDEN`, and nothing is created or paid
* Every other operation is unchanged
* Bumped public API doc version to 1.48
* 2026-10-10: v1.47 — Direct deposits need the `deposit` scope
  * **Breaking:** `POST /api/wallet/deposit` now needs the new [`deposit` scope](#scopes) as well as `write`.

Spendl grants it on request.

A key without it receives `403 INSUFFICIENT_SCOPE` with `data.requiredScope: "deposit"` before the user is looked up, and nothing is credited.

Previously any `write` key could deposit

* `fromSuspense: true` still needs the `admin` scope.

Other keys now receive `403 INSUFFICIENT_SCOPE` with `data.requiredScope: "admin"` instead of `403 PRIVILEGED_WALLET_FIELD`

* The deposit errors now list `409 DUPLICATE_IDEMPOTENCY_KEY` (already processed), which a same-key retry already returned
* Pay@ and Zapper deposits and every other wallet operation are unchanged
* Corrected the card funding limits description: for a missing or unknown tier the API reports the Savvy cap
* Bumped public API doc version to 1.47
* 2026-10-09: v1.46 — Review reason codes
  * The `kyc.review_required` webhook now includes `reviewReasonCodes`, the reasons Spendl verification sent the user to manual review.

The key is always present, and is `[]` when no Spendl check explains the review

* `GET /api/ingest/status/:id` now returns `syncDetails.kycValidation.reviewReasonCodes`.

It lists the reasons while the user is in review (`kycValidation.status` is `tgpd_review` and no manual decision has been made), and is `[]` otherwise

* See [Review reason codes](#review-reason-codes) for the values.

Codes never carry provider messages, scores or screening details

* Idempotency keys are unchanged.

A `kyc.review_required` already queued when this change shipped is sent without the field

* Bumped public API doc version to 1.46
* 2026-10-08: v1.44 — Emails stored lowercase, never linked to an existing account
  * Emails (`userDetails.email`, `kycData.email`) are stored trimmed and lowercase on ingest, on `PATCH /api/ingest/:id/details` and on `PATCH /api/ingest/:id/kyc`, and returned that way in responses and webhooks
  * Duplicate emails are detected ignoring case: `409 DUPLICATE_EMAIL` (or a batch `failed[]` entry with that `reason`).

Do not re-send a user you already ingested

* New `409 EMAIL_ALREADY_REGISTERED`: this email cannot be used for a new user.

The user is not created and never linked to an existing account.

If the existing account is one your user created in your app and never used, contact your Spendl account manager

* A `PATCH /api/ingest/:id/details` that sends an email stores it trimmed and lowercase; leave `email` out of a PATCH that does not change it
* `PATCH /api/ingest/:id/kyc` matches the payload email to the account ignoring case
* Batch `failed[]` and `POST /api/validate` `errors[]` entries echo each record's email as you sent it; an empty email is echoed as `""` (previously `"unknown"`)
* Bumped public API doc version to 1.44
* 2026-10-08: v1.43 — Ingest stores only tenant fields
  * `POST /api/ingest` and `POST /api/validate` now keep only `userDetails.email`, `userDetails.status`, `kycDetails.kycData`, `clientNo` and `preferences` from a standard-format record, for single and batch requests.

Every other field is ignored, and the request is still accepted.

The flat format is unchanged

* A batch `failed[].record` no longer echoes ignored fields
* Bumped public API doc version to 1.43
* 2026-10-08: v1.42 — `kyc.documents_completed` delivery fix
  * `kyc.documents_completed` is now sent once per user, by the document upload that first completes the user's KYC, as documented
  * No past events are replayed.

A user whose documents were already complete before this fix gets the callback on their next document upload, if their KYC has not already been approved or rejected by Spendl's verification

* Payload and `X-Idempotency-Key` are unchanged
* Bumped public API doc version to 1.42
* 2026-10-07: v1.41 — Incoming credit webhook
  * `wallet.incoming_credit` is now sent for each deposit into a user's wallet (EFT or instant EFT to the deposit reference, Pay@, Zapper), as soon as the wallet is credited, instead of some time later.

Delivery is best effort; `GET /api/wallet/history/:userId` is the source of truth

* Balances and `amount` are ZAR cents.

`amount` is what reached the wallet after any deposit fee.

New field `transactionId`: the deposit's `_id` in the wallet history

* New key `wallet.incoming_credit:{userId}:{transactionId}`
* Transfers between users and reward payouts do not send it.

Like `wallet.debt_repayment_failure`, it is sent only when the endpoint is configured

* Bumped public API doc version to 1.41
* 2026-10-05: v1.40 — Polled status-transition webhooks
  * `account.status_changed`, `compliance.hold_set`, `compliance.hold_cleared`, `wallet.suspended`, `wallet.closed` and `wallet.incoming_credit` now use a new key instead of a timestamp-based key.

A transition keeps its key across every redelivery, and a transition that recurs later gets a new one

* These events are now delivered one at a time per user, in the order they were detected, and after any earlier KYC lifecycle event for that user
* Bumped public API doc version to 1.40
* 2026-10-03: v1.39 — Money-out outcomes
  * Every endpoint that sends money from a user's wallet (transfer, load card, send to bank, repay debt, the deprecated purchase voucher, voucher payouts, Pay@ and Zapper withdrawals, remittance send, crypto withdrawals and place-order) can return `403 ACCOUNT_RESTRICTED` when the user's account is restricted from sending money.

Receiving money is unchanged

* A same-key retry of a wallet debit that already went through (`transfer`, `load-card`, `send-to-bank`, `purchase-voucher`, `repay-debt`) returns `409 DUPLICATE_IDEMPOTENCY_KEY` with `data.existingEntryId`, even when the first debit used up the balance (previously this could read as `INSUFFICIENT_FUNDS`).

Treat it as processed

* Load card and send to bank return `502 PAYACCSYS_LOAD_FAILED` when the payment provider rejects the request and the wallet is refunded (`data.reversed: true`), and `502 PAYACCSYS_LOAD_AMBIGUOUS` / `PAYACCSYS_EFT_AMBIGUOUS` when the outcome is unknown, instead of a generic error.

New: `502 PAYACCSYS_LOAD_REVERSAL_FAILED` and `PAYACCSYS_EFT_REVERSAL_FAILED` when the request was rejected but the refund to the wallet failed.

A same-key retry returns the first attempt's error again

* Zapper withdrawals: new `422 ZAPPER_WALLET_REFUND_FAILED` when the payment failed but the refund to the wallet failed.

A replayed `withdrawalRequestId` of a failed payment now returns its `422` error instead of `success: true`.

A replay of a payment still processing returns `429 SEND_IN_PROGRESS` (`data.idempotentReplay: true`) instead of `success: true`, and a new payment while the user's earlier payment to the same QR code is still processing returns `429 SEND_IN_PROGRESS` (`data.idempotentReplay: false`); keep the `withdrawalRequestId` and check again, never treat either as paid or failed.

Reusing a `withdrawalRequestId` for a different QR code, amount or tip returns `409 IDEMPOTENCY_KEY_MISMATCH`

* Voucher payouts can now return `502 VOUCHER_PAYOUT_AMBIGUOUS` where an unknown outcome previously returned a generic `502`
* Voucher payouts return `403 KYC_REQUIRED` when the user's KYC is not approved, instead of a retryable `502`
* Disbursements report a recipient already paid under the same key as `posted` (or `escrowed`) with the original `journalEntryId`, instead of `failed`, and do not pay them again; recipients not yet paid are processed.

Retry with an unchanged payload, and use a new key for a new disbursement

* The API now waits up to 40 seconds for a result on wallet, Pay@, Zapper, voucher payout and remittance requests before returning `502`.

The network edge can still answer a slow request with a `504` sooner.

Either way the outcome is unconfirmed: retry with the same idempotency key, which never moves money twice

* Bumped public API doc version to 1.39
* 2026-09-30: v1.38 — Crypto API hardening
  * User-scoped `/api/crypto` endpoints return `404 USER_NOT_FOUND` when `userId` is not one of your users, and `422 VALIDATION_ERROR` when it is not a 24-character Spendl ID
  * `POST /api/crypto/place-order`: `side` is optional and defaults to `SELL`; any other value returns `422 VALIDATION_ERROR`
  * New `409 CRYPTO_RECONCILE_PENDING` for a place-order or withdrawal whose outcome is still being confirmed.

Retry with the same idempotency key; `data` can include `customerOrderId` or `pendingId`

* A temporary Spendl-side error now returns `502` (`CRYPTO_PROVIDER_ERROR` or the endpoint's `CRYPTO_*_FAILED` type), never `401`/`403`.

`403 KYC_REQUIRED` is unchanged, and `403 TENANT_SUSPENDED` is now documented

* `403 USER_MISMATCH` is no longer returned by `/api/crypto`.

A `userId` outside your tenant returns `404 USER_NOT_FOUND` instead

* A timeout, network error or other lost-answer 5xx on `POST /api/crypto/withdrawals` or `POST /api/crypto/place-order` now says in its message to retry with the same idempotency key, because the request may still have gone through.

`503 CRYPTO_NOT_CONFIGURED` and the authentication `502` carry no such message

* `POST /api/crypto/place-order` returns `400 CARD_REQUIRED` when the user has no linked card.

Documented `409 IDEMPOTENCY_KEY_PAYLOAD_MISMATCH`, `409 IDEMPOTENCY_KEY_IN_PROGRESS` and `409 ORDER_IN_FLIGHT` in the error table

* `GET /api/crypto/order-status/:orderId` returns a terminal `400 TOO_SMALL` for a filled order with nothing left after fees.

Keep polling until a terminal result, because the sale is settled as part of the poll

* Error `data` now carries `reason`, `minimumWithdrawAmount` (`BELOW_MIN`) and the fee breakdown (`TOO_SMALL`, `TOO_SMALL_AFTER_BANK`) as documented
* Corrected the place-order `customerOrderId` example: `itt-` followed by 28 hexadecimal characters
* Documented the order-status bodies (`PARTIAL`, `FAILED`, `FILLED`), the filled-order fields, the place-order response, and the withdrawal list/detail wrappers
* Corrected the error table: `KYC_REQUIRED` (was `KYC_NOT_APPROVED`), `CRYPTO_NOT_CONFIGURED` is `503` (was `422`), and `CRYPTO_PROVIDER_ERROR` carries the provider's status
* `POST /api/crypto/estimate-trade` returns `400 TOO_SMALL_AFTER_BANK` when nothing would reach the card.

Place-order returns `400 TOO_SMALL` only when nothing is left after fees; the R10 minimum is removed

* Withdrawals are checked before anything is sent: `400 BENEFICIARY_REQUIRED`, `SERVICE_PROVIDER_REQUIRED`, `WITHDRAWALS_DISABLED`, `BELOW_MIN` or `INSUFFICIENT_BALANCE`, and `400 NO_SUBACCOUNT` for a user without a crypto account.

The amount is sent at the coin's decimal places, on the coin's configured network when it has one

* `GET /api/crypto/order-status/:orderId` can return `409 ORDER_SETTLE_IN_FLIGHT` while a filled sale is still settling; poll again
* `GET /api/crypto/withdrawals` also lists sell-to-card sales (`source: "TRADE"`, `tradeOrderId`).

`GET /api/crypto/transactions` lists every sale with its status, and items carry `id`, `direction` and a lowercase `status`

* `GET /api/crypto/market-data` leaves out a coin that cannot be priced instead of failing the whole list
* Bumped public API doc version to 1.38
* 2026-09-30: v1.38 — Voucher convergence and one idempotency contract
  * `POST /api/wallet/purchase-voucher` is **deprecated** in favour of the `/api/vouchers` catalogue flow.

It keeps working, and every successful (`2xx`) response now carries `Deprecation: true` and `Link: </api/vouchers/perform>; rel="successor-version"`.

A removal date will be announced here at least 90 days in advance

* `POST /api/vouchers/perform` now emits `wallet.purchase_voucher_completed` for a completed payout, the same event the legacy route sends, so one webhook handler covers both.

The payload carries `source: "vouchers.perform"` and the redacted perform result; voucher PINs, serial numbers, and recipient data are never included.

A `pending` perform sends no callback; recover it with `GET /api/vouchers/status`

* One idempotency contract on every mutation: the key may be sent as `X-Idempotency-Key` or `idempotencyKey` in the body.

A mismatch returns `422 IDEMPOTENCY_KEY_MISMATCH`; a required key that is missing returns `422 MISSING_IDEMPOTENCY_KEY` - **Breaking:** `POST /api/vouchers/perform` returned `400 MISSING_IDEMPOTENCY_KEY`; it now returns `422`, and it accepts the body field - **Breaking:** `POST /api/wallet/disburse` returned `422 VALIDATION_ERROR` for a missing `idempotencyKey`; it now returns `422 MISSING_IDEMPOTENCY_KEY`, and it accepts the header - Wallet mutations (`deposit`, `transfer`, `load-card`, `send-to-bank`, `purchase-voucher`, `repay-debt`, `beneficiary`) now reject conflicting header and body keys instead of silently preferring the body - `POST /api/wallet/beneficiary` now accepts `idempotencyKey` in the body (still optional); Pay@ and Zapper requests now reject conflicting header and body keys as well - Completion webhooks (`wallet.*_completed`, `wallet.beneficiary_added`) now use the key that was actually sent, whether it came from the header or the body, as their `X-Idempotency-Key`, so a header-only retry no longer produces a second callback - **Correction and breaking:** the key was documented as optional on `deposit`, `transfer`, `load-card`, `send-to-bank`, `purchase-voucher`, and `repay-debt`, but it has always been required, and an omitted key was rejected with `400 IDEMPOTENCY_KEY_REQUIRED`.

The API now returns `422 MISSING_IDEMPOTENCY_KEY` instead.

Tenants that already send a key are unaffected.

`beneficiary`, Pay@ deposits, and Zapper deposits stay optional

* The five `/api/vouchers` routes are now in `openapi.yaml`, and `POST /api/wallet/disburse` is in the endpoint summary
* Send-to-bank, disbursements, and the PayShap/RTC voucher products remain separate flows by design
* Bumped public API doc version to 1.38
* 2026-09-30: v1.37 — KYC rejection reason
  * The `kyc.rejected` webhook now includes `rejectionReason`, the reason that verification failed.

The key is always present, and is `null` only when no reason is available

* `GET /api/ingest/status/:id` now returns `syncDetails.kycValidation.rejectionReason`.

It is set when `kycValidation.status` is `tgpd_rejected`, and is `null` otherwise

* Bumped public API doc version to 1.37
* 2026-09-29: v1.36 — Missed debt repayment callback
  * New webhook event `wallet.debt_repayment_failure`, sent when a debt obligation misses its repayment window (installment due date plus `gracePeriodDays`)
  * The event fires **once per obligation**, on the first missed window; later missed installments on the same obligation do not send it again
  * The event is opt-in: the API silently skips it when the tenant has no `wallet.debt_repayment_failure` endpoint, and records no audit failure
  * Payload echoes the `guid`, `machine`, `clientNo` and `loanRefNo` the tenant supplied, and reports the missed installment, the window dates, and the expected and paid amounts as major-unit decimal strings
  * Idempotency key format is `wallet.debt_repayment_failure:{guid}`
  * Bumped public API doc version to 1.36
* 2026-09-29: v1.35 — South African ID check in card readiness
  * [Card readiness](#card-readiness) reports an `ID_CARD` or `GREEN_BOOK` user whose `idNumber` is not a valid South African ID number, or does not match `dob`, under `invalidFields` as `idNumber`.

KYC ingestion and submission are unchanged

* Corrected the `not_ready` description: the personal fields it checks are `name`, `surname`, and `dob`
* Bumped public API doc version to 1.35
* 2026-09-29: v1.34 — Card readiness
  * New `GET /api/cards/:userId/readiness` reports the fields and documents a user still needs before a card can be issued; it is available before KYC approval and changes nothing
  * Documented what a card needs, and the accepted `gender`, `title`, `nationality` and `province` values
  * `POST /api/ingest` ignores `kycDetails.s3Keys`: KYC documents are recorded only through the KYC upload endpoint
  * `suitableContactTime` is documented as 24-hour `HH:mm` (for example `"12:00"`) and the flat-format `contact_time` default is now `"12:00"`; `"12h00"` is still accepted, and a missing or unrecognised contact time never blocks card issuance
  * OpenAPI schemas renamed to describe the payload rather than its origin: `FlatUserPayload`, `IngestFlatUserPayload`, `DebtObligationPayload` and `DebtEligibilityPayload`.

Request and response fields are unchanged; regenerate any client built from the spec

* Bumped public API doc version to 1.34
* 2026-09-28: v1.33 — KYC lifecycle callbacks
  * Added callbacks for document uploads, submission and validation attempts, terminal failures, superseded revisions, and manual-review outcomes
  * Lifecycle payloads expose redacted operational state only; provider errors, KYC values, uploaded content, credentials, and audit records are excluded
  * Existing `kyc.documents_completed`, `kyc.approved`, `kyc.rejected`, and `kyc.review_required` payload keys remain available alongside the new lifecycle fields
  * Bumped public API doc version to 1.33
* 2026-09-23: v1.32 — Cards API
  * New read-only Cards API: card list with issuer state, masked card details, balance, transactions, monthly funding limits, and the card funding account (six `GET /api/cards/…` endpoints, `read` scope)
  * A tenant can now get a user's `cardId` and use `POST /api/wallet/load-card` end-to-end
  * All card monetary fields are integer ZAR cents with `Itt`-suffixed names; card numbers are always masked, and transaction windows are capped at the issuer's 90 days
  * The card contract is provider-neutral: `cardStatus` is a fixed enum (`ACTIVE` … `UNKNOWN`), `cardId` is an opaque string, all card timestamps are UTC ISO 8601, and `feeType`/`provisionStatus` are open lists
  * `limits` reports the KYC-tier monthly **funding** cap (`fundingLimitItt` / `fundingUsedItt` / `fundingRemainingItt`), not a card spending limit; usage is the month's posted card loads, fees included
  * `POST /api/wallet/load-card` returns `404 CARD_NOT_FOUND` when `cardId` is not the debited user's card, and returns `409 CARD_ACCOUNT_MISSING` (nothing debited) while the user's card is not fully provisioned
  * Bumped public API doc version to 1.32
* 2026-09-23: v1.31 — Document uploads re-run verification
  * Uploading a KYC document for a registered user now re-runs verification against the new documents (an in-flight verification of the old ones is superseded): `syncDetails.kycValidation.status` returns to `pending`, `kycStatus` returns to `Pending`, and a new outcome follows
  * A re-verification that lands in manual review sends a new `kyc.review_required`; it is no longer deduplicated against the earlier review for the same user
  * Bumped public API doc version to 1.31
* 2026-09-23: v1.30 — KYC verification outcome visibility
  * `kyc.review_required` is now sent when Spendl verification places a user in manual review (previously only tenant-side status transitions triggered it), with an idempotency key that is stable across retries of the same submission
  * `bank_account_created` is only sent once the KYC verification outcome is known; it is not a KYC approval
  * `GET /api/ingest/status/:id` now includes `syncDetails.kycValidation` (`status`, `attempts`, `error`, `completedAt`), and `kycStatus` reports `Pending` from KYC submission for all ingest formats
  * Verification derives `gender` from a South African ID number when the field is omitted; send `gender` (`M`/`F`) for passport holders
  * Bumped public API doc version to 1.30
* 2026-09-22: v1.29 — Public crypto API
  * New `/api/crypto` gateway for market data, balances, deposits, crypto withdrawals, sell estimate/place-order, and order status
  * Required 8–128 character `X-Idempotency-Key` on create withdrawal and place order
  * A filled sell is not a wallet credit or instant card load
  * Pending `GET /api/crypto/order-status/:orderId` may return `204 No Content` (empty body); continue polling
  * `GET /api/crypto/deposit-addresses` may return a currency-keyed `depositAddresses` map
  * `GET /api/crypto/service-providers` requires `userId`
  * Bumped public API doc version to 1.29
* 2026-09-16: v1.28 — Remittance quote countdown and stale-clock recovery
  * Added `expiresIn` (integer seconds remaining) to `POST /api/remittance/quote` responses — prefer it over `expiresAt` for client-side countdowns to stay immune to clock skew between your host and the Public API
  * `expiresAt` is now the quote's actual expiry, the same deadline the send checks
  * Default quote lifetime raised from 30 s to 50 s, with a configurable cap of 59 s
  * New error `503 UPSTREAM_STALE_CLOCK` (retryable) when less than 5 s of validity would remain on the quote — safe to retry immediately
  * Bumped public API doc version to 1.28
* 2026-09-14: v1.27 — Debt eligibility intake endpoint
  * New endpoint `POST /api/debt/eligibility` records debt-offer eligibility notifications against an existing tenant user (`client_no` or `user_id`)
  * Deduplicated by `uuid`; replaying the same payload returns the acknowledgement without creating another record
  * Added to the protected endpoint summary, OpenAPI spec, and the auth Postman collection
  * Bumped public API doc version to 1.27
* 2026-09-09: v1.26 — Remittance user-limits wire rename (\*Zar → \*Itt)
  * Field names on `GET /api/remittance/user-limits`, the `userLimits` snapshot inside `POST /api/remittance/quote`, and the `USER_DAILY_LIMIT_EXCEEDED` / `USER_MONTHLY_LIMIT_EXCEEDED` error payloads now use the `Itt` suffix (`dailyLimitItt`, `dailyUsedItt`, `dailyRemainingItt`, `monthlyLimitItt`, `monthlyUsedItt`, `monthlyRemainingItt`, `limitItt`, `usedItt`, `remainingItt`, `attemptedItt`), which marks an integer ZAR-cent amount
  * Value semantics are unchanged — same integers, same meaning
  * Bumped public API doc version to 1.26
* 2026-09-08: v1.25 — Payment-flow and KYC contract coverage
  * Documented the required `termsAcceptedAt` confirmation for remittance sends
  * Added the debt audit-log route to the endpoint summary
  * Documented all stable KYC upload validation, stream, conversion, and converted-file size errors
  * Expanded Spendl's end-to-end test coverage across debt repayment, voucher purchase, wallet, Pay@, Zapper, EFT, remittance, and all FICA document types
  * Bumped public API doc version to 1.25
* 2026-09-02: v1.24 — Tenant wallet create API
  * New endpoint `POST /api/wallet/tenant-wallets` (admin scope) creates a KYC-approved `tenant_wallet` user for your tenant
  * Deposit refs use the tenant's 3-letter `treasuryPrefix` plus 8 digits (`XXX-########`, 12 characters).

Missing prefixes return `422 TREASURY_PREFIX_REQUIRED` instead of falling back to `TR`

* New errors: `400 INVALID_EMAIL`, `409 DUPLICATE_EMAIL`, `422 TREASURY_PREFIX_REQUIRED`, `422 TENANT_CONFIG_NOT_FOUND`, `422 TENANT_NOT_ACTIVE`, `403 FORBIDDEN` (non-admin)
* Bumped public API doc version to 1.24
* 2026-08-26: v1.23 — Voucher and payout API
  * Added provider discovery, live provider limits, fee quote, perform, and owner-scoped status endpoints under `/api/vouchers`
  * Perform and status operations are checked against the user who owns the payout
  * Voucher payout perform requests now require an `X-Idempotency-Key` header and the accepted quote's `expectedTotalDebitItt` and `quotedTariffVersion`
  * Documented the required recipient data for all 20 currently supported cash, airtime, gift-voucher, PayShap, and RTC product families
  * Added dynamic limits and fixed-denomination guidance, lifecycle recovery, error handling, and voucher-credential security requirements
* 2026-08-21: v1.22 — Remittance hardening
  * New endpoint `GET /api/remittance/stats` for per-user remittance statistics (transaction counts, monthly totals, top corridors)
  * User-scoped remittance requests (`send`, `listTransactions`, `getTransaction`, `getStatus`, `cancelTransaction`, `getStats`) are checked against the user who owns the transaction
  * Error messages returned to you are sanitised: `4xx` messages meant for you are kept, and authentication and `5xx` messages are replaced with generic ones
  * Transaction detail responses now include `fxRate`, `recipientMsisdn`, `recipientAccountNumber`, `recipientBankCode`, `recipientPartnerCode`, `voucherPartner`, `purposeOfTransfer`, and `sourceOfFunds`
  * Quote responses no longer include the `quoteToken` field
* 2026-08-12: v1.21 — KYC document requirements correction for ID\_CARD
  * **Clarification:** `ID_CARD` identity type requires **both** `idProofFront` and `idProofBack` documents.

Previously the docs grouped `ID_CARD` and `GREEN_BOOK` together as requiring only `idProofFront`

* `GREEN_BOOK` continues to require only `idProofFront`
* Updated the **Required KYC documents per combination** table to list `ID_CARD` and `GREEN_BOOK` as separate rows
* Updated the **KYC Completion Requirements** checklist to separate `ID_CARD` (front + back) from `GREEN_BOOK` (front only)
* No API behaviour change — Spendl already required both documents for `ID_CARD`; this is a documentation-only correction
* Bumped public API doc version to 1.21
* 2026-07-30: v1.19 — Account and KYC updates
  * Added `PATCH /api/ingest/:id/details` for same-tenant mutable account detail updates
  * Added `PATCH /api/ingest/:id/kyc` for full normalized KYC replacement with uploaded-document preservation and KYC revalidation
  * Added the details-sync status fields (`detailsSyncStatus`, `detailsSyncedAt`, `detailsSyncError`, `detailsSyncAttempts`) to ingestion status responses
  * Added the `account.updated` callback with a safe change-summary payload and `account.updated:{userId}:{updateId}` idempotency key
  * Account update callbacks are sent only after the accepted update is applied
* 2026-07-28: v1.18 — Remittance gateway safeguards
  * A quote can be used only for the tenant, sender, amount, destination, payment type and routing partner it was issued for; a mismatch fails before the wallet is debited
  * Required a durable idempotency key for remittance sends and enabled the documented `X-Idempotency-Key` header for browser clients
  * Added pre-debit validation for rail-specific recipient fields, corridor routing, destination banks, and cash-pickup partners
  * Limited remittance transaction responses to the stable tenant-facing fields documented in this guide
* 2026-07-28: v1.17 — Remittance contract corrections
  * Standardized `INSUFFICIENT_FUNDS` as HTTP 422 across wallet, Zapper, and remittance operations
  * Defined `receiveAmount` as a fixed two-decimal transport value for all destination currencies, including zero-decimal currencies
  * Added `AMOUNT_TOO_LOW` and `AMOUNT_TOO_SMALL` errors and documented automatic debit reversal after quote and receive-amount failures
  * Clarified durable idempotency replay behaviour, raw destination-network status codes, and when a transfer can still be cancelled
  * Bumped the public API document version to 1.17
* 2026-07-28: v1.16 — Remittance event catalogue
  * Documented all customer remittance lifecycle events: `remittance.created`, `remittance.submitted`, `remittance.completed`, `remittance.failed`, `remittance.cancelled`, `remittance.cashPickupReady`, and `remittance.refunded`
  * Added exact lifecycle payload examples, transition timing, amount semantics, refund behaviour, and cash-pickup voucher handling
  * Documented the events `remittance.escalated`, `remittance.rateRefreshFailed`, `remittance.reconciliationUploaded`, and `remittance.reconciliationFailed` (no longer sent; see v1.71)
  * Bumped the public API document version to 1.16
* 2026-07-28: v1.15 — Cross-border remittance API
  * Added destination discovery endpoints: `GET /api/remittance/corridors` and `GET /api/remittance/banks`
  * Added recipient preparation endpoints: `POST /api/remittance/quote`, `POST /api/remittance/name-check`, and `POST /api/remittance/validate`
  * Added `POST /api/remittance/send` for wallet-funded transfers to supported mobile wallets, bank accounts, and cash-pickup partners
  * Added transaction tracking endpoints: `GET /api/remittance/transactions`, `GET /api/remittance/transactions/:transactionId`, and `GET /api/remittance/transactions/:transactionId/status`
  * Added `POST /api/remittance/transactions/:transactionId/cancel` for eligible pending and uncollected cash-pickup transfers
  * Documented rail-specific recipient fields, corridor and bank routing data, amount limits, purpose-of-transfer codes, source-of-funds codes, and sender KYC requirements
  * Documented indicative quote expiry, fee deduction, destination currency precision, and provider-neutral rate fields including `destinationRateTimestamp`
  * Documented durable send idempotency, safe retry behaviour, wallet debit timing, asynchronous submission, and the `pending` → `submitted` → `processing` lifecycle
  * Documented terminal and recovery states (`completed`, `failed`, `cancelled`, `refunded`, `cash_pickup_ready`), customer cancellation eligibility, voucher handling, and provider-neutral `networkStatusCode`
  * Added remittance endpoints to the protected endpoint summary and bumped the public API document version to 1.15
* 2026-07-09: v1.14 — KYC verification (production implementation)
  * **Breaking (for tenants with `validateKyc=true`)**: KYC submissions now receive verification decisions (Approved/Rejected/Pending)
  * Verification checks the user's identity, identity document and proof of residence, and runs compliance screening
  * Verification returns approved, rejected (with `rejectionReason`) or held for review
  * Each verification now records its decision ("Approved"/"Rejected"/"Pending"), the rejection reason, and an audit reference under `syncDetails.kycValidation`
  * New callback flow: verified users now correctly emit `kyc.approved` / `kyc.rejected` callbacks to tenant webhook endpoints
  * Card upgrade KYC: `isCardUpgrade=true` writes to `kycDetails.cardKycStatus` (separate from base wallet KYC `kycDetails.status`)
  * Bumped public API doc version to 1.14
* 2026-06-29: v1.13 — Pay@ deposit + withdrawal API
  * New endpoint `POST /api/wallet/deposit/payat` — initiate a Pay@ deposit (top-up).

Returns payment links (card, EFT, QR), a Snapscan/Masterpass/Zapper-compatible QR code, and the user's stable 18-digit account number, scannable at Pick n Pay

* New endpoint `POST /api/wallet/withdrawal/payat` — issue a single-use Pay@ OUT cash-at-till PIN.

Plaintext PIN returned in response; tenants are responsible for secure delivery to their user

* New endpoint `GET /api/payat/account/:userId` — look up a user's stable deposit (prefix `13013`) and payout (prefix `13044`) account numbers (corrected in v1.81: both use `13044`)
* New endpoint `GET /api/payat/transactions?userId=...` — paginated deposit transaction history with optional `status` / `referenceKey` filters
* New endpoint `GET /api/payat/transactions/:id` — single deposit transaction detail
* New endpoint `GET /api/payat/withdrawal/status/:withdrawalRequestId` — payout PIN lifecycle status (never returns the plaintext PIN)
* New endpoint `GET /api/payat/withdrawal/list/:userId` — paginated withdrawal-PIN history
* New error types: `PAYOUT_PIN_ALREADY_ISSUED` (409), `PAYOUT_PIN_NOT_FOUND` (404), `PAYOUT_AMOUNT_OUT_OF_RANGE` (422), `BELOW_MINIMUM_AMOUNT` (422), `EXCEEDS_MAXIMUM_AMOUNT` (422)
* New section **Pay@ Integration** documenting deposit + withdrawal flows and the PIN-delivery security expectations
* Bumped public API doc version to 1.13
* 2026-06-08: v1.12 — Debt duplicate prevention and audit logs
  * A loan reference can now be used only once per user
  * New `409 DUPLICATE_LOAN_REF` error returned when a duplicate `loan_ref_no` is submitted for the same user
  * New endpoint `GET /api/debt/audit-logs` for paginated debt operation audit trail (ingest, callback, retries)
  * Obligations now report their processing retries in `ittForwardStatus`, `ittForwardAttempts`, and `ittForwardError`
  * Failed processing is retried automatically, up to a configured maximum
  * Debt ingestion now also finds your users that were not created through this API
  * Users are looked up by `clientNo` within your tenant, and a missing `clientNo` is backfilled on first match
  * Bumped public API doc version to 1.12
* 2026-06-04: v1.11 — Email preferences schema overhaul
  * Email preference fields renamed from legacy keys (`deposit`, `trade`, `topup`) to grouped categories: `login`, `deposits`, `withdrawals`, `trades`, `transfers`, `requests`
  * `debtRepayments` and `reversals` removed from user-toggleable preferences — these are now **compulsory** (always-send) notifications
  * New user creation writes the updated 6-key schema; existing users were migrated once to the new keys
  * `openapi.yaml` `EmailPreferences` component updated to reflect new field names
  * Bumped public API doc version to 1.11
* 2026-05-25: v1.10 — Treasury deposit reference lookup
  * New endpoint `GET /api/wallet/:userId/depositRef` returning `{ userId, depositRef }` for the authenticated tenant
  * The deposit reference is generated when the user is created
  * New error: `404 TREASURY_DEPOSIT_REF_NOT_SET` when the user exists but has no deposit reference
  * `404 USER_NOT_FOUND` when the user is not one of your users
  * Bumped public API doc version to 1.10
* 2026-05-25: v1.9 — Signed webhook dispatches (`X-Signature`)
  * Every outbound callback now includes an `X-Signature` header computed over the exact bytes of the request body
  * `hmac-sha256=<hex>` when the tenant has an `hmacSecret` configured (recommended — verifies integrity **and** authenticity)
  * `sha256=<hex>` fallback when no secret is configured (integrity only)
  * New **Signature Verification** section under **Webhooks** with Node.js and shell verification examples, plus constant-time comparison guidance
  * `X-Signature` row added to the **Delivery, Headers & Wire Formats** request-headers table
  * Bumped public API doc version to 1.9
* 2026-05-21: v1.8 — Legacy `debt_repayment_complete` webhook
  * New conditional webhook event `debt_repayment_complete` documented under **Lifecycle / Account Events**, fired after `wallet.repay_debt_completed` for tenants on the legacy debt-repayment flow
  * Endpoint key routing entry added: `debt_repayment_complete` → `debtRepaymentComplete`
  * Payload fields are camelCase (`guid`, `machine`, `clientNo`, `loanRefNo`, `processingStatus`, `replyCd`, `replyStr`, `processedAt`, `amountProcessed`), including the full status enum
  * Silently skipped (no audit failure) when the tenant has not configured a `debtRepaymentComplete` endpoint
  * Bumped public API doc version to 1.8
* 2026-05-21: v1.7 — Comprehensive webhook payload examples
  * **Example Payloads** section in `## Webhooks` expanded to cover all 20 callback events (lifecycle, wallet activity, KYC / wallet / compliance status transitions) with realistic JSON bodies
  * Subsection headings now use **canonical event names**; legacy snake\_case aliases noted under each
  * Added a note clarifying that optional fields are omitted when null (not sent as `null`)
  * New **Idempotency Keys** subsection documenting the four key formats (`{event}:{recordId}`, `{event}:{userId}:{batchId}`, `{event}:{userId}:{timestamp}`, and the `wallet.incoming_credit` variant that includes `{currentBalance}`)
  * Bumped public API doc version to 1.7
* 2026-05-15: v1.6 — FICA validation, corrected webhook payloads, expanded KYC data fields
  * Added **FICA Identity Requirements** section documenting the product/identity type matrix enforced at ingestion time
  * New `identityType` field in KYC Data Fields — validated against `productType` per FICA rules
  * New error: `422 INVALID_FICA_COMBINATION` returned when productType + identityType is invalid
  * **KYC Completion Callback** payload corrected to actual shape: `{ success, account: { spendlUserId, bankAccountNumber, branchCode, bankName, accountHolderName, uniqueDepositReference, currency } }`
  * **KYC Completion Requirements** updated to be FICA-driven (required docs depend on product/identity type)
  * Error envelope now documents optional `data` field for structured validation detail
  * Added **Flat Format Field Mapping** table with all supported flat-format fields and their standard-format equivalents
  * Expanded **KYC Data Fields** with 17 additional fields: `title`, `altEmail`, `idIssue`, `idExpiry`, `identityIssueCountry`, `languageIndicator`, `suitableContactTime`, `residenceIndicator`, `residenceCountry`, `pepPip`, `permitType`, `permitNumber`, `permitIssue`, `permitExpiry`, `addressType`, `residenceStatus`, `intendedPurposeOfAccount`
  * Updated `not_ready` sync status description to include FICA document checks
  * Bumped public API doc version to 1.6
* 2026-05-14: Tenant label enforcement, parameter validation errors returned to client
  * API key `label` field is now required when generating keys
  * Validation errors are now returned in the `error.data` field
  * Requests must use an access token issued for your tenant
* 2026-05-13: Aligned webhook documentation with actual delivery
  * Updated **Debt Obligation Callback** payload to the current `{ success, obligation: { _id, guid, clientNo, loanRefNo, processingStatus, replyCd, replyStr } }` shape (camelCase fields, wrapped envelope)
  * Removed the **Debt Processing Callback** section — this webhook is not currently emitted by the Public API
  * Added a **Delivery, Headers & Wire Formats** section documenting `X-Idempotency-Key`, the `REST`/`RPC`/`FORM` wire formats, and the `NONE`/`BASIC`/`JWT` auth schemes supported per tenant endpoint
  * Bumped public API doc version to 1.5
* 2026-04-01 → 2026-05-12: Durable callback delivery and tenant configuration
  * Replaced synchronous webhook dispatch with durable asynchronous delivery
  * Callbacks retried up to 5 times
  * Tenant endpoint configuration: per-tenant `accountCreation` and `debtObligation` callback URLs
  * Wire format support: `REST` (default), `RPC` (JSON-RPC 2.0 envelope), `FORM` (URL-encoded)
  * Auth scheme support: `NONE`, `BASIC`, `JWT` per tenant endpoint
  * `wireFormatOverride` per event — KYC callbacks always delivered as plain REST regardless of tenant default
  * `X-Idempotency-Key` header sent on all dispatches (stable per logical delivery, reused across retries)
  * Password invite session created at ingestion time; the invite email is sent after registration
  * Treasury reference (`depositRef`) now configured per tenant
* 2026-02-24: Added automated user registration and KYC submission
  * Ingested users are registered and their KYC is submitted on a schedule
  * Added `syncDetails` to the user record to track registration and KYC submission status
* 2026-02-24: Added debt obligation ingestion
  * Debt obligations are idempotent by `guid`
  * New routes: `POST /api/debt/ingest`, `GET /api/debt/status/:guid`
  * Added a `clientNo` field to users for debt obligation user lookup
  * Each debt obligation is processed and the result is sent to your callback
  * Processing failures are retried automatically
* 2026-01-29: Added tenant and API key attribution for users and KYC uploads
  * Users now include `createdByApiKeyId` and `createdByTenant` fields
  * `kycDetails.s3Keys` changed from a string to an array of upload records with full history
* 2026-01-29: Added KYC document upload endpoint (POST /api/kyc/:userId/:documentType/:category/:filename)
* 2026-01-27: Initial documentation
