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 also 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 CardAllows you to activate a physical card.
Add CardAllows you to issue 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 CardAllows you to assign a physical card (from bulk cards) to an individual customer.
Card DetailsAllows you to retrieve cardholder name
Fetch CVV2 for Virtual CardAllows you to retrieve card expiry date and cvv2 (the values are returned in Base62 encoded).
PIN UpdateAllows you to set an Online PIN on a physical card.
Unmask Virtual CardAllows you to retrieve 16 digits 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.

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"
}

You could 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.

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 is not relevant for physical cards.

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

Assign a Physical Card

๐Ÿ“˜

Info

Please contact your NIUM\u2019s 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 ](/reference/activatecardusingpost) 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

APIs to manage 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 Additional Card(s)

To issue additional card(s) to your customer as a backup-card use case, call Add Card API request.

cardIssuanceAction needs to 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"
}

By using Card Details API, we can see the details of the new card added.

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 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 can see the outcome also 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'

Note 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

You might want to replace a card for your cardholder due to reported cases such as fraud; the card is lost or stolen: the card is damaged.

You only can replace a card using Issue Replacement Card API if the card status is permanently blocked. A permanently blocked card cannot be replaced on the same date as the date of issuance. For example, a customer issued a card today and request to block the card permanently on the same day, such as 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'

NOTE: The cardStatus is 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 is updated 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 is updated from Active to Inactive.
=====

Restriction by Merchant Category

NIUM as a licensed entity has to 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 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.

Steps 1: Block or Unblock

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

The rules:

  • Status = Active and ChannelStrategy = WHITE_LIST, then your customer can do all the transactions at the merchants with the listed MCC, other merchants which are not listed under the list of MCC will be blocked.
  • Status = Active and ChannelStrategy = BLACK_LIST, then your customer cannot do all the transactions at the merchants with the listed MCC, other merchants which are not listed under the list of MCC will be allowed.
  • Either blacklist or whitelist can be enabled at one point in 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

Upon the success of blocking the 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 whitelisted or blacklisted. 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.