Cards

This page includes all the endpoints related to Cards and the walkthrough of processing cards.

The whole section is divided into the below sections to understand the use cases:

Ordering a Card

By default, a customer doesn't have any cards issued. The customer has to order a new card. There are two types of cards available for a customer:

1. Physical: This type of card is a contactless debit card similar to day-to-day use.

2. Virtual: This card type is perfect for online shopping, where you don't need a physical card.

A card is associated with an account, and when the customer is ordering a card, he/she has to select an account from the available ones after agreeing with the card terms and conditions, the order process can be finalised by providing the app PIN.

addCard

Required scopes - cards Enhanced security through pin, password or challenge - as applicable - required, based on jurisdiction and/or client configuration

POST//accounts:8080/v1/cards

Body

application/json

body

accountId*string

cardTypeenum

VIRTUALPHYSICAL

tagstring

Response

201202401403404

Created

Request

JavaScriptCurl

const response = await fetch('//accounts:8080/v1/cards', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "accountId": "text"
    }),
});
const data = await response.json();

Here, the "cardType" can be of two types, as told before "VIRTUAL" or "PHYSICAL". accountId is the account ID number that needs to be passed through, as with that id, the card will be linked.

Lastly, this operation requires the Device Verification process to complete it. The user will have to provide the correct PIN in the header. The header requires the device signature to make the request work. Visit the page to learn how to generate it.

Activating a Card

After ordering a card, you will have to activate it, whether it is a virtual or a physical one. To get the available cards, make a GET Request to the below endpoint:

getCards

Required scopes - cards

GET//accounts:8080/v1/cards

Path parameters

status*enum

status

ACTIVEINACTIVEAWAITING_ACTIVATIONCLOSED

Response

200401403404

OK

Body

application/json

accountIdstring

cardDisplayNamestring

cardProgrammestring

cardRulesarray of string

cardStatusReasonstring

cardTypeenum

VIRTUALPHYSICAL

cvvstring

embossnamestring

expirystring

expiryDatestring

idstring

imageUrlstring

issueDatestring

obscuredCardNumberstring

panstring

partnerProductstring

statusenum

ACTIVEINACTIVEAWAITING_ACTIVATIONCLOSED

tagstring

tokenstring

Request

JavaScriptCurl

const response = await fetch('//accounts:8080/v1/cards', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

[
  {
    "accountId": "text",
    "cardDisplayName": "text",
    "cardProgramme": "text",
    "cardRules": [
      "text"
    ],
    "cardStatusReason": "text",
    "cardType": "VIRTUAL",
    "cvv": "text",
    "embossname": "text",
    "expiry": "text",
    "expiryDate": "text",
    "id": "text",
    "imageUrl": "text",
    "issueDate": "text",
    "obscuredCardNumber": "text",
    "pan": "text",
    "partnerProduct": "text",
    "status": "ACTIVE",
    "tag": "text",
    "token": "text"
  }
]

A successful response will contain the details of available cards. If a card is in "INACTIVE" status, then the status will contain the value "AWAITING_ACTIVATION".

To activate the card, make a PATCH request using the card id to identify the card uniquely. The body will contain the "status" key value to "ACTIVE" to activate the card.

updateCard

Required scopes - cards

PATCH//accounts:8080/v1/cards/{id}

Path parameters

id*string

id

Body

application/json

body

statusenum

ACTIVEINACTIVEAWAITING_ACTIVATIONCLOSED

Response

202204401403

Accepted

Body

application/json

statusstring

Request

JavaScriptCurl

const response = await fetch('//accounts:8080/v1/cards/{id}', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "status": "text"
}

Only provide the "status" key value to activate the card activation request. This request doesn't require the app PIN.

Reset Card Activation Attempts

If there is a problem with the card activation, you may have to reset the number of attempts to activate the card. Make a PATCH request to the following endpoint with the card id to reset the number of card activation attempts:

resetCardActivationAttempts

Required scopes - cards

PATCH//accounts:8080/v1/cards/{id}/reset-activation-attempts

Path parameters

id*string

id

Response

202204401403

Accepted

Body

application/json

statusstring

Request

JavaScriptCurl

const response = await fetch('//accounts:8080/v1/cards/{id}/reset-activation-attempts', {
    method: 'PATCH',
    headers: {},
});
const data = await response.json();

Response

{
  "status": "text"
}

Pause a Card

After activating a card, the user can change the card status to pause or block the card. To set the status of the Card, use the previous PATCH request to set the status of the card.

Blocking a Card

There can be some situations where the card is damaged and not working, or maybe the card has been stolen.

To get the available card blocking reason, make a GET request to the following endpoint:

getCardBlockReasons

Required scopes - cards

GET//accounts:8080/v1/cards/card-block-reasons

Response

200202401403404

OK

Request

JavaScriptCurl

const response = await fetch('//accounts:8080/v1/cards/card-block-reasons', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

For these reasons, the user can block the card with the below DELETE request. The request requires the device signature in the header.

removeCard

Required scopes - cards Required scopes - cards Enhanced security through pin, password or challenge - as applicable - required, based on jurisdiction and/or client configuration

DELETE//accounts:8080/v1/cards/{id}

Path parameters

id*string

id

Body

application/json

body

reasonstring

Response

202204401403

Accepted

Body

application/json

statusstring

Request

JavaScriptCurl

const response = await fetch('//accounts:8080/v1/cards/{id}', {
    method: 'DELETE',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "status": "text"
}

For this request, you have to make sure that a challenge id is available as 'X-AAZZUR-DEVICE-CHALLENGE' and a signature is available as 'X-AAZZUR-SIGNATURE'. To know more about how to generate it, please read through the process available on the Device Verification Page.

Blocking a card will also remove the card from the GET request result of /v1/cards API

Replacing a Card

Replacing a card is almost similar to ordering a new card, but in this one, you have to mention which card you are replacing with the old card id. The body must contain the id of the account that the card is added to. After a successful request, the response will contain the id of the new card.

replaceCard

POST//accounts:8080/v1/cards/{id}/replace

Path parameters

id*string

id

Body

application/json

body

accountId*string

cardTypeenum

VIRTUALPHYSICAL

tagstring

Response

200201401403404

OK

Body

application/json

idstring

Request

JavaScriptCurl

const response = await fetch('//accounts:8080/v1/cards/{id}/replace', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "accountId": "text"
    }),
});
const data = await response.json();

