Get API Keys

Overview of Cards

Overview

Nium Issuing platform enables you to issue two types of cards:

  • A Virtual Card is a full-function card with a 16-digit number, complete with a card verification number and expiry date, this card act in the same way for an online transaction without the need for a physical card.
  • A Physical Card is the actual piece of plastic issued to a cardholder to spend online and offline. Card is printed with a 16-digit number, complete with a card verification number, expiry date, and scheme name. This card can be personalized to your customer such as display their preferred name or corporate name (for corporate card use case), and it can be issued in bulk without any customer information (however, it is still issued with a full card number, card verification number, and expiry date)

APIs related to card issuance

APIDescription
Activate CardActivate a physical card.
Add CardIssue a new or add-on card to your customer. For the first time, you must issue a card as a NEW card to your customer. You may issue subsequent cards as ADD-ON, linked to the same customer and wallet.
Assign CardAssign a physical card (from bulk cards) to an individual customer.
Card DetailsRetrieve a cardholder name.
Fetch CVV2 for Virtual CardRetrieve the card expiry date and cvv2 (the values are returned in Base62 encoded).
PIN UpdateSet an Online PIN on a physical card.
Unmask Virtual CardRetrieve a 16-digit card number.

📘

Info

NIUM will provide cardHashId for a successful card issuance during Add Card API as a card's unique identifier.

Virtual card

Issue a virtual card

1100

To Issue a Virtual Card, you need to call Add Card API request.

curl --location --request POST 'https://apisandbox.spend.nium.com/api/v1/client/56171ae5-4bcc-4d0c-b204-e2234140f078/customer/59796fed-48d3-4d36-8915-0ff1a83d0bd0/wallet/bdf2865e-a55c-4a5e-b80e-9aeabae904a5/card' \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: QNh7Y3LEMt7bpEEEE1tdfapo7FXXXXXN9JxQW3GB' \
    --data-raw '{
    "cardIssuanceAction": "NEW",
    "demogOverridden": false,
    "cardFeeCurrencyCode": "SGD",
    "cardExpiry": "1122",
    "cardType": "GPR_VIR",
    "logoId": 100,
    "plasticId": 79100110
}'

The platform will add the virtual card (primary GPR_VIR card linked to the wallet).

{
    "cardHashId": "d8cca75b-ebfd-4e50-870b-ab99c94d299a",
    "cardActivationStatus": "VIRTUAL_ACTIVE",
    "maskedCardNumber": "4611-35xx-xxxx-3674"
}

Use the Card List API to view the list of cards linked to the given wallet.

Request

curl --location --request GET 'https://apisandbox.spend.nium.com/api/v1/client/56171ae5-4bcc-4d0c-b204-e2234140f078/customer/59796fed-48d3-4d36-8915-0ff1a83d0bd0/wallet/bdf2865e-a55c-4a5e-b80e-9aeabae904a5/cards' \
    --header 'x-api-key: QNh7Y3LEMt7bpEEEE1tdfapo7FXXXXXN9JxQW3GB'

Response

{
    "totalPages": 1,
    "content": [
        {
            "createdAt": "2021-08-12 00:30:54",
            "updatedAt": "2021-08-12 00:30:54",
            "cardHashId": "d8cca75b-ebfd-4e50-870b-ab99c94d299a",
            "cardType": "GPR_VIR",
            "cardStatus": "VIRTUAL_ACTIVE",
            "maskedCardNumber": "4611-35xx-xxxx-3674",
            "proxyNumber": "0007560010000237202",
            "logoId": "100",
            "plasticId": "79100110",
            "regionCode": "SG",
            "blockReason": null,
            "replacedOn": null,
            "issuanceMode": "NORMAL_DELIVERY_LOCAL",
            "issuanceType": "primaryCard",
            "embossingLine1": "John Smith",
            "embossingLine2": "",
            "firstName": "John",
            "middleName": null,
            "lastName": "Smith",
            "email": "[email protected]",
            "countryCode": "SG",
            "mobile": "81334300",
            "demogOverridden": false,
            "tokens": []
        }
    ],
    "totalElements": 1
}

