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. Convert Money is optional; use it only when you want to lock the exchange rate and exact converted amount before authorization, then pass the returned lockedExchangeRateId here.

​
Payment methods

The paymentMethod field determines which additional fields are required:
paymentMethodRequired fieldsOptional fields
BANK (non-Canada, e.g. DRC)accountNumber, receiverName, institutionName (bank display name), institutionCode (bank code from /bank/providers), accountTypenarration
BANK (South Africa)accountNumber, receiverName, institutionCode (bank code from /bank/providers), institutionName, accountType, purposeOfPayment, beneficiary.beneficiaryAddress, beneficiary.beneficiaryCity, beneficiary.beneficiaryPostCodebeneficiary.beneficiaryState
BANK (Canada)accountNumber, receiverName, institutionCode (institution number), accountType, beneficiary.beneficiaryEmailbeneficiary.securityQuestion, beneficiary.securityQuestionAnswer, beneficiary.transitNumber, narration
MobileMoneyaccountNumber (recipient phone number), receiverName, institutionName (provider display name), accountTypenarration
INTERACreceiverName, accountType, beneficiary.beneficiaryEmailbeneficiary.securityQuestion, beneficiary.securityQuestionAnswer
FASTER_PAYMENTSaccountNumber, receiverName, institutionCode (sort code, 6 digits), accountTypenarration
SEPAaccountNumber (IBAN), receiverName, institutionCode (SWIFT/BIC), accountType, purposeOfPaymentnarration
ACH (United States)accountNumber, institutionCode, institutionName, accountType, bankAccountType, bankAddress, bankCity, bankState, bankZipCode, beneficiary, purposeOfPaymentnarration
WIRE (United States)accountNumber, institutionName, institutionCode, accountType, bankAccountType, beneficiary, bankAddress, bankCity, bankState, bankZipCode, purposeOfPaymentnarration
curl --request POST \
  --url https://api.nomba.com/v1/global-payout/transfer/authorize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'accountId: <accountId>' \
  --data '{
    "amount": 250.0,
    "sourceCurrency": "USD",
    "destinationCurrency": "USD",
    "receiverName": "John Cena",
    "accountNumber": "0903086112",
    "institutionName": "Mpesa",
    "sourceCountryIsoCode": "CD",
    "destinationCountryIsoCode": "CD",
    "authCode": "2580",
    "paymentMethod": "MobileMoney",
    "accountType": "INDIVIDUAL",
    "narration": "Family support"
  }'
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

​
amount
number
required
The amount to transfer in the source currency.
​
sourceCurrency
string
required
ISO 4217 currency code of the source account (e.g., USD).
​
destinationCurrency
string
required
ISO 4217 currency code of the destination account (e.g., USD, CDF, CAD, GBP, EUR, KES, ZAR, GHS, XOF, TZS).
​
receiverName
string
required
Full name of the recipient.
​
sourceCountryIsoCode
string
required
ISO 3166-1 alpha-2 country code of the sender (e.g., CD).
​
destinationCountryIsoCode
string
required
ISO 3166-1 alpha-2 country code of the recipient (e.g., CD, CA, GB, KE, ZA, GH, SN, TZ).
​
authCode
string
required
Authorization PIN to confirm the transaction.
​
paymentMethod
string
required
Payment rail to use. One of: BANK, MobileMoney, INTERAC, FASTER_PAYMENTS, SEPA, ACH, WIRE.
​
accountNumber
string
Recipient account number, IBAN, or phone number (for MobileMoney). Required for BANK, MobileMoney, FASTER_PAYMENTS, and SEPA.
​
institutionCode
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.
​
institutionName
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.
​
accountType
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.
​
bankAccountType
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.
​
purposeOfPayment
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.
​
narration
string
Description or memo for the transfer.
​
lockedExchangeRateId
string
Optional locked exchange rate ID from Convert Money. Use this when you want to lock the exchange rate and destination amount before authorizing.
​
bankAddress
string
Bank street address. Required for United States WIRE.
​
bankCity
string
Bank city. Required for United States WIRE.
​
bankState
string
Bank state. Required for United States WIRE.
​
bankZipCode
string
Bank ZIP code. Required for United States WIRE.
​
beneficiary
object
Beneficiary details. Required for INTERAC; partially required for BANK (Canada and South Africa).

​
Response body

​
wtTransactionId
string
required
Unique GlobalPayout transaction ID. Use this to track the transfer via Fetch Transaction.
​
coreTransactionId
string
Internal core transaction reference.
​
status
string
required
Processing status. One of: PROCESSING, COMPLETED, FAILED, PENDING.
​
coreStatus
string
Core system status (e.g., PAYMENT_SUCCESSFUL).
​
type
string
Transaction type. Will be TRANSFER for cross-border disbursements.
​
prettyStatus
string
Human-readable status label (e.g., Successful, Processing).
​
meta
object
Transaction metadata containing currency details, amounts, and routing info. This is a JSON object — only transaction-relevant fields are present.