Transfer Money

Run in Postman

You can transfer or send money to any beneficiary or recipient using Nium and our Transfer Money request. Our transfers resource offers four requests that accept your money transfer order and its details, its request for information (RFI), and its cancellations. Use the Transfer Money requests to process several kinds of transactions, including:

• Business-to-business (B2B)
• Business-to-people (B2P)
• Peer-to-business (P2B)
• Peer-to-peer (P2P) transactions. The payments get disbursed to your beneficiaries' bank accounts, cards, cash flows, and digital wallets.

Beneficiary management

A beneficiary is the recipient of your customer's money. A beneficiary is either an individual or a corporation.

Two key fundamental fields returned during the creation of a beneficiary are the beneficiaryHashId and the payoutHashId. The beneficiaryHashId captures the beneficiary details. The payoutHashId captures the payout method details, such as the bank account number, bank details, destination currency, routing code, etc.

Beneficiary details

The beneficiary details include the name, address, contact information, email address, account type (individual or company), and relationship with the sender.

Payout method details

Payout method details are captured during the addition or update of the beneficiary. Payout details for remittance include account number, account type, name and country code of the bank, destination currency, payout method, routing code, ID details, etc.

The account types supported by Nium for remittance include:

• Saving accounts
• Checking accounts
• Maestra accounts

Nium supports the following payout methods:

Payout method	Description
CARD	Payout to a beneficiary Visa card
CHECK	A local payout to a beneficiary via paper check.
LOCAL	Local payout to a bank account
PROXY	Payout to proxies against accounts
SWIFT	A Society for Worldwide Interbank Financial Telecommunication (SWIFT) international payout to a bank account
WALLET	Payout to a beneficiary wallet

Beneficiary registration information

Nium offers the following API suite to help you collect the right set of data elements to register a beneficiary to transfer money.

HTTP method	API name	Description
GET	Fetch Supported Corridors V2	Fetch the supported corridors for the remittance with details.
GET	Beneficiary Validation Schema V2	Fetch the validation schema for all possible beneficiary and payout validation details.
POST	Search Routing Code (Using Bank Name/Branch Name)	Search bank routing code details.
GET	Search Routing Code Using Bank Name	Search for the beneficiary routing code details using a bank or branch name. Use this API to fetch the list of all or any specific routing code information based on the bank or branch name, currency, and other fields. It's useful even if partial information is available such as a partial or an abbreviated bank name.

Endpoint

Combine one of the following host names with the API resource path from the Transfer Money request to create the URI.

• Sandbox: https://gateway.nium.com
• Production: https://api.spend.nium.com

Supported country and currency

• For a comprehensive breakdown of the countries and corridors that Nium supports, see the Nium Playbook.
• For a list of countries and currencies that are recognized throughout the world, see Currency and country codes.

Transfer Money requests

The Transfer Money suite involves the following requests and endpoints. These requests helps you create a beneficiary, get a currency foreign exchange (FX) quote, and transfer funds.

HTTP method	API name	Action
POST	Add Beneficiary V2	Add a beneficiary to transfer money.
GET	Lock and Hold Foreign Exchange Rate	Lock and hold a foreign exchange rate.
POST	Transfer Money	Send money to a registered beneficiary.
POST	Upload Transaction Receipt	Upload supporting documentation linked to a payment to avoid any compliance delays and enable Nium to process transactions faster.
GET	Fetch Transaction Status	Fetch the currency exchange rate and lock and hold the rates for a certain amo

Add a beneficiary

POST /api/v2/client/{clientHashId}/customer/{customerHashId}/beneficiaries

Use this request to add a beneficiary that you can transfer funds to. Preemptively creating a beneficiary is optional; you can also add beneficiaries as you create payouts.

To use this request, pass the unique client identifier generated and shared before the API handshake. Then, add the unique customer identifier generated when the customer is created. You also need to pass the beneficiary account type and all the fields shown as required in the response data from the Beneficiary Validation Schema V2 request.

Lock and hold foreign exchange rate

GET /api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/lockExchangeRate

Use this API to fetch the foreign exchange rate and lock and hold the rate for a certain amount of time. To execute this operation, pass the unique client identifier generated and shared before the API handshake. Then, add the unique customer identifier and the unique wallet identifier generated simultaneously when the customer is created. You also need to pass the source and destination currency codes and the random X-Request-ID to uniquely identify each request sent through the security channels. This ID is available as one of the parameters in the response headers of the API response object.

Transfer money

POST /api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance

Use this request to create a payout (represented by the remittance resource). You can create a payout either by:

• Using an existing Beneficiary ID:
  • Use the beneficiaryId that is returned in the Add Beneficiary response.
