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:

`paymentMethod`	Required fields	Optional fields
`BANK` (non-Canada, e.g. DRC)	`accountNumber`, `receiverName`, `institutionName` (bank display name), `institutionCode` (bank code from `/bank/providers`), `accountType`	`narration`
`BANK` (South Africa)	`accountNumber`, `receiverName`, `institutionCode` (bank code from `/bank/providers`), `institutionName`, `accountType`, `purposeOfPayment`, `beneficiary.beneficiaryAddress`, `beneficiary.beneficiaryCity`, `beneficiary.beneficiaryPostCode`	`beneficiary.beneficiaryState`
`BANK` (Canada)	`accountNumber`, `receiverName`, `institutionCode` (institution number), `accountType`, `beneficiary.beneficiaryEmail`	`beneficiary.securityQuestion`, `beneficiary.securityQuestionAnswer`, `beneficiary.transitNumber`, `narration`
`MobileMoney`	`accountNumber` (recipient phone number), `receiverName`, `institutionName` (provider display name), `accountType`	`narration`
`INTERAC`	`receiverName`, `accountType`, `beneficiary.beneficiaryEmail`	`beneficiary.securityQuestion`, `beneficiary.securityQuestionAnswer`
`FASTER_PAYMENTS`	`accountNumber`, `receiverName`, `institutionCode` (sort code, 6 digits), `accountType`	`narration`
`SEPA`	`accountNumber` (IBAN), `receiverName`, `institutionCode` (SWIFT/BIC), `accountType`, `purposeOfPayment`	`narration`
`ACH` (United States)	`accountNumber`, `institutionCode`, `institutionName`, `accountType`, `bankAccountType`, `bankAddress`, `bankCity`, `bankState`, `bankZipCode`, `beneficiary`, `purposeOfPayment`	`narration`
`WIRE` (United States)	`accountNumber`, `institutionName`, `institutionCode`, `accountType`, `bankAccountType`, `beneficiary`, `bankAddress`, `bankCity`, `bankState`, `bankZipCode`, `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",
    "paymentMethod": "MobileMoney",
    "accountType": "INDIVIDUAL",
    "narration": "Family support"
  }'

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": 100.0,
    "sourceCurrency": "USD",
    "destinationCurrency": "KES",
    "receiverName": "Jane Doe",
    "accountNumber": "0712345678",
    "institutionName": "M-Pesa",
    "sourceCountryIsoCode": "NG",
    "destinationCountryIsoCode": "KE",
    "paymentMethod": "MobileMoney",
    "accountType": "INDIVIDUAL",
    "narration": "Family support"
  }'

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": 2.0,
    "sourceCurrency": "USD",
    "destinationCurrency": "CDF",
    "accountNumber": "00444555555",
    "receiverName": "John Doe",
    "institutionName": "Access Bank",
    "institutionCode": "access_bank",
    "sourceCountryIsoCode": "CD",
    "destinationCountryIsoCode": "CD",
    "paymentMethod": "Bank",
    "accountType": "INDIVIDUAL",
    "narration": "Business payment"
  }'

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": 21.0,
    "sourceCurrency": "USD",
    "destinationCurrency": "CAD",
    "receiverName": "Thomas Doe",
    "sourceCountryIsoCode": "CD",
    "destinationCountryIsoCode": "CA",
    "narration": "Ted",
    "paymentMethod": "Interac",
    "accountType": "INDIVIDUAL",
    "lockedExchangeRateId": "01k7pcakf0t8g03rvny3z5mr1p",
    "beneficiary": {
      "beneficiaryEmail": "[email protected]",
      "securityQuestion": "Test",
      "securityQuestionAnswer": "Test"
    }
  }'

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": 2.0,
    "sourceCurrency": "USD",
    "destinationCurrency": "CAD",
    "accountNumber": "234543245433",
    "receiverName": "Jane Doe",
    "institutionCode": "34444",
    "sourceCountryIsoCode": "CD",
    "destinationCountryIsoCode": "CA",
    "paymentMethod": "Bank",
    "accountType": "INDIVIDUAL",
    "lockedExchangeRateId": "01k7pcakf0t8g03rvny3z5mr1p",
    "beneficiary": {
      "beneficiaryEmail": "[email protected]",
      "securityQuestion": "353333"
    }
  }'

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": 23.0,
    "sourceCurrency": "USD",
    "destinationCurrency": "GBP",
    "accountNumber": "404130729909118",
    "receiverName": "Ayodeji Abimbola",
    "institutionCode": "433333",
    "sourceCountryIsoCode": "CD",
    "destinationCountryIsoCode": "GB",
    "narration": "Ted Thomos",
    "paymentMethod": "FASTER_PAYMENTS",
    "accountType": "INDIVIDUAL",
    "lockedExchangeRateId": "01k4a8rfrngw76yfcj3ak1rw71"
  }'

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": 500.0,
    "sourceCurrency": "USD",
    "destinationCurrency": "ZAR",
    "accountNumber": "1234567890",
    "receiverName": "Jane Doe",
    "institutionCode": "2763",
    "institutionName": "Standard Bank",
    "sourceCountryIsoCode": "NG",
    "destinationCountryIsoCode": "ZA",
    "paymentMethod": "Bank",
    "accountType": "INDIVIDUAL",
    "purposeOfPayment": "FAMILY_SUPPORT",
    "beneficiary": {
      "beneficiaryAddress": "123 Main Street",
      "beneficiaryCity": "Cape Town",
      "beneficiaryPostCode": "8001",
      "beneficiaryState": "Western Cape"
    }
  }'

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": 23.0,
    "sourceCurrency": "USD",
    "destinationCurrency": "GBP",
    "accountNumber": "GB41CLJU04130729909118",
    "receiverName": "trfff tttt",
    "institutionCode": "CLJUGB21",
    "sourceCountryIsoCode": "CD",
    "destinationCountryIsoCode": "GB",
    "narration": "Ted",
    "paymentMethod": "SEPA",
    "accountType": "INDIVIDUAL",
    "purposeOfPayment": "MAINTENANCE_EXPENSES",
    "lockedExchangeRateId": "01k4a8rfrngw76yfcj3ak1rw71"
  }'

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": 40.0,
    "sourceCurrency": "USD",
    "destinationCurrency": "USD",
    "accountNumber": "223456789",
    "receiverName": "Daniel Brooks",
    "institutionCode": "021000021",
    "institutionName": "Chase Bank",
    "sourceCountryIsoCode": "CD",
    "destinationCountryIsoCode": "US",
    "paymentMethod": "ACH",
    "accountType": "INDIVIDUAL",
    "bankAccountType": "CHECKING",
    "bankAddress": "123 Financial Street",
    "bankCity": "San Francisco",
    "bankState": "California",
    "bankZipCode": "94105",
    "purposeOfPayment": "MAINTENANCE_EXPENSES",
    "beneficiary": {
      "beneficiaryAddress": "45 Market Road",
      "beneficiaryCity": "Austin",
      "beneficiaryState": "Texas",
      "beneficiaryPostCode": "78701"
    }
  }'

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": 75.0,
    "sourceCurrency": "USD",
    "destinationCurrency": "USD",
    "accountNumber": "987654321",
    "receiverName": "Morgan Blake",
    "institutionCode": "026009593",
    "institutionName": "Bank of America",
    "sourceCountryIsoCode": "CD",
    "destinationCountryIsoCode": "US",
    "paymentMethod": "WIRE",
    "accountType": "CORPORATE",
    "bankAccountType": "SAVINGS",
    "bankAddress": "400 Commerce Avenue",
    "bankCity": "New York",
    "bankState": "New York",
    "bankZipCode": "10001",
    "purposeOfPayment": "SERVICE_CHARGES",
    "beneficiary": {
      "beneficiaryAddress": "10 Business Park",
      "beneficiaryCity": "Dallas",
      "beneficiaryState": "Texas",
      "beneficiaryPostCode": "75201"
    }
  }'

{
  "code": "00",
  "description": "Successful",
  "status": false,
  "data": {
    "wtTransactionId": "01kky197w3xc6wyjenpc5r0tnp",
    "coreTransactionId": "API-FX_TX_DR-08A1B-6add611a-e538-4e67-bcf9-661c77a16804",
    "status": "PROCESSING",
    "coreStatus": "PAYMENT_SUCCESSFUL",
    "type": "TRANSFER",
    "meta": {
      "source_currency": "USD",
      "destination_country": "CD",
      "amount_charged": "255.0",
      "source_amount": "250.0",
      "wt_transaction_id": "01kky197w3xc6wyjenpc5r0tnp",
      "spread_currency": "USD",
      "trade_context": "default",
      "destination_country_name": "Congo DR",
      "source_country": "CD",
      "destination_amount": "250.0",
      "spread_amount": "0.0",
      "narration": "Family support",
      "transactionCategory": "General",
      "payment_destination_type": "Account",
      "trade_side": "BUY",
      "destination_currency": "USD",
      "currency_pair_name": "USD/USD",
      "payment_method": "MobileMoney",
      "tradeType": "FIXED_TRADE"
    },
    "prettyStatus": "Successful"
  }
}

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

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

Show object

string

Recipient email address. Required for INTERAC and BANK (Canada).

string

Security question for Interac e-Transfer.

string

Answer to the security question.

string

Bank transit number (Canada only).

string

Recipient street address. Required for South Africa.

string

Recipient city. Required for South Africa.

string

Recipient postal code. Required for South Africa.

string

Recipient state or province. Optional.

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.

Introduction

Getting Started

Products

API Basics

Guides

Authorize Transfer

Authorize Transfer

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

Payment methods

Request body

Response body

Authorize Transfer

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

​Payment methods

​Request body

​Response body

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

Payment methods

Request body

Response body