Issue in both virtual and physical

To Issue the same card information in both physical and virtual card, you need to call Add Card API request indicating cardType as GPR_VIR_UP2PHY.

curl --location --request POST 'https://apisandbox.spend.nium.com/api/v1/client/56171ae5-4bcc-4d0c-b204-e2234140f078/customer/59796fed-48d3-4d36-8915-0ff1a83d0bd0/wallet/bdf2865e-a55c-4a5e-b80e-9aeabae904a5/card' \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: QNh7Y3LEMt7bpEEEE1tdfapo7FXXXXXN9JxQW3GB' \
    --data-raw '{
        "cardIssuanceAction": "NEW",
        "demogOverridden": false,
        "embossingLine1": "Nikola Tesla",
        "cardFeeCurrencyCode": "SGD",
        "cardExpiry": "1122",
        "cardType": "GPR_VIR_UP2PHY",
        "logoId": 100,
        "plasticId": 79100110
    }'

📘

INFO

Cardholder will receive both Virtual Card with VIRTUAL_ACTIVE status, and a physical card will be delivered to the Cardholder's address with INACTIVE Status. You can retrieve virtual card information with both Unmask Virtual Card and Fetch CVV2 for Virtual Card APIs, and the cardholder needs to activate a physical card for card-present transactions.

old way

📘

Info

Cardholder will receive both Virtual Card with VIRTUAL_ACTIVE status, and a physical card will be delivered to the Cardholder's address with INACTIVE Status. You can retrieve virtual card information with both Unmask Virtual Card and Fetch CVV2 for Virtual Card APIs, and the cardholder needs to activate a physical card for card-present transactions.

Display virtual card

1100

Physical card

Nium allows you to issue a physical card with the following options:

  1. Issue a new or additional card to your cardholder, and deliver it to your cardholder’s address
  2. Issue cards in bulk so that you can assign a card to your cardholder instantly

Issue a physical card

1100

To Issue a physical card, you need to call Add Card API request with all required fields and include the following optional fields:

curl --location --request POST 'https://apisandbox.spend.nium.com/api/v1/client/56171ae5-4bcc-4d0c-b204-e2234140f078/customer/ae17e442-a1eb-4121-b03c-8cb42020172c/wallet/171f12c9-57b9-42a8-ba94-6c595255f5b3/card' \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: QNh7Y3LEMt7bpEEEE1tdfapo7FXXXXXN9JxQW3GB' \
    --data-raw '{
        "cardIssuanceAction": "NEW",
        "demogOverridden": false,
        "cardFeeCurrencyCode": "SGD",
        "cardType": "GPR_PHY",
        "logoId": 100,
        "plasticId": 79100110,
        "embossingLine1": "Mother Teresa"
    }'

📘

NOTE

Do not send cardExpiry value since it's not relevant for physical cards.

{
    "cardHashId": "c8c09c83-70ef-4470-ad71-e128d4fdf57b",
    "cardActivationStatus": "INACTIVE",
    "maskedCardNumber": "4611-35xx-xxxx-1663"
}

Assign a physical card

📘

INFO

Contact your Nium account manager to assist you with bulk card issuance.

1100

Once you have received your bulks, you can instantly assign a physical card to our customer through Nium's Portal or Assign Card API.

To assign a physical card to your cardholder, use Assign Card API.

Activate a physical card

📘

Info

All physical card status is always INACTIVE during card creation, and you need to allow your cardholder to activate their card. Additionally, you can also set a card PIN with PIN Update API during the card issuance process as part of your user journey during a physical card creation. For details, see the Set Card PIN flow.

1100

To activate a physical card, you need to call Activate Card API request with a correct pair of customerHashID, walletHashID, and cardHashID

curl --location --request POST 'https://apisandbox.spend.nium.com/api/v1/client/56171ae5-4bcc-4d0c-b204-e2234140f078/customer/ae17e442-a1eb-4121-b03c-8cb42020172c/wallet/171f12c9-57b9-42a8-ba94-6c595255f5b3/card/c8c09c83-70ef-4470-ad71-e128d4fdf57b/activate' \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: QNh7Y3LEMt7bpEEEE1tdfapo7FXXXXXN9JxQW3GB' \
    --data-raw ''