• Including beneficiary details when creating a payout:
  • Instead of using a stored beneficiary, you can also provide the beneficiary and their account details directly within the Transfer Money request body.

Upload transaction receipt

POST /api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/transactions/{transactionId}/receipt

Use this request to upload invoices or supporting documents for a transaction. Uploading a transaction receipt is optional However, adding documentation early helps reduce processing delays and avoids unnecessary compliance reviews.

You can upload a document immediately after creating a transaction with the Transfer Money request. Just use the systemReferenceNumber from the Transfer Money response as the transactionId in this request’s path.

This is especially helpful for transactions flagged for review with Requests for Information (RFIs) or those requiring proof of payment, such as business settlements or cross-border payouts.

Fetch transaction status

GET /api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance/{systemReferenceNumber}/audit

Use this operation to fetch the remittance lifecycle status along with the payment reference number, partner reference number, system reference number, and date and time of the remittance status based on the system reference number provided in the input. To execute this operation, pass the unique client identifier generated and shared before the API handshake. Then, add the unique customer identifier and the unique wallet identifier generated simultaneously when the customer is created. Finally, add the unique system reference number generated by the card issuance platform for the transaction.

note

You can receive webhook events and notifications about the transfer money remittance through your configuration. The only notification that the transfer money operation doesn't support is Short Message Service (SMS) since Nium only sends these through mobile for 3D Secure (3DS) One Time Password (OTP) operations.

Audit ID

You need to pass the Audit ID forex quote between your currency pair regardless of whether they're the same or not. You do this when you initiate the payout request. You also need to call the Exchange Rate Lock And Hold API to fetch the Audit ID and include it in the transfer money request.

The quote currency, commonly known as the counter currency, is the second currency in a direct and indirect currency pair and determines the value of the base currency.

The Audit ID that the system generates for you, so that you can start your payout request, is only valid for 60 minutes by default. You need to make sure it's valid when you perform the operation. You can reuse the same Audit ID for other payout requests. If you want to change the Audit ID's default 60-minute locking period, contact your Nium representative.

Refer to the FX_MARKUP field name key in the Fee Details API to understand the markup applied to the Audit ID forex quote. In case you lock your Audit ID to the 60-minute default period, and you want it to exceed that amount of time, refer to the FX_MARKUP_LOCKANDHOLD_1 field name key.

Upload documents

Minimize delays caused by RFIs by uploading transaction receipts using the Upload Transaction Receipt request.

After initiating a transaction with the Transfer Money retrieve the systemReferenceNumber from the response.

Then, upload the transaction receipt using the Upload Transaction Receipt request - pass the systemReferenceNumber number as the transactionId in the path parameter.

Purpose code

Purpose codes defines the reason for each transfer money transaction. See Purpose Codes for a complete list of possible values.

Creating a transaction

This following explains how to create a transaction and the stages it goes through.

At each stage, if configured, Nium sends a webhook event that updates you on the transaction’s status. For more details, see Notifications and Webhooks.

Step 1: Create a payout

To create a transaction, first create a payout (represented by the remittance resource) using the Transfer Money request.

Step 2: Validate the request body

Nium validates the request body using regex and format checks as described in the Beneficiary Validation Schema v2.

• If validation succeeds, the response returns 200 OK and includes:
  • systemReferenceNumber
  • externalId (if provided)
• If validation fails, the response returns 400 BAD_REQUEST.

At this stage, the transaction status is INITIATED. You can confirm this using the Fetch Transaction Status request.

Step 3: Wallet balance check

Nium checks if the wallet has sufficient funds. Based on the balance, a webhook event is triggered:

• Sufficient balance
• Insufficient balance
• Configuration or limit rejection

Sufficient balance

If sufficient funds are available:

• Nium sends the REMIT_TRANSACTION_INITIATED_WEBHOOK with status IN_PROGRESS.
• The payout is being processed.

Insufficient balance

If insufficient funds are detected:

• Nium sends the REMIT_TRANSACTION_AWAITING_FUNDS webhook event with status AWAITING_FUNDS.
• Add funds to the debited wallet to continue the payout.

If the client does not have Awaiting Funds enabled, Nium rejects the payout and sends the:

• REMIT_TRANSACTION_REJECTED webhook event with status FAILED.
• Add funds to the wallet and create a new payout.

Configuration or limit rejection

If the payout exceeds configured limits or setup is incorrect:

• Nium sends the REMIT_TRANSACTION_REJECTED_WEBHOOK with status FAILED.
• Adjust the payout to meet the configured limits and try again.

Step 4: Sent to bank

Once the payout is forwarded to the local clearing system:

