Manage Cards

Before you begin

Before you explore Fusion’s card management APIs, we recommend that you

familiarize yourself with various card related concepts mentioned in Card orders.
study the following illustration for various card related terminologies used in the article:

Reset PIN

Use the /generatePin to reset PIN for a card. A randomly generated 4-digit PIN is sent to the delivery channel (phone, e-mail) provided in the request. You can use the API to generate a new PIN in case the old one is forgotten or exposed.

Endpoint URI

POST/api/v1/ifi/{ifiID}/cards/{cardID}/generatePin

Input parameters

ifiID: Required. Unique identifier of the IFI.
cardID: Required. Unique identifier of the Card for which the PIN is generated
deliveryChannel: Required. Channel where the new PIN is sent to. Allowed values: PHONE, EMAIL. The same delivery channel (Vector) specified during Account Holder creation must be provided.

Form Factor ID, Card ID, and CGUID refer to the same identifier and are used interchangeably in Fusion.

Example

In the following example, the new PIN is generated and sent to Account Holder’s registered phone number:

Request

cURL Sample

curl -X POST 'https://fusion.preprod.zeta.in/api/v1/ifi/140827/cards/8039b47d-0f51-4ae8-ba4a-ff6c187adac0/generatePin' \
-H 'Authorization: {{AUTH_TOKEN}}' \
-H 'Content-Type: application/json' \
--data-raw '{
              "deliveryChannel": "PHONE"
}'

Code Copied

Response

JSON Sample

N/A

Code Copied

Replace card

Before ordering a replacement, delete the old card first.

Order a replacement for the card if it’s stolen, lost, expired, or damaged. A new card order must be created with the old card’s reference number (CRN) when ordering the replacement.

Endpoint URI

POST/api/v1/ifi/{ifiID}/cards/orders/replacement

Input parameters

ifiID: Required. Unique identifier of the IFI.
orderID: Required. Unique identifier for the new card order.
oldCardReferenceNumber: Required. Card Reference Number (CRN) of the card to be replaced.
expiry: Optional. Expiration date for the card. The date will be set according to the formula current Month + Month and current Year+Year. For example, to set May 2023 as the expiration date in April 2020, specify month as 1 and year as 3. The expiration date will be set as 05/2023. If not specified, then month and year from the old card will be considered and the expiration date will be calculated according to the aforementioned formula.
thirdLineEmbossing: Optional. Account Holder’s name displayed on the card. If not specified, the replacement card will be printed with the same data as the old card.
fourthLineEmbossing: Optional. Additional Account Holder details, like company name, displayed on the card. If not specified, the replacement card will be printed with the same data as the old card.
deliveryAddress: Optional. Address where the replacement card should be delivered to. If not specified, the replacement card will be delivered to the same address as the old card.
tenantAttributes: Optional. IFI related information that fintech wants to communicate to the vendor. If not specified, same data as the old card will be sent to the vendor.
vendorAttributes: Optional. Vendor related information like shipping partner, tracking ID, and welcome kit. If not specified, same data as the old card will be sent to the vendor.

Example

In the following example, we replace a card with CRN 193825515652

Request

cURL Sample

curl -X POST 'https://fusion.preprod.zeta.in/api/v1/ifi/140827/cards/orders/replacement' \
-H 'Content-Type: application/json' \
-H 'Authorization: {{AUTH_TOKEN}}' \
--data-raw '{
"orderID": "farzantestOrdr10116",
"oldCardReferenceNumber": "193825515652",
"expiry": {
"month": 4,
"year": 3
},
"thirdLineEmbossing": "Rohit",
"fourthLineEmbossing": "Jospeh",
"deliveryAddress": {
"name": "Rohit Joseph",
"addressLine1": "Directiplex",
"addressLine2": "Near Andheri Subway",
"addressLine3": "Old Nagardas Road",
"addressLine4": "Andheri East",
"city": "Mumbai",
"state": "Maharashtra",
"country": "India",
"postalCode": "400069",
"contactNumber": "+919090909090"
},
"tenantAttributes": {
"corporateName": "",
"corporateID": "",
"templateID": ""
},
"vendorAttributes": {
"consignmentID" :""
}
}'