Response

{
  "id": "text"
}

Getting the PIN of a Card

To get the PIN of a card on the account, you have to make a GET request to the /v1/cards/cardId/pin given below. The successful response sends the PIN of the card.

getPin

Required scopes - cards Enhanced security through pin, password or challenge - as applicable - required, based on jurisdiction and/or client configuration

GET//accounts:8080/v1/cards/{id}/pin

Path parameters

id*string

id

Response

200401403404

OK

Body

application/json

pinstring

Request

JavaScriptCurl

const response = await fetch('//accounts:8080/v1/cards/{id}/pin', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "pin": "text"
}

You can also get the PIN of a card by providing the CVV in the body of the request.

getPinWithCvv

Required scopes - cards Enhanced security through pin, password or challenge - as applicable - required, based on jurisdiction and/or client configuration

POST//accounts:8080/v1/cards/{id}/pin

Path parameters

id*string

id

Body

application/json

body

cvvstring

Response

200201401403404

OK

Body

application/json

pinstring

Request

JavaScriptCurl

const response = await fetch('//accounts:8080/v1/cards/{id}/pin', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "pin": "text"
}

Reset PIN

If the user wants to reset the card pin, you have to use the resetPin POST request. The response will contain the request's status if the request is successful.

resetPin

Required scopes - cards

POST//accounts:8080/v1/cards/{id}/pin/reset

Path parameters

id*string

id

Response

201202401403404

Created

Request

JavaScriptCurl

const response = await fetch('//accounts:8080/v1/cards/{id}/pin/reset', {
    method: 'POST',
    headers: {},
});
const data = await response.json();

Create Tag

Users can tag their cards with a name or a nickname to find the card fast. This is useful when the users have multiple cards. To tag a card, make a PATCH request to the below endpoint with the card id:

updateCard

Required scopes - cards

PATCH//accounts:8080/v1/cards/{id}

Path parameters

id*string

id

Body

application/json

body

tagstring

Response

202204401403

Accepted

Body

application/json

statusstring

Request

JavaScriptCurl

const response = await fetch('//accounts:8080/v1/cards/{id}', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "status": "text"
}

Count Rules

When the user makes transactions with the card, it counts as a transaction and the number of counts increases. Users can control the number of card transactions by limiting the number of counts per day or month. Including these two, the user can also limit the amount. To get the available rules that the customer can set on a card, make a GET request on the below endpoint:

getCardRules

Required scopes - cards

GET//accounts:8080/v1/cards/{cardId}/available-rules

Response

200202401403404

OK

Request

JavaScriptCurl

