Wallet to Wallet Transfers

You can allow a Nium onboarded customer to transfer funds from their wallet to another Nium onboarded customer with a suite of Nium One platform fund transfer APIs, which your customer has authorized to do so.

The sender and the receiver of the funds can be an individual or a business and can belong to the same or a different client setup based on geographic regions. Global clients have multiple client setups on the platform where customers across the client setups require wallet to wallet transfers.

important

To enable wallet to wallet fund transfers across multiple client setups, contact your Nium representative.

Diagram detailing how the Wallet to Wallet Transfers request allows you to send money from one wallet to another wallet in the same or a different client setup based on geographic regions.

Prerequisites

• There are no prerequisites to allow wallet to wallet transfers within the same client setup.
• There are two requirements to allow wallet to wallet transfers between multiple geographic client setups:
  • The client of the sender and the receiver customer needs to have the allowInterClientWalletTransfer flag set to true.
  • At least one common currency needs to be enabled between the different client setups to enable wallet to wallet fund transfers.

API server URLs

Use the following URLs to separate API calls between different environments.

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

API endpoints

HTTP method	API name	Action
POST	Wallet to Wallet Transfer	This API helps you transfer funds from one Nium onboarded customer wallet to another similar wallet.
GET	Transactions	This API allows you to fetch the transaction details for a customer.
GET	Client Transactions	This API allows you to fetch transaction details at the client level. It also supports query parameters based on filtering to fetch details of the transactions for the customer.

Wallet to Wallet Transfer API

The Wallet to Wallet Transfer API allows you to transfer funds in the same currency. The sourceCurrencyCode and destinationCurrencyCode must match.

For cross-currency scenarios, use the Create Conversion API as a separate step alongside the Wallet to Wallet Transfer API:

• The sender uses the Create Conversion API to convert funds to the target currency within their wallet, then uses the Wallet to Wallet Transfer API to send the converted amount to the receiver.
• Alternatively, the sender transfers same-currency funds to the receiver’s wallet, and the receiver then uses the Create Conversion API to convert to their desired currency.

Example request

curl --location --request POST \
  'https://gateway.nium.com/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/transfers' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'x-request-id: YOUR_REQUEST_ID' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "destinationCurrencyCode": "USD",
    "destinationWalletHashId": "DESTINATION_WALLET_HASH_ID",
    "sourceAmount": 100.00,
    "sourceCurrencyCode": "USD",
    "purposeCode": "IR001"
  }'

Example response

{
  "systemReferenceNumber": "NIUM1234567890",
  "status": "SUCCESS",
  "sourceAmount": 100.00,
  "sourceCurrencyCode": "USD",
  "destinationAmount": 100.00,
  "destinationCurrencyCode": "USD"
}

Troubleshooting errors

The following are the common error scenarios in sending an API request for a wallet to wallet transfer.

Error	Description
Either sourceAmount or destinationAmount isn't provided.	Either provide sourceAmount or destinationAmount.
purposeCode is invalid.	The transaction isn't permitted due to an invalid purposeCode, and the Purpose of Transfer Code is provided, such as IR001.
purposeCode isn’t provided.	The transaction isn't permitted because the purposeCode is required.
Receiver’s inter-client transfer flag in client configuration is not true.	The receiver’s client program doesn’t have the permission to receive the funds from that client’s customer through Wallet transfer.
Sender’s inter-client transfer flag in client configuration is not true.	The sender's client program doesn’t have the permission to transfer the funds to that client’s customer through Wallet transfer.
sourceCurrencyCode and destinationCurrencyCode don’t match.	Cross-currency transfers are not allowed. The sourceCurrencyCode and destinationCurrencyCode need to be the same.