Code Copied

Response

JSON Sample

{
"quantity": 1,
"orderID": "farzantestOrdr10116",
"cardSkuID": "TEST_FAMPAY_MS",
"plasticCode": "WHITEC",
"expiry": {
"month": 4,
"year": 3
},
"thirdLineEmbossing": "Rohit",
"fourthLineEmbossing": "Jospeh",
"deliveryAddress": {
"name": "Rohit Joseph",
"addressLine1": "Directiplex",
"addressLine2": "Near Andheri Subway",
"addressLine3": "Old Nagardas Road",
"addressLine4": "Andheri East",
"city": "Mumbai",
"state": "Maharashtra",
"country": "India",
"postalCode": "400069",
"contactNumber": "+919090909090"
},
"tenantAttributes": {
"templateID": "",
"corporateID": "",
"corporateName": ""
},
"vendorAttributes": {
"consignmentID": ""
},
"additionalAttributes": {
"oldCrn": "193825515652"
},
"orderStatus": "EMBOSSING_FILE_GENERATED",
"orderedAt": "2020-03-23T10:02:03.526Z"
}

Code Copied

Deactivate card

Deactivating a card will temporarily block the card and all future transactions on it. If you detect suspicious activity on the card, you can deactivate it until the flagged transactions are investigated.

Get Resource and Form Factor details

If you already have the Resource ID and Form Factor ID, skip to the next step.

In Fusion, an Account Holder is mapped to a Resource, and their payment instruments, like card, are represented as Form Factors. To deactivate a card, you must provide the Resource ID and Form Factor ID as path parameters. To fetch these values, call the /cards/list API. The response returns an array of all the cards in the order. cardID provides the value for Form Factor ID, as they are the same and note the Resource ID from URI: resource://{resourceID}.

Form Factor ID, Card ID, and CGUID refer to the same identifier and are used interchangeably in Fusion

Quick tip You can also use the Card Reference Number (CRN) to fetch the Resource ID and Form Factor ID. Use the /cards/{cardCRN} API.

Endpoint URI

POST/api/v1/ifi/{ifiID}/orders/{orderID}/cards/list

Input parameters

ifiID: Required. Unique identifier of the IFI.
orderID: Required. Unique identifier for the card order.

Example

In the following example, we fetch the details of an order which has a single card.

Request

cURL Sample

curl -X GET 'https://fusion.preprod.zeta.in/api/v1/ifi/140827/orders/e8f6e34f-1deb-4e28-84ee-5c4d73dd7364/cards/list' \
-H 'Authorization: {{AUTH_TOKEN}}' \
-H 'Content-Type: application/json'

Code Copied

Response

JSON Sample

[
{
"resource": {
"uri": "resource://a8e27abb-3490-4b4b-9a5f-82de543f8b96",
"attributes": {}
},
"cardID": "f0c1bb24-d800-4024-bd34-67a61aaab588",
"crn": "167635292871",
"cardType": "PHYSICAL",
"maskedPan": "508645-xxxxxx-7335",
"cardStatus": "ENABLED",
"orderDetails": {
"orderID": "e8f6e34f-1deb-4e28-84ee-5c4d73dd7364",
"cardSkuID": "RUPAY_ABC_VBO_PHYSICAL",
"cardSku": {
"cardSkuId": "RUPAY_ABC_VBO_PHYSICAL",
"productID": "201383917079881",
"ifi": "140827",
"bin": "508645",
"plasticCode": "WHITEC",
"vendorID": "SESHAASAI_VBO_FAMPAY",
"tags": [],
"range": "32"
},
"plasticCode": "WHITEC",
"thirdLineEmbossing": "ROHIT",
"fourthLineEmbossing": "JOSEPH",
"expiry": {
"month": "2",
"year": "30"
},
"deliveryAddress": {
"country": "India",
"city": "Mumbai",
"postalCode": "400069",
"contactNumber": "+919090909090",
"addressLine1": "Directiplex",
"addressLine2": "Near Andheri Subway",
"addressLine3": "Old Nagardas Road",
"state": "Maharashtra",
"addressLine4": "Andheri East"
},
"tenantAttributes": {},
"orderStatus": "EMBOSSING_FILE_GENERATED"
},
"tenantAttributes": {},
"binRange": {
"bin": "508645",
"range": "32"
}
}
]

Code Copied

Deactivate cards

To deactivate the card, use the /resources/{resourceID}/form_factors/{formfactorID} API. Provide the resource ID and form factor ID of the card in the path parameter and set the status to INACTIVE in the request body.

Endpoint URI

PATCH/ifi/{ifiID}/resources/{resourceID}/form_factors/{formfactorID}

Input parameters

ifiID: Required. Unique identifier of the IFI.
resourceID: Required. Unique identifier of the Resource to which the card belongs.
formfactorID: Required. Unique identifier of the card to be deactivated. Same as cardID.
status: Required. Status of the card. Allowed values: ACTIVE, INACTIVE, DELETED. Set to INACTIVE to deactivate the card; ACTIVE to activate the card.
code: Optional. Code of the reason for deactivating the card. Allowed values: LOST_OR_STOLEN, DAMAGED, HOTLISTED, OFAC_BLOCKED, OTHER.
description: Optional. Description of the reason for deactivating the card. Length must be less than 200 characters.

Example

In the following example, we deactivate a card after the Account Holder reported unauthorized high-value transactions.

Request

cURL Sample

curl -X PATCH 'https://api.preprod.zeta.in/ifi/140827/resources/36bbdac7-8a11-4d97-8e83-fcac84d7b081/form_factors/c7845612-c10d-4524-beb4-10b834655c47' \
-H 'Content-Type: application/json' \
-H 'Authorization: {{AUTH_TOKEN}}' \
--data-raw '{
"status": "INACTIVE",
"reason": {
"code": "OTHER",
"description": "temporarily deactivated due to suspicious activity "
}
}'

Code Copied

Response

JSON Sample

{
"id": "c7845612-c10d-4524-beb4-10b834655c47",
"ifi": 140827,
"formFactorProductID": "dc3c2d30-7a6a-4714-b1c4-66dc39c2df2b",
"formFactorID": "+919397432115",
"targetURI": "account://71227305-whatMobile2",
"tags": [],
"attributes": {},
"policies": {
"issuancePolicies": [],
"paymentPolicies": []
},
"status": "INACTIVE",
"createdAt": "Mar 19, 2020 7:10:27 PM",
"modifiedAt": "Apr 20, 2020 10:17:23 AM",
"headers": {}
}

Code Copied

Activate card

The same API is used to deactivate and activate the card. Refer to the Deactivate card section and specify the value of the status parameter in the request body to ACTIVE.

Delete card

Deleting a card will block the card and all future transactions on it permanently.

Delete a card if it’s reported stolen, lost, or damaged.

Important To delete a card, specifying the reason (code and description parameters in the request body) is required. To block the card temporarily, deactivate the card.

Get Resource and Form Factor details

If you already have the Resource ID and Form Factor ID, skip to the next step.

To delete a card, you need to provide the card’s resource ID and form factor ID as path parameters. To fetch these values, refer to the Deactivate cardsection.

Delete cards

To delete the card, provide the resource ID and form factor ID of the card and set the status to DELETED in the request body.

Endpoint URI

PATCH/ifi/{ifiID}/resources/{resourceID}/form_factors/{formfactorID}

Input parameters

ifiID: Required. Unique identifier of the IFI.
resourceID: Required. Unique identifier of the Resource to which the card belongs.
formfactorID: Required. Unique identifier of the card to be deactivated. Same as cardID.
status: Required. Status of the card. Allowed values: ACTIVE, INACTIVE, DELETED. Set it to DELETED to delete the card.
code: Required. Code of the reason for deleting the card. Allowed values: LOST_OR_STOLEN, DAMAGED, HOTLISTED, OFAC_BLOCKED, OTHER.
description: Required. Description of the reason for deleting the card. Length must be less than 200 characters.

Important Deleting a card is an irreversible action and hence proceed with caution. All future operations and transactions on the card will be invalid. To allocate a new card, you must create a new card order.

Choose your product

Choose your product

Manage Cards

Reset PIN

Replace card

Deactivate card

Activate card

Delete card

Was this article helpful?