- Created by user-5c3b0, last modified by user-e873e on Aug 18, 2020
Order cards for your Account Holders by creating a card order. There are two types of orders you can create on Fusion - Individual card order and Bulk card order. In this article you learn about:
- Individual card order flow
- Bulk card order flow
- Sharing embossing file with vendor
- Checking card order status
- Card delivery
- Cancelling card order
Before you begin
Before you explore Fusion's card order APIs,
- learn various card related functional concepts mentioned in Card Lifecycle.
- remember the various card related terminologies, as illustrated below.
Embossing and embossing file
Embossing is the imprinting of card with various details like card number, name, design, and so on. This process is handled by an external vendor. An embossing file contains all the details
required for printing the card.
A typical embossing file looks like the sample below:
Embossing specification file
An embossing specification file contains the definition and format for the various data fields in the embossing file. This is an additional file shared with the vendor, who uses it to read the data fields and print the card accordingly.
A typical specification file looks like the sample below:
Individual card order flow
This is the primary flow you use to issue cards to your Account Holders individually. The flow consists of the following stages:
- Create card order by creating an Account for the Account Holder.
- Generate embossing file by calling the /dispatch API
- Share embossing file with vendor
The following diagram illustrates the various stages in the Individual card order flow. For a detailed explanation on each status, see Card order statuses.
Create card order
In Individual card order flow, you initiate the order creation when you create an Account for the Account Holder.
Quick tip
You can automate this step by integrating the functionality in your web or mobile application. For example, you can configure your mobile app so that an Account is created for the Account Holder when they apply for a card.
Get Card ID
When you create an Account for Account Holder, Fusion generates a Resource ID
to identify the Account Holder and a Form Factor ID
to identify the card.
Form Factor ID, Card ID, and CGUID refer to the same identifier and are used interchangeably in Fusion.
The /dispatch
API requires Card ID to generate the embossing file. To get this value, use the /cards/list
API and note the cardID
of your card in the response.
Endpoint URI
POST | /api/v1/ifi/{ifiID}/orders/{orderID}/cards/list |
Input parameters
ifiID
: Required. Unique identifier of the IFI.orderID
: Required. Unique identifier of the order which contains the card to be dispatched.
Example
In the following example, we list the card details for an order. The card for which the embossing file is to be generated is identified by cardID
in the response.
Request
Response
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_fintech_PHYSICAL", "cardSku": { "cardSkuId": "RUPAY_ABC_fintech_PHYSICAL", "productID": "201383917079881", "ifi": "140827", "bin": "508645", "plasticCode": "WHITEC", "vendorID": "SESHAASAI_fintech_FAMPAY", "tags": [], "range": "32" }, "plasticCode": "WHITEC", "thirdLineEmbossing": "", "fourthLineEmbossing": "", "expiry": { "month": "2", "year": "30" }, "deliveryAddress": { "country": "IN", "city": "dkwkr", "postalCode": "400050", "contactNumber": "9867962795", "addressLine1": "Test Line 1", "addressLine2": "Test2", "addressLine3": "Test Line 3", "state": "dfejhr", "addressLine4": "Test2" }, "tenantAttributes": {}, "orderStatus": "CARD_DATA_GENERATED" }, "tenantAttributes": {}, "binRange": { "bin": "508645", "range": "32" } } ]
Generate embossing file
Use the card's ID from the previous step and generate the embossing file using the /dispatch
API. In this step, you also specify details like Account Holder's name to be printed on the card, expiry, delivery address, and so on. Fusion creates an order file with a unique identifier, orderID
.
Endpoint URI
POST | /api/v1/ifi/{ifiID}/cards/{cardID}/dispatch |
Input parameters
ifiID
: Required. Unique identifier of the IFI.cardID
: Required. Unique identifier of the card.plasticCode
: Optional. Unique identifier of the design that the card will be printed with. Default value: WHITEC.expiry
: Optional. Expiration date for the card. The date will be set according to the format 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, the expiration date defined in the card SKU will be taken.thirdLineEmbossing
: Optional. Account Holder's name displayed on the card.fourthLineEmbossing
: Optional. Additional Account Holder details, like company name, displayed on the card.deliveryAddress
: Required. Address where the cards should be delivered to.vendorAttributes
: Optional. Miscellaneous information like shipping and welcome kit details that fintech wants to share with the vendor.
Example
In the following example, we dispatch a single card for embossing. The card will be delivered at the address mentioned in the request.
Request
Response
curl -X POST 'https://fusion.preprod.zeta.in/api/v1/ifi/140827/cards/f0c1bb24-d800-4024-bd34-67a61aaab588/dispatch' \ -H 'Content-Type: application/json' \ -H 'Authorization: {{AUTH_TOKEN}}' \ --data-raw '{ "plasticCode": "WHITEC", "thirdLineEmbossing": "Rohit", "fourthLineEmbossing": "Joseph", "deliveryAddress": { "name": "Farzan Shaikh", "addressLine1": "Directiplex", "addressLine2": "Near Andheri Subway", "addressLine3": "Old Nagardas Road", "addressLine4": "Andheri East", "city": "Mumbai", "state": "Maharashtra", "country": "India", "postalCode": "400069", "contactNumber": "+919090909090" }, "vendorAttributes": { "shipping-partner.name": "BLUEDART", "shipping-partner.trackingNumber": "098137643242412312414", "welcome-kit.fullName": "Rohit Joseph", "welcome-kit.qrCode": "c48tn73793cfh93cg24c872t478r4ft3ubdcy8g3cr", "welcome-kit.templateID": "template-id" } }'
{ "quantity": 1, "orderID": "e8f6e34f-1deb-4e28-84ee-5c4d73dd7364", "cardSkuID": "RUPAY_ABC_fintech_PHYSICAL", "plasticCode": "WHITEC", "expiry": { "month": 0, "year": 10 }, "thirdLineEmbossing": "Rohit", "fourthLineEmbossing": "Joseph", "deliveryAddress": { "name": "Farzan Shaikh", "addressLine1": "Directiplex", "addressLine2": "Near Andheri Subway", "addressLine3": "Old Nagardas Road", "addressLine4": "Andheri East", "city": "Mumbai", "state": "Maharashtra", "country": "India", "postalCode": "400069", "contactNumber": "+919090909090" }, "tenantAttributes": {}, "vendorAttributes": { "welcome-kit.qrCode": "c48tn73793cfh93cg24c872t478r4ft3ubdcy8g3cr", "welcome-kit.fullName": "Rohit Joseph", "shipping-partner.name": "BLUEDART", "welcome-kit.templateID": "template-id", "shipping-partner.trackingNumber": "098137643242412312414" }, "additionalAttributes": {}, "orderStatus": "EMBOSSING_FILE_PENDING", "orderedAt": "2020-03-19T16:15:04.131Z" }
To know how the embossing file is shared with the vendor, see Share embossing file with vendor.
Bulk card order flow
A bulk card order allows you to order cards in large quantities. One of the real-world use-cases for bulk orders could be when a corporate wants to provide gift cards to all its employees.
There are two types of bulk card orders that you can create on Fusion - non-personalized and personalized. Each order-type serves different use-cases and requires different APIs to be called. A bulk card order flow consists of the following stages:
- Create non-personalized or personalized bulk card order
- Generate embossing file
- Map card to Account Holder by assigning Form Factor to Resource
- Share embossing file with vendor
The following diagram illustrates the various stages in the Bulk card order flow, complemented with corresponding order statuses. For a detailed explanation on each status, see Card order statuses.
Create personalized card order
Personalized card orders help develop customized cards for RAHs. You can specify different Account Holder details, delivery address, and IFI details for each card. Each card order is identified by a unique identifier, recordID
.
Endpoint URI
POST | /ifi/{ifiID}/cards/orders/personalized |
Input Parameters
ifiID
: Required. Unique identifier of the IFI.orderID
: Required. Unique identifier for the order.quantity
: Required. Number of cards to be ordered.cardSkuID
: Required. Card SKU defines your card's basic attributes like card network, BIN, card-type, embossing vendor details, and so on. Based on the business requirement and agreement, Zeta configures a card SKU for you represented by a unique identifier,cardSkuID
.plasticCode
: Required. Unique identifier of the design that the card will be printed with. Default value: WHITEC.recordID
: Required. Unique identifier for each card in the order.expiry
: Optional. Expiration date for the card. The date will be set according to the format 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, the expiration date defined in the card SKU will be taken by default.thirdLineEmbossing
: Optional. Account Holder's name displayed on the card.fourthLineEmbossing
: Optional. Additional Account Holder details, like company name, displayed on the card.deliveryAddress
: Required. Address where the cards should be delivered to.tenantAttributes
: Optional. IFI related information that fintech wants to communicate to the vendor.vendorAttributes
: Optional. Miscellaneous information like shipping and welcome kit details that fintech wants to share with the vendor.
Example
In the following example, we order 2 cards with different Account Holder details, delivered to different addresses but with same expiration date:
Request
Response
curl -X POST 'https://embossing-gw.preprod.zeta.in/ifi/155616/cards/orders/personalized' \ -H 'Content-Type: application/json' \ -H 'x-zeta-authtoken: {{AUTH_TOKEN}}' \ --data-raw '{ "orderID": "persOrder997", "quantity": 2, "cardSkuID": "RUPAY_ABC_fintech_PHYSICAL", "plasticCode": "WHITEC", "expiry": { "month": 1, "year": 3 }, "records": [ { "recordID": 1, "deliveryAddress": { "name": "John Doe", "addressLine1": "Linkin Road", "addressLine2": "Line2", "addressLine3": "Line3", "addressLine4": "Line4", "city": "Mumbai", "state": "Maharastra", "country": "India", "postalCode": "220022", "contactNumber": "8147832540" }, "thirdLineEmbossing": "John Doe", "fourthLineEmbossing": "XYZ Inc", "tenantAttributes": { } }, { "recordID": 2, "deliveryAddress": { "name": "Jane Johnson", "addressLine1": "MG Road", "addressLine2": "Line2", "addressLine3": "Line3", "addressLine4": "Line4", "city": "Bangalore", "state": "Karnataka", "country": "India", "postalCode": "560095", "contactNumber": "9876567876" }, "thirdLineEmbossing": "Jane Johnson", "fourthLineEmbossing": "ABC Corp", "tenantAttributes": { } } ] }'
{ "orderID": "persOrder997", "quantity": 2, "cardSkuID": "RUPAY_ABC_fintech_PHYSICAL", "expiry": { "month": 1, "year": 3 }, "records": [ { "recordID": 1, "deliveryAddress": { "name": "John Doe", "addressLine1": "Linkin Road", "addressLine2": "Line2", "addressLine3": "Line3", "addressLine4": "Line4", "city": "Mumbai", "state": "Maharastra", "country": "India", "postalCode": "220022", "contactNumber": "8147832540" }, "thirdLineEmbossing": "John Doe", "fourthLineEmbossing": "XYZ Inc", "tenantAttributes": { } }, { "recordID": 2, "deliveryAddress": { "name": "Jane Johnson", "addressLine1": "MG Road", "addressLine2": "Line2", "addressLine3": "Line3", "addressLine4": "Line4", "city": "Bangalore", "state": "Karnataka", "country": "India", "postalCode": "560095", "contactNumber": "9876567876" }, "thirdLineEmbossing": "Jane Johnson", "fourthLineEmbossing": "ABC Corp", "tenantAttributes": { } } ] }
Create non-personalized card order
When you create a non-personalized bulk order, properties like Account Holder details, delivery address, expiration date, and IFI ID for all the cards will be the same. Card number and CVV will be different for each card.
Endpoint URI
POST | /api/v1/ifi/{ifiID}/cards/orders |
Input parameters
ifiID
: Required. Unique identifier of the IFI.quantity
: Required. Number of cards to be ordered.orderID
: Required. Unique identifier for the order.cardSkuID
: Required. Card SKU defines your card's basic attributes like card network, BIN, card-type, embossing vendor details, and so on. Based on the business requirement and agreement, Zeta configures a card SKU for you represented by a unique identifier,cardSkuID
.plasticCode
: Required. Unique identifier of the design that the card will be printed with. Default value: WHITEC.expiry
: Optional. Expiration date for the card. The date will be set according to the format 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, the expiration date defined in the card SKU will be taken.thirdLineEmbossing
: Optional. Account Holder's name displayed on the card.fourthLineEmbossing
: Optional. Additional Account Holder details, like company name, displayed on the card.deliveryAddress
: Required. Address where the cards should be delivered to.tenantAttributes
: Optional. IFI related information that fintech wants to communicate to the vendor.vendorAttributes
: Optional. Miscellaneous information like shipping and welcome kit details that fintech wants to share with vendor.
Quick tip
To order cards with different attributes like Account Holder name and expiration date, create a personalized card order.
Example
In the following example, we order 10 cards with the same expiration date, delivered to the same address and without Account Holder details imprinted on the card:
Request
Response
curl -X POST 'https://fusion.preprod.zeta.in/api/v1/ifi/140827/cards/orders' \ -H 'Authorization: {{AUTH_TOKEN}}' \ --data-raw '{ "quantity": "10", "orderID": "cardorder801", "cardSkuID": "RUPAY_ABC_fintech_PHYSICAL", "plasticCode": "WHITEC", "expiry": { "month": 1, "year": 3, "separator": "/" }, "thirdLineEmbossing": "NA", "fourthLineEmbossing": "NA", "deliveryAddress": { "name": "DirectiPlex", "addressLine1": "Directiplex, Old Nagardas road", "addressLine2": "Andheri (East)", "addressLine3": "Mumbai", "addressLine4": "NA", "city": "Mumbai", "state": "Maharashtra", "country": "India", "postalCode": "400053", "contactNumber": "02228875511" }, "tenantAttributes": { "corporateName": "", "corporateID": "", "templateID": "" }, "vendorAttributes": { "consignmentID": "" } }'
{ "quantity": 10, "orderID": "cardorder801", "cardSkuID": "RUPAY_ABC_fintech_PHYSICAL", "plasticCode": "WHITEC", "expiry": { "month": 1, "year": 3 }, "thirdLineEmbossing": "NA", "fourthLineEmbossing": "NA", "deliveryAddress": { "name": "DirectiPlex", "addressLine1": "Directiplex, Old Nagardas road", "addressLine2": "Andheri (East)", "addressLine3": "Mumbai", "addressLine4": "NA", "city": "Mumbai", "state": "Maharashtra", "country": "India", "postalCode": "400053", "contactNumber": "02228875511" }, "tenantAttributes": { "corporateName": "", "corporateID": "", "templateID": "" }, "vendorAttributes": { "consignmentID": "" } }
Generate embossing files
In bulk order flow, the embossing file is automatically generated during the processing of your card order.
Map card to Account Holder
In Fusion's payment ecosystem, an Account Holder is mapped to a Resource, and their payment instruments, like card, are represented as Form Factors. In bulk order flow, after the card is printed and delivered, it must be mapped to the Account Holder before it's used for any transaction. In Fusion, we call it associating the Form Factor with Resource.
Endpoint URI
POST | /api/v1/ifi/{ifiID}/resources/{resourceID}/form_factors |
Input parameters
ifiID
: Required. Unique identifier of the IFI.resourceID
: Required. Unique identifier of the Resource generated while creating Account for Account Holder.formFactorProductID
: Required. Unique identifier of the Form Factor Product.formFactorID
: Required. Unique identifier of the card. Same asCardID
andCGUID
.targetURI
: Required. Unique identifier of the account generated while creating Account for Account Holder.status
: Required. Current status of the Form Factor. Allowed values: ACTIVE, INACTIVE, DELETED.
Example
Request
Response
curl -X POST 'https://fusion.preprod.zeta.in/api/v1/ifi/140827/resources/3d683159-ce0e-47cd-a95f-c3198199d353/form_factors' \ -H 'Authorization: {{AUTH_TOKEN}}' \ -H 'Content-Type: application/json' \ --data-raw '{ "formFactorProductID": "1533e62d-f114-4cc8-80e9-8a79451d9074", "formFactorID": "ca606cca-7cb3-48e2-8d55-dcb10987a399", "targetURI": "account://71227305-whatMobile2", "status": "ACTIVE" }'
N/A
Share embossing file with vendor
This applies to both individual as well as bulk card order flow.
Embossing file is shared with the vendor by Zeta using cron jobs scheduled to run at 2.30 AM daily. All the embossing files for the day are collected and shared securely with the vendor over SFTP. The files are encrypted using Pretty Good Privacy (PGP) encryption. Public key and private key pairs are shared between Zeta and vendor during the contractual agreement. The public key is used to encrypt the file before sharing, and decrypted by the vendor using the corresponding PGP private key pair.
Check card order status
Card order statuses
Fusion uses statuses to inform you what stage your card order is in. The status also provides additional information regarding order, card data, embossing file, and so on.
- ORDER_PLACED: Card order is successfully placed and order details are received by Fusion's embossing service.
- CARD_REQUEST_GENERATED : Card created with Customer Reference Number (CRN) in Fusion's card management system.
- EMBOSSING_FILE_GENERATED: Card data (card number, PIN, CVV) generated, and embossing file containing the data is ready to be dispatched to the vendor.
- ORDER_COMPLETED : Card order, including embossing file, is successfully dispatched to the vendor.
- ORDER_FAILED : Card order failed to due to data mismatch or other reason.
- ORDER_CANCELLED : Card order cancelled.
To understand the sequence of order statuses generated for different types of orders, see Card order flow and Bulk card order flow.
Check card order status
Check the status of a card order anytime using its order ID. The response returns various order details specified while creating the order - quantity, Account Holder details, delivery address, and so on. To check the current status of the order, note the value of orderStatus
parameter.
Endpoint URI
POST | /api/v1/ifi/ifiID/cards/orders/{orderID} |
Input Parameters
ifiID
: Required. Unique identifier of the IFI.orderID
: Required. Unique identifier for the order specified at the time of creation.
Example
In the following example, we check the status of a non-personalized card order. The "orderStatus": "CARD_REQUEST_GENERATED" shows that a card with CRN is generated.
Request
Response
curl -X GET 'https://fusion.preprod.zeta.in/api/v1/ifi/140827/cards/orders/cardorder801' \ -H 'Authorization: {{AUTH_TOKEN}}'
{ "quantity": 10, "orderID": "cardorder801", "cardSkuID": "RUPAY_ABC_fintech_PHYSICAL", "plasticCode": "WHITEC", "expiry": { "month": 1, "year": 2023 }, "thirdLineEmbossing": "NA", "fourthLineEmbossing": "NA", "deliveryAddress": { "name": "DirectiPlex", "addressLine1": "Directiplex, Old Nagardas road", "addressLine2": "Andheri (East)", "addressLine3": "Mumbai", "addressLine4": "NA", "city": "Mumbai", "state": "Maharashtra", "country": "India", "postalCode": "400053", "contactNumber": "02228875511" }, "tenantAttributes": { "templateID": "", "corporateID": "", "corporateName": "" }, "vendorAttributes": { "consignmentID": "" }, "additionalAttributes": {}, "orderStatus": "CARD_REQUEST_GENERATED", "orderedAt": "2020-04-14T12:52:38.500Z" }
Card delivery
Vendors
In addition to embossing, vendor also takes care of the delivery of the cards. You can specify your shipping preferences like delivery address and courier partner when creating the order (when calling /dispatch, /orders, /personalized APIs). These details can also be decided upon beforehand between you, Zeta, and the vendor.
Currently, Zeta has partnered with the following vendors:
- SELP
- IDEMIA
- Seshaasai Cards
- Dz Cards
Tracking
Embossing vendors partner with leading courier companies, like Blue Dart, to deliver the card. The courier company shares a tracking ID with the recipient via SMS or e-mail.
Quick tip
You can coordinate with the courier company to receive a pre-approved set of tracking IDs. You can share these IDs with the vendor and use them to integrate a tracking facility in your mobile/web application.
Cancel card order
Cancel an existing card order using its order ID. An order can be cancelled only if the order status
- is in ORDER_RECEIVED or CARD_REQUEST_GENERATED state
- has not moved to EMBOSSING_FILE_PENDING state.
Quick tip
Use orders/{orderID}/cards/list
API to check for above conditions. For more information on how to call the endpoint, see Card Core API Reference.
Important
Cancelling a card order is a permanent operation and cannot be reversed. To re-order, you must create a new card order.
Endpoint URI
POST | /api/v1/ifi/{ifiID}/cards/orders/{orderID}/cancel |
Input parameters
ifiID
: Required. Unique identifier of the IFI.orderID
: Required. Unique identifier of the order to be cancelled.
Example
In the following example, we cancel a personalized card order.
Request
Response
curl -X POST 'https://fusion.preprod.zeta.in/api/v1/ifi/140827/cards/orders/PersonalizedTestOrdersxo45m0ym/cancel' \ -H 'Authorization: {{AUTH_TOKEN}}' \ -H 'Content-Type: application/json'
N/A
- No labels