API Overview

NIUM provides card issuance platform to any organization working in a business-to-consumer (B2C), customer to customer (C2C), or corporate environment.

With the help of multiple schemes available from NIUM, you can issue branded cards on the Visa or Mastercard network of your choice, including consumer prepaid, commercial prepaid, and platinum cards.

This multi-currency card issuance platform accepts funding in multiple currencies such as – EUR, USD, SGD, and more. The NIUM card can be used for to various transactions at POS terminals, ATM withdrawals, for online purchases, and many more. MasterCard scheme options are also available.

We follow the REST API structure and our setup consists of following entities:

  • Client : The entity which is onboarded in the NIUM card issuance platform and responsible for onboarding and managing cardholders. The client is set-up by NIUM and identified by a UUID called clientHashId.
  • Customer : The individual cardholder onboarded by the client. It is identified by a UUID called customerHashId. A unique identifier walletHashId is also generated and assigned to every onboarded customer. We have different models which may or may not be wallet-based but this unique identifier is generated to keep a consistent API structure.
  • Wallet: In the wallet model, this entity belongs to the customer and can be used to identify the multi-currency wallet using the walletHashId.
  • Card: A customer can have multiple cards (Physical, Virtual, and Virtual Upgrade to Physical) issued for use. Every card is uniquely identified by a UUID called cardHashId.


API header requirements

A 36-character UUID should be sent in the header as x-request-id for every request. A client name(maximum length of 32 characters) of your choosing should also be sent in the header as x-client-name with every request. It is necessary to provide this value while raising a support query. NIUM also supports Static Header with Remote Host Authorization and Webhook requests.


Sandbox maintenance window

Our daily maintenance window will be between 7:00 am - 7:45 am IST.

Validation on Name and Email Fields

The NIUM APIs allow special characters as per OWASP standards.

RegEx for name:

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

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

RegEx for email:

The following RegEx is applicable to email.

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

Standards for currencies and rates

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

  • The transaction amount shall be 10.00 when the currency is USD.
  • The transaction amount shall be 1000 when the currency is JPY.
  • The billing amount shall be 10.00 when the currency is SGD.

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

Database Column Definitions for Amounts and Exchange Rates

  • Amount - NUMERIC(19,4): It will generate the amount in 15.4 format.
  • Rates - NUMERIC(19,9): It will generate rates in 10.9 format.

Validation on Source Currency and Destination Currency

Both the source and destination amounts shall be supported till the last decimal place in the relevant currency. Please refer ISO-4217 for more information, for example:

  • Conversion of USD to SGD, 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.
  • Conversion of JPY to AUD, 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 up is done(half-even up) to the nearest whole number.

List of Country and Currency Codes

Please refer to the Country Code and Currency Code list for an exhaustive description.