> ## Documentation Index
> Fetch the complete documentation index at: https://developer.nomba.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authorize Transfer

> Initiate and authorize a cross-border transfer using the Nomba Global Payout API

<Card title="Authorize Transfer" icon="paper-plane" href="/nomba-api-reference/global-payout/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.

<Tip>
  Before calling this endpoint, use [Fetch Exchange Rates](/docs/products/global-payout/fetch-exchange-rates) for cross-currency transfers, then call [Fetch Payment Methods](/docs/products/global-payout/payment-methods) to get required fields and selectable values for `purposeOfPayment`, `accountType`, and `bankAccountType`. [Convert Money](/docs/products/global-payout/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.
</Tip>

## 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`                                                                                                    |

<CodeGroup>
  ```bash MobileMoney (DRC) theme={null}
  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"
    }'
  ```

  ```bash MobileMoney (Africa) theme={null}
  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",
      "authCode": "2580",
      "paymentMethod": "MobileMoney",
      "accountType": "INDIVIDUAL",
      "narration": "Family support"
    }'
  ```

  ```bash BANK (DRC) theme={null}
  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",
      "authCode": "2580",
      "paymentMethod": "Bank",
      "accountType": "INDIVIDUAL",
      "narration": "Business payment"
    }'
  ```

  ```bash INTERAC (Canada) theme={null}
  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",
      "authCode": "2580",
      "narration": "Ted",
      "paymentMethod": "Interac",
      "accountType": "INDIVIDUAL",
      "lockedExchangeRateId": "01k7pcakf0t8g03rvny3z5mr1p",
      "beneficiary": {
        "beneficiaryEmail": "testtt@yahoo.com",
        "securityQuestion": "Test",
        "securityQuestionAnswer": "Test"
      }
    }'
  ```

  ```bash BANK (Canada) theme={null}
  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",
      "authCode": "2580",
      "paymentMethod": "Bank",
      "accountType": "INDIVIDUAL",
      "lockedExchangeRateId": "01k7pcakf0t8g03rvny3z5mr1p",
      "beneficiary": {
        "beneficiaryEmail": "test@yoop.com",
        "securityQuestion": "353333"
      }
    }'
  ```

  ```bash FASTER_PAYMENTS (UK) theme={null}
  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",
      "authCode": "2580",
      "narration": "Ted Thomos",
      "paymentMethod": "FASTER_PAYMENTS",
      "accountType": "INDIVIDUAL",
      "lockedExchangeRateId": "01k4a8rfrngw76yfcj3ak1rw71"
    }'
  ```

  ```bash BANK (South Africa — Individual) theme={null}
  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",
      "authCode": "2580",
      "paymentMethod": "Bank",
      "accountType": "INDIVIDUAL",
      "purposeOfPayment": "FAMILY_SUPPORT",
      "beneficiary": {
        "beneficiaryAddress": "123 Main Street",
        "beneficiaryCity": "Cape Town",
        "beneficiaryPostCode": "8001",
        "beneficiaryState": "Western Cape"
      }
    }'
  ```

  ```bash SEPA (Europe) theme={null}
  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",
      "authCode": "2580",
      "narration": "Ted",
      "paymentMethod": "SEPA",
      "accountType": "INDIVIDUAL",
      "purposeOfPayment": "MAINTENANCE_EXPENSES",
      "lockedExchangeRateId": "01k4a8rfrngw76yfcj3ak1rw71"
    }'
  ```

  ```bash ACH (United States) theme={null}
  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",
      "authCode": "2580",
      "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"
      }
    }'
  ```

  ```bash WIRE (United States) theme={null}
  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",
      "authCode": "2580",
      "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"
      }
    }'
  ```

  ```json Response (MobileMoney DRC) theme={null}
  {
    "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"
    }
  }
  ```
</CodeGroup>

<Note>
  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](/docs/products/global-payout/mobile-money-providers) with `countryIsoCode` set to the destination country to get valid provider codes.
</Note>