const response = await fetch('//accounts:8080/v1/cards/{cardId}/available-rules', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

A sample response to this request is given below as well. When setting a card rule, you will need the type and the rule value of the below response to set the rule properly.

{
    "rules": [
        {
            "type": "card_max_spend_per_transaction",
            "rule": "card-max-spend-per-transaction",
            "description": "maximum value of one transaction"
        },
        {
            "type": "card_max_spend_per_day",
            "rule": "card-max-spend-per-day",
            "description": "maximum spend amount per day 00:00 to 23:59.999 UTC"
        },
        {
            "type": "card_max_spend_per_week",
            "rule": "card-max-spend-per-week",
            "description": "maximum spend amount per week Monday 00:00 to Sunday 23:59.999 UTC"
        },
        {
            "type": "card_max_spend_per_month",
            "rule": "card-max-spend-per-month",
            "description": "maximum spend amount per first day of month 00:00 to last day of month 23:59.999"
        },
        {
            "type": "card_max_count_per_day",
            "rule": "card-max-count-per-day",
            "description": "maximum transaction count per day 00:00 to 23:59.999 UTC"
        },
        {
            "type": "card_max_count_per_week",
            "rule": "card-max-count-per-week",
            "description": "maximum transaction count per week Monday 00:00 to Sunday 23:59.999 UTC"
        },
        {
            "type": "card_max_count_per_month",
            "rule": "card-max-count-per-month",
            "description": "maximum transaction count per first day of month 00:00 to last day of month 23:59.999"
        }
    ]
}

By default, a card doesn't have any count rules set. So, making a GET request to the below endpoint with the card id will return an empty list.

getRules

Required scopes - cards

GET//accounts:8080/v1/cards/{cardId}/rules

Path parameters

cardId*string

cardId

Response

200202401403404

OK

Request

JavaScriptCurl

const response = await fetch('//accounts:8080/v1/cards/{cardId}/rules', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Setting a Card Rule

You will need the card rule name, type and description to set a card rule. To set a card rule make a POST request to the following endpoint:

createRule

Required scopes - cards

POST//accounts:8080/v1/cards/{cardId}/rules

Path parameters

cardId*string

cardId

Body

application/json

body

body*string

description*string

name*string

type*enum

card_max_spend_per_transactioncard_max_spend_per_daycard_max_spend_per_weekcard_max_spend_per_monthcard_max_count_per_daycard_max_count_per_weekcard_max_count_per_month

Response

201202401403404

Created

Request

JavaScriptCurl

const response = await fetch('//accounts:8080/v1/cards/{cardId}/rules', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "body": "text",
      "name": "text",
      "type": "card_max_spend_per_transaction",
      "description": "text"
    }),
});
const data = await response.json();

Updating a Card Rule

There can be a situation where the user has to update a specific card rule; for example, the user wants to increase or decrease the monthly limit. For this, make a PUT request to the following endpoint with name, body and description. The value will be in the body key. The request also requires you to identify which rule you're updating, so you will need the rule id. You can get the rule id from the getRules endpoint mentioned previously.

updateRule

Required scopes - cards

PUT//accounts:8080/v1/cards/{cardId}/rules/{id}

Path parameters

cardId*string

cardId

id*string

id

Body

application/json

body

bodystring

descriptionstring

namestring

Response

201202401403404

Created

Request

JavaScriptCurl

const response = await fetch('//accounts:8080/v1/cards/{cardId}/rules/{id}', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Deleting a Card Rule

To delete a card rule that is set on a card, make a DELETE request on the following endpoint with the rule id:

deleteRule

Required scopes - cards

DELETE//accounts:8080/v1/cards/{cardId}/rules/{id}

Path parameters

cardId*string

cardId

id*string

id

Response

202204401403

Accepted

Body

application/json

statusstring

Request

JavaScriptCurl

const response = await fetch('//accounts:8080/v1/cards/{cardId}/rules/{id}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Response

{
  "status": "text"
}

Getting Card PIN

You might have to verify the card's PIN when making a transaction. You can retrieve a card's PIN by making a GET request to the below endpoint:

getPin

Required scopes - cards Enhanced security through pin, password or challenge - as applicable - required, based on jurisdiction and/or client configuration

GET//accounts:8080/v1/cards/{id}/pin

Path parameters

id*string

id

Response

200401403404

OK

Body

application/json

pinstring

Request

JavaScriptCurl

const response = await fetch('//accounts:8080/v1/cards/{id}/pin', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "pin": "text"
}

You must pass the account's password in the request's header for this request to work. The key for the password is "X-AAZZUR-PASSWORD".