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 to get the latest rate for your currency pair. Pass the returned exchangeRateId as lockedExchangeRateId to guarantee that the rate shown to your customer is the rate used to fulfil the transaction.

​
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)narration
BANK (Canada)accountNumber, receiverName, institutionCode (institution number), beneficiary.beneficiaryEmailbeneficiary.securityQuestion, beneficiary.securityQuestionAnswer, beneficiary.transitNumber, narration
MobileMoneyaccountNumber (recipient phone number), receiverName, institutionName (provider display name)narration
INTERACreceiverName, beneficiary.beneficiaryEmailbeneficiary.securityQuestion, beneficiary.securityQuestionAnswer
FASTER_PAYMENTSaccountNumber, receiverName, institutionCode (sort code, 6 digits)accountType (e.g. Individual, Corporate), narration
SEPAaccountNumber (IBAN), receiverName, institutionCode (SWIFT/BIC)accountType (e.g. Individual, Corporate), purposeOfPayment, narration
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",
    "narration": "Family support"
  }'
For DRC transfers, call List Institution Providers first to get valid institutionCode and institutionName values. Use isMobileMoney=true for mobile money providers and isMobileMoney=false for banks.

​
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, EUR, GBP, CAD).
​
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, GB, DE, CA).
​
authCode
string
required
Authorization PIN to confirm the transaction.
​
paymentMethod
string
required
Payment rail to use. One of: BANK, MobileMoney, INTERAC, FASTER_PAYMENTS, SEPA.
​
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
Account type of the recipient. Pass Individual or Corporate. Required by some corridors — optional for FASTER_PAYMENTS and SEPA.
​
purposeOfPayment
string
Reason for the transfer. Optional for most corridors; required by some (e.g., SEPA corporate transfers).
​
narration
string
Description or memo for the transfer.
​
lockedExchangeRateId
string
The exchangeRateId from a prior Fetch Exchange Rates or Convert Money call. Guarantees the transfer is fulfilled at that exact rate regardless of any subsequent market movement.
​
beneficiary
object
Beneficiary details. Required for INTERAC; partially required for BANK (Canada).

​
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.