NOnomba

POST /v1/global-payout/transfer/authorize

Changed on

Initiate and authorize a cross-border transfer. Manages the complete transfer lifecycle from initiation to final authorization. Supports BANK, MobileMoney, INTERAC, FASTER_PAYMENTS, SEPA, ACH, and WIRE payment methods.

Request

  • Base URL
    https://api.nomba.com
  • URL
    https://api.nomba.com/v1/global-payout/transfer/authorize
  • Auth
    none declared. Required headers: Authorization, accountId

Headers

Authorizationstring required
Example:Bearer <token>

Bearer token for authentication.

accountIdstring required
Example:890022ce-bae0-45c1-9b9d-ee7872e6ca27

The parent accountId of the business.

Request body

amountnumber required
sourceCurrencystring required
destinationCurrencystring required
receiverNamestring required
sourceCountryIsoCodestring required
destinationCountryIsoCodestring required
paymentMethod'BANK' | 'MobileMoney' | 'INTERAC' | 'FASTER_PAYMENTS' | 'SEPA' | 'ACH' | 'WIRE' required

Payment rail. Determines which additional fields are required. Use Fetch Payment Methods with code or name to get method-specific requirements.

accountNumberstring

Account number, IBAN, or phone number for MobileMoney. Required for BANK, MobileMoney, FASTER_PAYMENTS, SEPA.

institutionCodestring

Routing code. Bank code from /bank/providers for BANK (DRC). Sort code for FASTER_PAYMENTS, SWIFT/BIC for SEPA, institution number for BANK (Canada).

institutionNamestring

Bank or provider display name. Use displayName from List Institution Providers.

accountType'INDIVIDUAL' | 'CORPORATE' required

Required account type of the recipient. Select one of the values returned in accountTypes from Fetch Payment Methods. ACH supports only INDIVIDUAL; WIRE supports INDIVIDUAL and CORPORATE.

bankAccountType'CHECKING' | 'SAVINGS'

Recipient bank account type. Required for ACH and WIRE. Select one of the values returned in bankAccountTypes from Fetch Payment Methods.

purposeOfPaymentstring

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.

narrationstring
lockedExchangeRateIdstring

Optional locked exchange rate ID from Convert Money. Use this when you want to lock the exchange rate and destination amount before authorizing.

idempotencyKeystring

Optional. Your own unique key for this request. Send the same key when retrying and the original transaction is returned instead of a second one being created. A key stays tied to its transaction permanently — use a new key for a new attempt.

bankAddressstring

Bank street address. Required for United States WIRE.

bankCitystring

Bank city. Required for United States WIRE.

bankStatestring

Bank state. Required for United States WIRE.

bankZipCodestring

Bank ZIP code. Required for United States WIRE.

Example request

{
  "amount": 500,
  "sourceCurrency": "USD",
  "destinationCurrency": "USD",
  "receiverName": "John Cena",
  "sourceCountryIsoCode": "CD",
  "destinationCountryIsoCode": "CD",
  "paymentMethod": "MobileMoney",
  "accountNumber": "0903086112",
  "institutionCode": "access_bank",
  "institutionName": "Mpesa",
  "accountType": "INDIVIDUAL",
  "bankAccountType": "CHECKING",
  "purposeOfPayment": "FAMILY_SUPPORT",
  "narration": "Family support",
  "lockedExchangeRateId": "01k7pcakf0t8g03rvny3z5mr1p",
  "idempotencyKey": "5e246f9a-3e79-4b11-92f1-dbd98b53b308",
  "bankAddress": "383 Madison Avenue",
  "bankCity": "New York",
  "bankState": "NY",
  "bankZipCode": "10017",
  "beneficiary": {
    "beneficiaryEmail": "jane.doe@email.com",
    "securityQuestion": "What is your pets name?",
    "securityQuestionAnswer": "Fluffy",
    "beneficiaryAddress": "123 Main Street",
    "beneficiaryCity": "New York",
    "beneficiaryState": "NY",
    "beneficiaryPostCode": "10001"
  }
}

Response

Transfer authorized successfully.

codestring
descriptionstring

Example response

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

Changes

  • 278a25dccfe5Revision changes
    • info

      added the new optional request property

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status