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, 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:

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.

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/n1
• 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.

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.

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

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

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.

Examples

Code example to add a beneficiary:

curl --location --request POST 'https://gateway.nium.com/n1/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/n1/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/n1/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/n1/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"
}'