<Tip>
  For all mobile money transfers, call [List Institution Providers](/docs/products/global-payout/mobile-money-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.
</Tip>

<Note>
  `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`.
</Note>

<Note>
  `purposeOfPayment` is required for `ACH`, `WIRE`, and `SEPA`. Select it from the `purposeOfPayments` array returned by Fetch Payment Methods; do not send arbitrary text.
</Note>

#### Request body

<ParamField body="amount" type="number" required>
  The amount to transfer in the source currency.
</ParamField>

<ParamField body="sourceCurrency" type="string" required>
  ISO 4217 currency code of the source account (e.g., `USD`).
</ParamField>

<ParamField body="destinationCurrency" type="string" required>
  ISO 4217 currency code of the destination account (e.g., `USD`, `CDF`, `CAD`, `GBP`, `EUR`, `KES`, `ZAR`, `GHS`, `XOF`, `TZS`).
</ParamField>

<ParamField body="receiverName" type="string" required>
  Full name of the recipient.
</ParamField>

<ParamField body="sourceCountryIsoCode" type="string" required>
  ISO 3166-1 alpha-2 country code of the sender (e.g., `CD`).
</ParamField>

<ParamField body="destinationCountryIsoCode" type="string" required>
  ISO 3166-1 alpha-2 country code of the recipient (e.g., `CD`, `CA`, `GB`, `KE`, `ZA`, `GH`, `SN`, `TZ`).
</ParamField>

<ParamField body="authCode" type="string" required>
  Authorization PIN to confirm the transaction.
</ParamField>

<ParamField body="paymentMethod" type="string" required>
  Payment rail to use. One of: `BANK`, `MobileMoney`, `INTERAC`, `FASTER_PAYMENTS`, `SEPA`, `ACH`, `WIRE`.
</ParamField>

<ParamField body="accountNumber" type="string">
  Recipient account number, IBAN, or phone number (for `MobileMoney`). Required for `BANK`, `MobileMoney`, `FASTER_PAYMENTS`, and `SEPA`.
</ParamField>

<ParamField body="institutionCode" type="string">
  Bank or institution routing code. For `BANK` (DRC): bank code from [List Institution Providers](/docs/products/global-payout/mobile-money-providers). For `BANK` (Canada): institution number. For `FASTER_PAYMENTS`: sort code (6 digits). For `SEPA`: SWIFT/BIC code.
</ParamField>

<ParamField body="institutionName" type="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](/docs/products/global-payout/mobile-money-providers).
</ParamField>

<ParamField body="accountType" type="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`.
</ParamField>

<ParamField body="bankAccountType" type="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`.
</ParamField>

<ParamField body="purposeOfPayment" type="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.
</ParamField>

<ParamField body="narration" type="string">
  Description or memo for the transfer.
</ParamField>

<ParamField body="lockedExchangeRateId" type="string">
  Optional locked exchange rate ID from [Convert Money](/docs/products/global-payout/convert-money). Use this when you want to lock the exchange rate and destination amount before authorizing.
</ParamField>

<ParamField body="bankAddress" type="string">
  Bank street address. Required for United States `WIRE`.
</ParamField>

<ParamField body="bankCity" type="string">
  Bank city. Required for United States `WIRE`.
</ParamField>

<ParamField body="bankState" type="string">
  Bank state. Required for United States `WIRE`.
</ParamField>

<ParamField body="bankZipCode" type="string">
  Bank ZIP code. Required for United States `WIRE`.
</ParamField>

<ParamField body="beneficiary" type="object">
  Beneficiary details. Required for `INTERAC`; partially required for `BANK` (Canada and South Africa).

  <Expandable title="object">
    <ParamField body="beneficiaryEmail" type="string">
      Recipient email address. Required for `INTERAC` and `BANK` (Canada).
    </ParamField>

    <ParamField body="securityQuestion" type="string">
      Security question for Interac e-Transfer.
    </ParamField>

    <ParamField body="securityQuestionAnswer" type="string">
      Answer to the security question.
    </ParamField>

    <ParamField body="transitNumber" type="string">
      Bank transit number (Canada only).
    </ParamField>

    <ParamField body="beneficiaryAddress" type="string">
      Recipient street address. Required for South Africa.
    </ParamField>

    <ParamField body="beneficiaryCity" type="string">
      Recipient city. Required for South Africa.
    </ParamField>

    <ParamField body="beneficiaryPostCode" type="string">
      Recipient postal code. Required for South Africa.
    </ParamField>

    <ParamField body="beneficiaryState" type="string">
      Recipient state or province. Optional.
    </ParamField>
  </Expandable>
</ParamField>

#### Response body

<ResponseField name="wtTransactionId" type="string" required>
  Unique GlobalPayout transaction ID. Use this to track the transfer via [Fetch Transaction](/docs/products/global-payout/fetch-transaction).
</ResponseField>

<ResponseField name="coreTransactionId" type="string">
  Internal core transaction reference.
</ResponseField>

<ResponseField name="status" type="string" required>
  Processing status. One of: `PROCESSING`, `COMPLETED`, `FAILED`, `PENDING`.
</ResponseField>

<ResponseField name="coreStatus" type="string">
  Core system status (e.g., `PAYMENT_SUCCESSFUL`).
</ResponseField>

<ResponseField name="type" type="string">
  Transaction type. Will be `TRANSFER` for cross-border disbursements.
</ResponseField>

<ResponseField name="prettyStatus" type="string">
  Human-readable status label (e.g., `Successful`, `Processing`).
</ResponseField>

<ResponseField name="meta" type="object">
  Transaction metadata containing currency details, amounts, and routing info. This is a JSON object — only transaction-relevant fields are present.
</ResponseField>