Skip to main content

Authorize Transfer

​
POST /v1/global-payout/transfer/authorize

Manage the complete transfer lifecycle with a single endpoint. AuthTransfer walks you through every required step from initiating a transfer to final authorization, ensuring nothing is missed before funds are moved.
Before calling this endpoint, use Fetch Exchange Rates for cross-currency transfers, then call Fetch Payment Methods to get required fields and selectable values for purposeOfPayment, accountType, and bankAccountType. Optionally use Convert Money to calculate the destination amount. To use the rate quoted to your customer, pass the exchangeRateId returned by Fetch Exchange Rates as lockedExchangeRateId here.

​
Payment methods

The paymentMethod field determines which additional fields are required. Requirements also differ by destination, so the table below is a summary — call Fetch Payment Methods with destinationCountryIsoCode for the exact list your corridor expects.
The MobileMoney (Africa) payload shape applies to all African mobile money corridors. Swap the destination country code, destination currency, account number, and provider institutionName for the recipient’s market. Supported countries: Ghana (GH/GHS), Kenya (KE/KES), Senegal (SN/XOF), Tanzania (TZ/TZS), Ethiopia (ET/ETB), Rwanda (RW/RWF), Uganda (UG/UGX), Cameroon (CM/XAF), Gabon (GA/XAF), Côte d’Ivoire (CI/XOF), Niger (NE/XOF). Call List Institution Providers with countryIsoCode set to the destination country to get valid provider codes.
For all mobile money transfers, call List Institution Providers first to get valid institutionCode and institutionName values for your destination country. Use isMobileMoney=true for mobile money providers and isMobileMoney=false for banks.
accountType is required for Authorize Transfer and must be selected from the accountTypes array returned by Fetch Payment Methods. Valid values are INDIVIDUAL and CORPORATE. ACH supports only INDIVIDUAL; WIRE supports INDIVIDUAL and CORPORATE.
purposeOfPayment is required for ACH, WIRE, and SEPA. Select it from the purposeOfPayments array returned by Fetch Payment Methods; do not send arbitrary text.

​
Request body

​
number
required
The amount to transfer in the source currency.
​
string
required
ISO 4217 currency code of the source account (e.g., USD).
​
string
required
ISO 4217 currency code of the destination account (e.g., USD, CDF, CAD, GBP, EUR, KES, ZAR, GHS, XOF, TZS).
​
string
required
Full name of the recipient.
​
string
required
ISO 3166-1 alpha-2 country code of the sender (e.g., CD).
​
string
required
ISO 3166-1 alpha-2 country code of the recipient (e.g., CD, CA, GB, KE, ZA, GH, SN, TZ).
​
string
required
Payment rail to use. One of: BANK, MobileMoney, INTERAC, FASTER_PAYMENTS, SEPA, ACH, WIRE.
​
string
Recipient account number, IBAN, or phone number (for MobileMoney). Required for BANK, MobileMoney, FASTER_PAYMENTS, and SEPA.
​
string
Bank or institution routing code. For BANK (DRC): bank code from List Institution Providers. For BANK (Canada): institution number. For FASTER_PAYMENTS: sort code (6 digits). For SEPA: SWIFT/BIC code.
​
string
Bank or provider display name. For BANK: the bank display name. For MobileMoney: the provider display name (e.g., Mpesa). Use the displayName from List Institution Providers.
​
string
required
Account type of the recipient. Required for Authorize Transfer. Select one of the values returned in accountTypes from Fetch Payment Methods. Valid values are INDIVIDUAL and CORPORATE; ACH supports only INDIVIDUAL.
​
string
Recipient bank account type. Required for ACH and WIRE. Select one of the values returned in bankAccountTypes from Fetch Payment Methods. Valid values are CHECKING and SAVINGS.
​
string
Reason for the transfer. Required for ACH, WIRE, and SEPA. Select one of the values returned in purposeOfPayments from Fetch Payment Methods; do not send arbitrary text.
​
string
Description or memo for the transfer.
​
string
Optional exchange rate ID from Fetch Exchange Rates. Use this for the transfer to use the rate quoted to your customer.
​
string
Your own unique key for this transfer, up to 128 characters. Send the same key when retrying and you get the original transaction back instead of a second transfer. See Retrying safely.
​
string
Bank street address. Required for United States WIRE.
​
string
Bank city. Required for United States WIRE.
​
string
Bank state. Required for United States WIRE.
​
string
Bank ZIP code. Required for United States WIRE.
​
object
Beneficiary details. Required for INTERAC; partially required for BANK (Canada and South Africa).

​
Response body

​
string
required
Unique GlobalPayout transaction ID. Use this to track the transfer via Fetch Transaction.
​
string
Internal core transaction reference.
​
string
required
Processing status. One of: PROCESSING, COMPLETED, FAILED, PENDING.
​
string
Core system status (e.g., PAYMENT_SUCCESSFUL).
​
string
Transaction type. Will be TRANSFER for cross-border disbursements.
​
string
Human-readable status label (e.g., Successful, Processing).
​
object
Transaction metadata containing currency details, amounts, and routing info. This is a JSON object — only transaction-relevant fields are present.
​
string
The idempotencyKey you sent, echoed back. Empty if you did not send one.
​
boolean
true when this response is a replay of an earlier request with the same key, meaning no new transfer was created. false on the first call.

​
Retrying safely

If a request times out or the connection drops, you cannot tell whether the transfer was created. Retrying blindly risks paying the recipient twice. Send an idempotencyKey to make the retry safe:
The retry returns the original wtTransactionId with idempotentReplay set to true. No second transfer is created. Rules to follow:
  • Generate one key per transfer, reuse it only for retries of that same transfer. A UUID works well.
  • Change anything about the transfer, change the key. Reusing a key with different details returns 409.
  • A failed transfer replays as failed. If the transfer failed downstream, the same key returns that failure — it does not start a new attempt. Fix the problem and send a new key.
  • A replay is not a completion signal. It returns the status as it stands right now, which may still be PROCESSING. Use the webhook for the final outcome.
  • Keys are scoped to your account, and stay tied to their transfer permanently.
This is different from the X-Idempotent-key header used by Transfers. Global Payout takes idempotencyKey in the request body.