{
    "status": "Active"
}

Manage a card

APIDescription
Block/Unblock CardAllows you to block card temporary and unblock it, or permanently block a card.
Issue Replacement CardAllows you to replace a card.
PIN UpdateAllows you to set an Online PIN on a physical card.

Set a card PIN

To allow your cardholder to start using their card where there is a need for PIN verification, you need to provide your cardholders with their card PIN. To set a card pin, you need to use Set/Reset PIN API.

📘

NOTE

A card PIN needs to be highly secured and should not be shared with other cardholders. Therefore, Nium does not provide a reveal of card PIN.

Every country has its own requirement for the PIN’s length:

CountryPIN Digits
Singapore6
Europe4
Australia4
Hong Kong4

To set a card with PIN, use Set/Reset PIN API and pass BASE64 encoded PIN value. This flow is not applicable for EU/UK. Refer the next section on Offline PIN for EU/UK for more details.

Manage card limit

1100

Issue an additional card

To issue an additional card to your customer as a backup card, call Add Card API request.

cardIssuanceAction must be set with ADD_ON (to indicate that this is an add-on card to an existing primary card).

curl --location --request POST 'https://apisandbox.spend.nium.com/api/v1/client/56171ae5-4bcc-4d0c-b204-e2234140f078/customer/ae17e442-a1eb-4121-b03c-8cb42020172c/wallet/171f12c9-57b9-42a8-ba94-6c595255f5b3/card' \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: QNh7Y3LEMt7bpEEEE1tdfapo7FXXXXXN9JxQW3GB' \
    --data-raw '{
      "cardIssuanceAction": "ADD_ON",
      "demogOverridden": false,
      "cardFeeCurrencyCode": "SGD",
      "cardType": "GPR_PHY",
      "logoId": 100,
      "plasticId": 79100110,
      "embossingLine1": "Mother Teresa",
      "cardHashId": "c8c09c83-70ef-4470-ad71-e128d4fdf57b"
  }'

{
    "cardHashId": "6c23497b-7cb8-4d92-801c-78fd9a73c28d",
    "cardActivationStatus": "INACTIVE",
    "maskedCardNumber": "4611-35xx-xxxx-8277"
}

Use Card Details API to see the details of the newly added card.

curl --location --request GET 'https://apisandbox.spend.nium.com/api/v1/client/56171ae5-4bcc-4d0c-b204-e2234140f078/customer/ae17e442-a1eb-4121-b03c-8cb42020172c/wallet/171f12c9-57b9-42a8-ba94-6c595255f5b3/card/6c23497b-7cb8-4d92-801c-78fd9a73c28d' \
    --header 'x-api-key: QNh7Y3LEMt7bpEEEE1tdfapo7FXXXXXN9JxQW3GB'

Refer to the issuanceType field.

{
    "createdAt": "2021-08-12 00:59:36",
    "updatedAt": "2021-08-12 00:59:36",
    "cardHashId": "6c23497b-7cb8-4d92-801c-78fd9a73c28d",
    "cardType": "GPR_PHY",
    "cardStatus": "INACTIVE",
    "maskedCardNumber": "4611-35xx-xxxx-8277",
    "proxyNumber": "0007560010000237236",
    "logoId": "100",
    "plasticId": "79100110",
    "regionCode": "SG",
    "blockReason": null,
    "replacedOn": null,
    "issuanceMode": "NORMAL_DELIVERY_LOCAL",
    "issuanceType": "additionalCard",
    "embossingLine1": "Mother Teresa",
    "embossingLine2": "",
    "firstName": "John",
    "middleName": "Paul",
    "lastName": "Screening KYC",
    "email": "[email protected]",
    "countryCode": "SG",
    "mobile": "750609097",
    "demogOverridden": false,
    "tokens": []
}

Freeze/Unfreeze a card

