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
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 -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"
}'
N/A
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
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 -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" :""
}
}'
{
"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"
}
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
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 -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'
[
{
"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"
}
}
]
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
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 -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 "
}
}'
{
"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": {}
}
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
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
Card API Error Codes
List of error codes specific to Card APIs
Generic Error Codes
List of general error codes across fusion
Card APIs
Order new cards, change PIN, get payment details
Card Lifecycle
An introduction to the key concepts around Card Lifecycle