Transfer Money
Overview
You can transfer or send money to any beneficiary or recipient using a suite of Nium One platform Transfer Money API operations. The service offers four API functions that accept your money transfer order and its details, its request for information (RFI), and its cancellations. It targets business-to-business (B2B), business-to-consumer (B2C), customer-to-customer (C2C), and consumer-to-business (C2B) entities.
Beneficiary management
A beneficiary is the recipient of your customer's money. A beneficiary is either an individual or a business.
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 are current, Saving, Maestra, or checking accounts.
Nium supports the following payout methods:
Payout method | Description |
---|---|
LOCAL | A local payout to a bank account |
SWIFT | A Society for Worldwide Interbank Financial Telecommunication (SWIFT) international payout to a bank account |
WALLET | A payout to a beneficiary wallet |
PROXY | A payout to proxies against accounts |
CARD | A payout to a beneficiary Visa card |
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. |
API URI resources
Combine one of the following host names with the API resource path from the Transfer Money API details section to create the URI.
- Sandbox:
https://gateway.nium.com
- Production:
https://api.spend.nium.com
Supported country and currency
- To see the list of countries and currencies that this API recipe supports, refer to the Currency and country codes guide.
- To see the functionality that this API recipe supports, refer to The Nium Playbook guide.
Transfer Money API endpoints
To use the Transfer Money API recipe, call the following APIs.
HTTP method | API name | Action |
---|---|---|
POST | Add Beneficiary V2 | Add a beneficiary to transfer money. |
GET | Fetch Remittance Life Cycle Status | Fetch the remittance life cycle status and related details. |
POST | Transfer Money | Send money to a registered beneficiary. |
GET | Exchange Rate Lock And Hold | Fetch the currency exchange rate and lock and hold the rates for a certain amo |
Transfer Money API details
The Transfer Money API suite involves the following API URI resource paths. The combined usage of the endpoints helps you check the required balance—the amount and the fees that need to be configured for your program—in the currency of the account holder's multicurrency wallet. The Transfer Money API catalog helps you create a beneficiary, get a currency foreign exchange (forex) quote, and invoke the transfer money function.
Add a beneficiary
URI POST /api/v2/client/{clientHashId}/customer/{customerHashId}/beneficiaries
Use this API to add a beneficiary to transfer funds. To execute this operation, 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 Beneficiary Validation Schema V2 API.
Get the foreign exchange rate
URI 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.
Invoke the transfer money function
URI POST /api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance
Use this API to get the list of all the supported combinations of currency, payout methods, and routing codes. You can use it to check the different supported methods in the different geographic corridors. To execute this operation, pass the unique client identifier generated and shared before the API handshake. Then, pass the destination country code, destination currency code, payout method, customer type, beneficiary account type, and currency routing code.
Get the remittance life cycle status
Use this operation to fetch the remittance life cycle 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 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.
Purpose code
The purpose code determines the reason for each transfer money transaction. Refer to the Purpose of transfer codes glossary for the list of possible values.
Remittance transaction life cycle
Start a remittance transaction through the Transfer Money API. Once a Remittance_Debitor
Remittance_Debit_External
transaction is INITIATED
, the system checks it. At this stage, the transaction status is PENDING
. The transaction compliance status in the Transactions API is IN_PROGRESS
.
When the transaction screening completes without any flags, the payment gateway internally processes it. At this point, the transaction status is PENDING
, its compliance status is COMPLETED
, and its remittance life cycle status is PG_PROCESSING
.
If there are no screening hits, and the transaction compliance status is COMPLETED
, the system sends the transaction to the bank for the payout. At this stage, the transaction status is PENDING
, its compliance status is COMPLETED
, and its remittance life cycle status is Sent_To_Bank
.
During the payout completion stage, the transaction status is APPROVED
, its compliance status is COMPLETED
, and its remittance life cycle status is PAID
.
If there are screening hits, the transaction status is PENDING
and its compliance status is ACTION_REQUIRED
, which means that the Nium compliance team needs to act on the transaction.
The Nium compliance team can raise an RFI for the transaction. At this stage, the transaction status is PENDING
and its transaction compliance status is RFI_REQUESTED
. A nudge is triggered on the transaction compliance callback URL when the status changes from ACTION_REQUIRED
. The Respond to Transaction RFI API answers this call.
In certain cases, the transaction is rejected. The transaction compliance status is REJECT
and its transaction status is DECLINED
. A refund is triggered immediately. The REJECTED
interim transaction status, in this case, remains until the refund is processed.
The transaction details, such as the beneficiary and payout information and its forex, are available as labels in the Transactions API.
Refer to the remittance lifecycle page for detailed descriptions on each of the status.
Examples
Code example to 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"
}
}'
Code example to use the Exchange Rate Lock and Hold API function to obtain a quote and get the rate quote Audit ID:
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'
{
"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
}
Code example to use the API function to fetch details for an existing Audit ID fetched in the past for the same currency pair:
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'
{
"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"
}
Code example to invoke the Transfer Money API function by referring to the preregistered beneficiary and the payout method:
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"
}'
Updated 5 months ago