You may need to freeze a card as one of the features for your cardholder to manage their card for specific instances. When the card is frozen, the cardholder will not be able to use the card to do any transactions. However, this blocking is only temporary, as the cardholder can unblock/unfreeze the frozen card.

Freeze a card

To freeze a card, use Block/Unblock Cards API with the following fields, and specify temporaryBlock in the blockAction field.

curl --location --request POST 'https://apisandbox.spend.nium.com/api/v1/client/56171ae5-4bcc-4d0c-b204-e2234140f078/customer/ae17e442-a1eb-4121-b03c-8cb42020172c/wallet/171f12c9-57b9-42a8-ba94-6c595255f5b3/card/6c23497b-7cb8-4d92-801c-78fd9a73c28d/cardAction' \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: QNh7Y3LEMt7bpEEEE1tdfapo7FXXXXXN9JxQW3GB' \
    --data-raw '{
        "blockAction": "temporaryBlock"
    }'

{
    "status": "Success"
}

You see the outcome by using Card Details API.

curl --location --request GET 'https://apisandbox.spend.nium.com/api/v1/client/56171ae5-4bcc-4d0c-b204-e2234140f078/customer/ae17e442-a1eb-4121-b03c-8cb42020172c/wallet/171f12c9-57b9-42a8-ba94-6c595255f5b3/card/6c23497b-7cb8-4d92-801c-78fd9a73c28d' \
    --header 'x-api-key: QNh7Y3LEMt7bpEEEE1tdfapo7FXXXXXN9JxQW3GB'

Set the cardStatus value as TEMP_BLOCK

{
    "createdAt": "2021-08-12 00:59:36",
    "updatedAt": "2021-08-12 01:09:26",
    "cardHashId": "6c23497b-7cb8-4d92-801c-78fd9a73c28d",
    "cardType": "GPR_PHY",
    "cardStatus": "TEMP_BLOCK",
    "maskedCardNumber": "4611-35xx-xxxx-8277",
    "proxyNumber": "0007560010000237236",
    "logoId": "100",
    "plasticId": "79100110",
    "regionCode": "SG",
    "blockReason": "",
    "replacedOn": null,
    "issuanceMode": "NORMAL_DELIVERY_LOCAL",
    "issuanceType": "additionalCard",
    "embossingLine1": "Mother Teresa",
    "embossingLine2": "",
    "firstName": "John",
    "middleName": "Paul",
    "lastName": "Screening KYC",
    "email": "[email protected]",
    "countryCode": "SG",
    "mobile": "750609097",
    "demogOverridden": false,
    "tokens": []
}

Unfreeze a card

To unfreeze a card, please use Block/Unblock Cards API and use unblock in the field blockAction field.

curl --location --request POST 'https://apisandbox.spend.nium.com/api/v1/client/56171ae5-4bcc-4d0c-b204-e2234140f078/customer/ae17e442-a1eb-4121-b03c-8cb42020172c/wallet/171f12c9-57b9-42a8-ba94-6c595255f5b3/card/6c23497b-7cb8-4d92-801c-78fd9a73c28d/cardAction' \
    --header 'Content-Type: application/json' \
    --header 'x-api-key: QNh7Y3LEMt7bpEEEE1tdfapo7FXXXXXN9JxQW3GB' \
    --data-raw '{
        "blockAction": "unblock"
    }'

{
    "status": "Success"
}

Replace a card

Cards must be replaced when they are lost, stolen, damaged, or a target of fraud.

You can replace a card using Issue Replacement Card API only if the card status is permanently blocked. A permanently blocked card cannot be replaced on the same date as the date of issuance and such a request will be declined.

To replace a card for your cardholder, you need to use the following APIs.

  1. Block/Unblock Cards
  2. Issue Replacement Card

Step 1: Block card

First, you need to block the old card permanently. To do this, use Block/Unblock Cards API with the following fields:

