Send Money (Transfer)

Sending money by using Nium Platform is simple and straightforward with few easy steps.

  1. Ensure the required balance (the amount and the fees, if fees for payout service are configured for your program) is there in the currency in the concerned account holder’s multi-currency wallet.
  2. If a beneficiary is not registered yet, create the beneficiary capturing the beneficiary particulars along with the payout/transfer related details (such as bank details, for example).
  3. Make use of the Lock and Hold FX Rate API function to obtain quote and get a fresh audit_id of the rate quote or make us of an existing audit_id that was fetched for same currency pair and is still valid.
  4. Invoke the transfer money API function by referring to the pre-registered beneficiary and the payout method.

Code sample to add a beneficiary:

curl --location --request POST 'https://apisandbox.spend.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 sample to make use of the Lock and Hold FX Rate API function to obtain quote and get the audit_id of the rate quote:

curl --location --request GET 'https://apisandbox.spend.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 sample to make use of the API function to fetch details for an existing audit_id fetched in the past for same currency pair:

curl -X GET \
'https://apisandbox.spend.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 sample to invoke the transfer money API function by referring to the pre-registered beneficiary and the payout method:

curl --location --request POST 'https://apisandbox.spend.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"
}'

Beneficiary Management

A beneficiary is the recipient to which the customer intends to send money. A beneficiary data object contains two key parts:

  1. Beneficiary’s particulars
  2. Payout method details

Beneficiary Details

Beneficiary Details include the following important details - name, address, contact information, email, account type [Individual or Company], relationship with sender.

Payout Details

Payout details are captured while addition/updation of beneficiary. Payout Details for remittance include the following details - account number, account type, name and country code of the bank, destination currency, payout method, routing code, ID details, etc.

Account Types supported by NIUM for remittance are Current, Saving, Maestra or Checking accounts.

Payout methods supported by NIUM and their meanings are as follows -

Payout MethodDescription
LOCALLocal payout to bank account
SWIFTInternational payout to bank account
WALLETPayout to beneficiary wallet
PROXYPayout to proxies against accounts
CARDPayout to beneficiary Visa card

Nium offers a set of APIs to help collect the right set of data elements to register a beneficiary. Let’s review these APIs now.

  1. Fetch supported corridors API: This API can be used to fetch the list of all supported combinations of currency, payout method and routing code. It can be utilized to check the different supported methods in different corridors.
  2. Beneficiary Validation Schema: This API can be used to fetch the list of all possible beneficiary and payout fields and to understand if these are mandatory or optional in each use case. It can be filtered for any specific payout method.
  3. Search Beneficiary Corridors API(to search for bank/branch codes by using bank name) -
  4. Search Routing Code (using bank name/branch name) API (to identify the bank/branch by using the specific routing code) - This API can be used to fetch the list of all or any specific routing code information based on bank name, currency and other fields. It is useful even if partial information is available such as partial or abbreviated bank name.

Transfer Money and Exchange Rate Management

Money can be transferred to registered beneficiaries using the Transfer Money API by providing essential details such as beneficiary ID, payout id, audit id, amount, purpose code, source of funds etc.

Audit ID

Irrespective of source and destination being same or different, Audit ID is a mandatory requirement in the payout request initiated by clients. All clients are required to call the auto$ API to fetch the Audit ID and include it in the auto$ request.

An Audit ID represents the FX quote between the currency pair that will be applicable for the Payout request initiated with the concerned Audit ID

Every Audit ID generated has a validity that is by default set to 60 minutes for every Client and while initiating the Payout request, clients have to ensure the Audit ID is still valid.

Clients will be allowed to re-use the same Audit ID for multiple payouts requests if requires.

For changing the default locking period of 60 minutes, Clients are requested to reach out to their NIUM representative.

Also to understand the markup that is applied to the FX quote represented by the Audit ID, Clients are advised to refer to the FX_MARKUP as received in the auto$ API in case of locking period set to default - 60 minutes or less than 60 minutes. However in case the locking period set to more than 60 minutes, clients will have to refer to FX_MARKUP_LOCKANDHOLD_1 as received in the auto$ API.

Purpose Code

Purpose code is an important parameter which determines the purpose of each send money transaction. Please refer to the Glossary of Purpose Codes: for the list of possible values.

Transaction lifecycle for a remittance transaction

A remittance transaction is initiated through the Transfer Money. Once a Remittance_Debitor Remittance_Debit_External transaction is initiated, it undergoes transaction monitoring checks in the system. At this stage, the transaction status is PENDING. Transaction Compliance status available in [Transactions API] is IN_PROGRESS.

Once the transaction screening is completed without any flags, the transaction undergoes internal processing through the payment gateway. At this point, the transaction status is still PENDING. Transaction Compliance status is COMPLETED. Remittance lifecycle status at this point would be PG_PROCESSING.

If there are no screening hits and the transaction compliance status is COMPLETED, it is now sent to bank for payout. At this stage, the transaction status is still PENDING. Transaction Compliance status is still COMPLETED. Remittance lifecycle status at this point would be Sent_To_Bank .

The next stage would be completion of the payout. At this stage, the transaction status is now APPROVED. Transaction Compliance status is still COMPLETED. Remittance lifecycle status at this point would be PAID .

In case there are any screening hits, the transaction status would still be PENDING. However, the transaction compliance status would be ACTION_REQUIRED meaning that NIUM compliance team will take action on the transaction.

NIUM compliance team can raise an RFI for the transaction. At this stage, the transaction status would still be PENDING. However, the transaction compliance status would be RFI_REQUESTED . Transaction status is still PENDING. A nudge is triggered on the transaction compliance callback URL described under Compliance Management when the status is changed from ACTION_REQUIRED. This RFI can be responded using the Respond to Transaction RFI API.

In certain cases, the transaction may be rejected as well. Transaction Compliance status is REJECT in this case and the transaction status is DECLINED. Refund is triggered immediately. Please note the interim transaction status of REJECTED in this case till the refund is processed.

Details related to the transaction such as beneficiary details [name, email, mobile, country], payout details [bank name, account number, etc], exchange rate, etc are available as labels in Transactions API.

The entire flow can be summarized as follows: