Switch to dark theme

Switch to light theme

Manage Cards


Fusion provides APIs to manage various attributes of a card. In this article you learn about:

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:

cURL Sample
Switch Theme
Expand More
Copy
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
JSON Sample
Switch Theme
Expand More
Copy
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

cURL Sample
Switch Theme
Expand More
Copy
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
JSON Sample
Switch Theme
Expand More
Copy
{
"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.

cURL Sample
Switch Theme
Expand More
Copy
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
JSON Sample
Switch Theme
Expand More
Copy
[
{
"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.

cURL Sample
Switch Theme
Expand More
Copy
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
JSON Sample
Switch Theme
Expand More
Copy
{
"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 card section.

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.


Related articles