curl --location --request POST 'https://apisandbox.spend.nium.com/api/v1/client/56171ae5-4bcc-4d0c-b204-e2234140f078/customer/ae17e442-a1eb-4121-b03c-8cb42020172c/wallet/171f12c9-57b9-42a8-ba94-6c595255f5b3/card/6c23497b-7cb8-4d92-801c-78fd9a73c28d/cardAction' \
    --header 'Content-Type: application/json' 
    --header 'x-api-key: QNh7Y3LEMt7bpEEEE1tdfapo7FXXXXXN9JxQW3GB' 
    --data-raw '{
        "blockAction": "permanentBlock",
        "reason": "cardLost"
    }'

{
    "status": "Success"
}

Check the details of the card by using Card Details API:

curl --location --request GET 'https://apisandbox.spend.nium.com/api/v1/client/56171ae5-4bcc-4d0c-b204-e2234140f078/customer/ae17e442-a1eb-4121-b03c-8cb42020172c/wallet/171f12c9-57b9-42a8-ba94-6c595255f5b3/card/6c23497b-7cb8-4d92-801c-78fd9a73c28d' \
--header 'x-api-key: QNh7Y3LEMt7bpEEEE1tdfapo7FXXXXXN9JxQW3GB'

The cardStatus is now P_BLOCK (indicating permanently blocked).

{
    "createdAt": "2021-08-12 00:59:36",
    "updatedAt": "2021-08-12 01:18:12",
    "cardHashId": "6c23497b-7cb8-4d92-801c-78fd9a73c28d",
    "cardType": "GPR_PHY",
    "cardStatus": "P_BLOCK",
    "maskedCardNumber": "4611-35xx-xxxx-8277",
    "proxyNumber": "0007560010000237236",
    "logoId": "100",
    "plasticId": "79100110",
    "regionCode": "SG",
    "blockReason": "|cardLost",
    "replacedOn": null,
    "issuanceMode": "NORMAL_DELIVERY_LOCAL",
    "issuanceType": "additionalCard",
    "embossingLine1": "Mother Teresa",
    "embossingLine2": "",
    "firstName": "John",
    "middleName": "Paul",
    "lastName": "Screening KYC",
    "email": "[email protected]",
    "countryCode": "SG",
    "mobile": "750609097",
    "demogOverridden": false,
    "tokens": []
}

🚧

Warning

The permanent block is an irreversible action. The cardholder will not be able to unblock their card or re-issue a card with the same 16 digit number, card verification number, and expiry date.

Step 2: Replace card

Issue a replacement card to your cardholder. To do this, use Issue Replacement Card API with the following fields:

curl --location --request POST 'https://apisandbox.spend.nium.com/api/v1/client/cc0b9587-a1e6-4464-8abe-2dea2b455817/customer/abd63733-d6a9-4a86-8e6d-b8fea55a6304/wallet/0f2d1c37-062e-416e-95f7-b6e19d48416b/card/8fa47b14-a929-4250-bb7d-5177948c6829/replaceCard' \
--header 'x-api-key: QNh7Y3LEMt7bpEEEE1tdfapo7FXXXXXN9JxQW3GB' \
--header 'Content-Type: application/json' \
--data-raw '{
 "cardFeeCurrencyCode": "SGD"
}'

{
    "cardHashId": "ecd6792f-1224-4f6a-bbc3-2f73fe6a5e63",
    "cardActivationStatus": "INACTIVE",
    "maskedCardNumber": "4611-35xx-xxxx-6697"
}

Next, use Card Details for the replaced card (using the above cardHashId)

curl --location --request GET 'https://apisandbox.spend.nium.com/api/v1/client/cc0b9587-a1e6-4464-8abe-2dea2b455817/customer/abd63733-d6a9-4a86-8e6d-b8fea55a6304/wallet/0f2d1c37-062e-416e-95f7-b6e19d48416b/card/ecd6792f-1224-4f6a-bbc3-2f73fe6a5e63' \
--header 'x-api-key: QNh7Y3LEMt7bpEEEE1tdfapo7FXXXXXN9JxQW3GB'