• Nium sends the REMIT_TRANSACTION_SENT_TO_BANK_WEBHOOK webhook with status SENT_TO_BANK or PG_PROCESSING.
• The transactions is being reviewed and processed by the bank.

Step 5: Paid

When the transaction is successfully processed:

• Nium sends the REMIT_TRANSACTION_PAID_WEBHOOK with status PAID.

Additional transaction statuses

Transactions may also encounter the following statuses:

• Returned
• Request for information (RFI)
• Rejected

Returned

If the transaction is returned by the beneficiary's bank:

• Nium sends the REMIT_TRANSACTION_RETURNED_WEBHOOK with status RETURN.

Check the following fields for return reasons:

• errorCode
• errorReasonCode
• errorDescription

For next steps, see Return Codes.

Request for information (RFI)

If compliance review is required:

• The transaction status changes to RFI_REQUESTED.
• Use the Respond to Transaction RFI request to respond.

After responding:

• The transaction status updates to RFI_RESPONDED.

For more information, see Requests for Information.

Rejected

If the transaction is rejected:

• Nium sends the REMIT_TRANSACTION_REJECTED webhook event with status REJECTED.
• A refund is triggered automatically.

Transaction metadata

Use the Fetch Transactions request to retrieve:

• Beneficiary details
• Payout information
• Foreign exchange details

Direct Payout

For detailed descriptions of each status, see the Transaction Lifecycle guide.

Examples

Add a beneficiary

curl --location --request POST 'https://gateway.nium.com/api/v1/client/cc0b9512-a1e6-4464-8abe-2dea2bxxxxxx/customer/056175a0-xxxx-4352-92c8-edf03xxxxxx/beneficiaries' \
--header 'x-api-key: X-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "beneficiaryDetail": {
        "name": "Herwig Ahrendsen",
        "country_code": "DE",
        "account_type": "Individual"
    },
    "payoutDetail": {
        "payout_method": "LOCAL",
        "destination_currency": "EUR",
        "account_type": "Saving",
        "account_number": "DE75512108001245126199",
        "country_code": "DE",
        "routing_code_type_1": "SWIFT",
        "routing_code_value_1": "DEUTDEFF"
    }
}'

Lock and hold exchange rate

curl --location --request GET 'https://gateway.nium.com/api/v1/client/cc0b9512-a1e6-4464-8abe-2dea2bxxxxxx/customer/056175a0-xxxx-4352-92c8-edf03xxxxxx/wallet/bed5d49b-06b2-4d61-b7fd-xxxxx/lockExchangeRate?sourceCurrency=USD&destinationCurrency=AUD' \
--header 'x-api-key: X-API-KEY' 

Example Response

{
    "fx_hold_id": "4597b19f-11a3-49d1-9266-2e36e1679088",
    "source_currency": "USD",
    "destination_currency": "AUD",
    "fx_rate": "1.363500000",
    "markup_rate": "0.000000000",
    "ecb_fx_rate": "0.0",
    "hold_expiry_at": "2021-08-10T01:52:50.101Z",
    "audit_id": 35932
}

Fetch audit details

curl -X GET \
'https://gateway.nium.com/api/v1/{client}/{clientHashId}/{lockExchangeRate}/{auditId}' \
  -H 'x-api-key: 0mZpIhaLVM1qd8IJhCfgjGJDsY7b5pdr00j' \
  -H 'x-request-id: 123e4567-e89b-12d3-a456-426655440000' \
  -H 'x-client-name: client1' 

Example Response

{
   "audit_id":112,
   "source_currency":"USD",
   "destination_currency":"INR",
   "fx_rate":"74.719",
   "markup_rate":"0.000000000",
   "ecb_fx_rate":"0.0",
   "hold_expiry_at":"2021-07-02T10:43:00.514Z",
   "fx_hold_id":"472e130b-ed14-4829-9e6d-81a9d8dce72e",
   "status":"ACTIVE"
}

Transfer money

curl --location --request POST 'https://gateway.nium.com/api/v1/client/cc0b9512-a1e6-4464-8abe-2dea2bxxxxxx/customer/056175a0-xxxx-4352-92c8-edf03xxxxxx/wallet/bed5d49b-06b2-4d61-b7fd-xxxxx/remittance' \
--header 'x-api-key: X-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "beneficiary": {
    "id": "6081219f04fa070017d12e68" //refers to the beneficiary
  },
  "customerComments": "lunch settlement",
  "payout": {
    "audit_id": "35198",
    "payout_id": "6081219f04fa070017d12e69",  //refers to the specific payout method attached to the beneficiary
    "source_amount":10
  },
  "purposeCode": "IR005"
}'

Example Response

{
    "message": "Transfer Accepted",
    "payment_id": null,
    "systemReferenceNumber": "RT1281667885"
}