API Overview

Nium's open APIs provide functionality to collect, convert, and disburse funds. The APIs also provide capability to onboard customers onto the Nium platform and issue cards.

Nium follows the OpenAPI 3.0 specification for its REST API structure, and its setup consists of the following entities:

  • Client: The client is the entity that onboards into the Nium system. The client is responsible for onboarding and managing their corporate or individual customer. Nium sets up the client entity which is identified by a universally unique identifier (UUID) called the clientHashId.
  • Customer: The client onboards the corporate or individual customer. A UUID called the customerHashId identifies the customer. Nium generates and assigns the onboarded customer a unique identifier, walletHashId. This unique identifier keeps the API structure consistent.
  • Wallet: A wallet belongs to the corporate or individual customer. The walletHashId identifies the multicurrency wallet.
  • Card: A corporate or individual customer can have multiple cards, physical, virtual, and virtual upgrade to physical. The UUID cardHashId uniquely identifies the card instrument.

API header requirements

A 36-character UUID needs to be sent in the API header as x-request-id for every request. A client's name of your choosing needs to also be sent in the API header as x-client-name with every request. The client's name can be up to 32 characters in length. You need to provide this value while raising a support query.

📌

IMPORTANT

Nium's daily sandbox maintenance window is between 7 and 7:45 AM India Standard Time (IST).

Name and email fields validation

Nium APIs allow special characters according to OWASP standards.

Regular expression for name

The following regular expression is applicable to firstName, middleName, lastName, and preferredName.

^[\\p{Alpha}ßẞŒœǿøǾØIJij](([',. -])?[\\p{Alpha}ßẞŒœǿøǾØIJij]*)*$

Regular expression for email

The following regular expression is applicable to email.

^[a-zA-Z0-9!#$%&'*+/=?^_{|}~-]+(?:\\.[a-zA-Z0-9!#$%&'*+/=?^_`` {|}~-]+)*@(?:[a-zA-Z0-9-]+\\.)+[a-zA-Z]{2,}$

Currency and rate standards

The number of digits after the decimal point in any amount depends on the currency. The rounding method is half_even. For example:

  • The transaction amount is $10.00 when the currency is USD.
  • The transaction amount is ¥1000 when the currency is JPY.
  • The billing amount is S$10.00 when the currency is SGD.

All exchange rates and markup rates need to be returned to nine places after the decimal.

Amount and exchange rate database column definitions

  • Amount — numeric (19,4) generates the amount in the 15.4 format.
  • Rates — numeric (19,9) generates rates in the 10.9 format.

Source and destination currency validation

The source and destination amounts are supported until the last decimal place in the relevant currency. Refer to the ISO-4217 standard for more information. See the examples below for more information.

  • In a conversion of USD to SGD, the source amount cannot be less than 0.01 as USD supports two decimal places. Similarly, the destination amount cannot be less than 0.01 as SGD supports two decimal places.
  • In a conversion of JPY to AUD, the source amount cannot be less than 1 as JPY supports zero decimal places. Similarly, the destination amount cannot be less than 0.01 as AUD supports two decimal places.
  • When a remittance transaction is executed with either source or destination currency as IDR, rounding is done half-even up to the nearest whole number.

Currency and country codes

Refer to the Currency and country codes list for an exhaustive description.