{
    "createdAt": "2021-08-12 01:26:13",
    "updatedAt": "2021-08-12 01:26:13",
    "cardHashId": "ecd6792f-1224-4f6a-bbc3-2f73fe6a5e63",
    "cardType": "GPR_PHY",
    "cardStatus": "INACTIVE",
    "maskedCardNumber": "4611-35xx-xxxx-6697",
    "proxyNumber": "0007560010000196309",
    "logoId": "100",
    "plasticId": "333666",
    "regionCode": "SG",
    "blockReason": "This card is the replacement of 4611-35xx-xxxx-4973",
    "replacedOn": "12082021",
    "issuanceMode": "BULK_ISSUE_INTERNATIONAL_EU",
    "issuanceType": "replaceCard",
    "embossingLine1": "Jane Doe",
    "embossingLine2": "Alpha Beta Co",
    "firstName": "Jane",
    "middleName": null,
    "lastName": "Doe",
    "email": "[email protected]",
    "countryCode": "SG",
    "mobile": "85285888",
    "demogOverridden": false,
    "tokens": []
}

In the response, the issuanceType indicates that this is a replacement card, and the blockReason field captures some card details of the card that was replaced.

Restriction by transaction channel

With Nium's APIs, you can restrict your customer's purchases at their card-level based for the following transaction channels:

Transaction ChannelDescription
ATMA physical card transaction on an ATM.
NOTE: ATM Balance Inquiry is not supported. For balance inquiry, see Wallet Balance API.
CROSS_BORDERAll card transactions when the purchase is transacted in foreign currency.
IN_STOREAll card-present transactions at the merchant stores need to present a physical card or digital wallet.
MAG_STRIPEAll card-present transactions with a physical card at the merchant stores where the cardholder needs to swipe a physical card on the POS machine.
ONLINEAll card-not-present transactions at the online merchant store where the cardholder must input their card details (16 digit card number, card expiry date, card verification number, and cardholder name).

To restrict transactions at card level for one of the above channels, do the following.

Step 1: Block

You must block one or all the channels by calling Update Channel Restriction with action="BLOCK" and select one of the channels (ATM, CROSS_BORDER, IN_STORE, MAG_STRIPE, ONLINE).

Step 2: Evaluate

Upon the success of blocking the channel, check the result with Get Channel Restriction. This will return the status of all the channels and verify the channel that you have set action="BLOCK" to.

Channel's status updates from Inactive to Active.

Step 3: Unblock

To allow your customer's card to transact in this channel again, unblock the channel restriction. Call Update Channel Restriction on that specific channel with action = 'UNBLOCK'.

The channel's status updates from Active to Inactive.

Restriction by merchant mategory

Nium as a licensed entity must restrict some specific merchant types based on the list given by regulators. Additionally, you also can restrict your customer transactions with additional merchant types (based on the Visa Merchant Category Code https://usa.visa.com/content/dam/VCOM/download/merchants/visa-merchant-data-standards-manual.pdf), such as Airlines, Lodging, F&B merchants.

Step 1: Block or unblock

If your list of allowed merchants is less than the restricted merchants, you can opt-in to allowlist the merchants. Otherwise, denylist the restricted merchants.

The rules:

  • Status = Active and ChannelStrategy = WHITE_LIST (allowlist), then your customer can do all the transactions at the merchants with the listed MCC while merchants not listed under this list will be blocked.
  • Status = Active and ChannelStrategy = BLACK_LIST (denylist), then your customer cannot do any the transactions at the merchants with the listed MCC while merchants not listed under this list will be allowed.
  • Either BLACK_LIST or WHITE_LIST can be enabled at any time.

You need to block one or all the MCC(s) by calling Update MCC Channel Restrictions with the above rules setting.

Step 2: View the MCC restriction list

After blocking a channel, you can view the list of your MCC restriction by calling Get MCC Channel Restrictions. It will return all the MCC lists that have been added to the allowlist or denylist. You will not see the list of MCC codes that have been listed by Nium.

Step 3: Manage the MCC restriction

If you need to change or manage your existing MCC’s restriction. you can always call Update MCC Channel Restrictions on the specific MCC list with the desired status.

Updated 10 days ago