South Africa Payouts

Use this guide when you want to send ZAR payouts to recipients in South Africa. South Africa supports bank transfers only.

Overview

• Currency: ZAR
• Payment location: ZAF
• Supported rails: Bank transfer
• Payment method: paymentMethodId: "banktransfer", recipient.type: "bank_account"

Required fields (bank transfer)

Top-level required fields for every payout: merchantId, merchantReference, destinationValue (with minorAmount and currency), paymentMethodId, paymentLocation, recipient.

Verify recipient before payout

Recipient bank account validation is not performed as part of the payout request. To reduce failed payouts and confirm account holder details before sending, use Bank Account Verification. You can verify that the account exists, is open, and optionally that the account holder name or identity matches (e.g. South African ID, passport, or business registration).

• When to use: Before creating a ZAR bank payout when you want to confirm the account and optionally match identity.
• How: Call POST /verification/bank-account with the recipient’s accountNumber, bankCode (use a bank code from the table below), country: "ZAF", and your merchantId. Optionally include accountHolder for name/identity matching.
• Result: The API returns whether the account is verified, the account holder name when available, and whether the account is open and accepts credits.

See Bank Account Verification for the full guide and Verification API Reference for the request and response schema.

Beneficiary statement reference

You can pass a beneficiary reference that appears on the recipient’s bank statement. Use the optional top-level field beneficiaryReference (separate from merchantReference). This is useful when you want the recipient to see an invoice number, order ID, or other reference on their statement for reconciliation.

• merchantReference — For your tracking and idempotency; not necessarily shown to the beneficiary.
• beneficiaryReference — Shown on the beneficiary’s statement where supported (ZAR bank payouts).

See Create Payout for the request schema.

Bank codes (South Africa)

For ZAR payouts, use one of the following values in recipient.bankCode. These identify the beneficiary’s bank.

Payout speed

CrissCross supports two clearing options for ZAR bank payouts:

Instant clearing is not supported by all South African banks. When it isn’t available for a given beneficiary bank, CrissCross will process the payout using standard clearing.

To request instant clearing, set clearingType to "instant" in your payout request. Omit clearingType or set it to "standard" for standard clearing. See Create Payout for the full request schema.

Example request

1
{
2
  "merchantId": "your-merchant-id",
3
  "merchantReference": "PAYOUT-ZA-001",
4
  "beneficiaryReference": "INV-2024-0042",
5
  "destinationValue": {
6
    "minorAmount": 250000,
7
    "currency": "ZAR"
8
  },
9
  "paymentMethodId": "banktransfer",
10
  "paymentLocation": "ZAF",
11
  "clearingType": "standard",
12
  "recipient": {
13
    "type": "bank_account",
14
    "accountNumber": "0123456789",
15
    "bankCode": "absa",
16
    "accountHolderName": "Sipho Dlamini",
17
    "country": "ZAF"
18
  }
19
}

• beneficiaryReference is optional; “INV-2024-0042” would appear on the recipient’s bank statement where supported.
• bankCode: "absa" uses the code for Absa Bank; see Bank codes (South Africa) for all supported values.

Use "clearingType": "instant" when you want faster clearing (may incur an additional cost; not supported by all South African banks).

Status and failure behaviour (ZAR)

ZAR payouts use the same CrissCross payout statuses as other destinations: PENDING, PROCESSING, COMPLETED, FAILED, and CANCELLED. The following describes behaviour that is specific to ZAR bank payouts.

Insufficient balance (held, then complete or fail)
If there is insufficient balance in your payout source when a ZAR payout is submitted, the payout may remain in PENDING or PROCESSING until balance is available. Payouts are processed in order (first in, first out). Once the balance is topped up, held payouts can move to COMPLETED. If the balance is not topped up in time, the payout may move to FAILED with a reason in failureReason (e.g. insufficient funds). Ensure sufficient balance before submitting, or top up promptly if you see payouts staying in PENDING/PROCESSING.

Reversals
In rare cases, a payout that has reached COMPLETED can be reversed by the bank (for example, if the beneficiary account was closed). When that happens, you will receive a final status update and the payout will no longer be considered completed—check your payout history and webhooks for the updated status and any reason code.

Cancellation
You can cancel a ZAR payout that has not yet completed. Once cancelled, the payout has status CANCELLED and will not be processed. Cancelling a payout that was held (e.g. due to insufficient balance) can free balance for other payouts. Use the cancel endpoint or contact support as per your integration; see the Payouts API Reference for cancel behaviour if exposed.

For full status definitions and how to track payouts, see Tracking Payouts.

Retries and idempotency (ZAR)

If a ZAR payout request times out or returns an error, retry using the same merchantReference. CrissCross treats the request as idempotent: if the original request was already accepted, a retry with the same reference will not create a duplicate payout.

• Retry with the same merchantReference — Do not generate a new reference on retry; reuse the one from the failed or timed-out request.
• Use exponential backoff — Wait a short time before the first retry (e.g. a few seconds), then increase the delay between subsequent retries to avoid overwhelming the service.

This applies to all payouts but is especially important for ZAR when you rely on idempotency to avoid double sends after timeouts or transient errors.

Sandbox testing (ZAR)

To simulate successful payouts, failures, and held (insufficient balance) scenarios in the sandbox, use the amount and account-number rules described in Sandbox Testing — South Africa (ZAR).

Related guides

• Bank Transfers
• Bank Account Verification
• Tracking Payouts
• Sandbox Testing
• Supported Destinations