Unknown macro: {hivestonebreadcrumb}
Fusion
Page tree
Skip to end of metadata
  • Created by user-5c3b0, last modified by user-e873e on Aug 18, 2020
Go to start of metadata

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:

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.

 This file is shared with the vendor, who uses it to emboss the card. Fusion's embossing service handles the generation of embossing file. One file is generated for each product type or IFI. For example, if you place 10 card orders, consisting of 6 orders for IFI A and 4 for IFI B, the embossing service generates two embossing files —one file will contain order data for 6 cards for IFI A, and the other one will contain order data for 4 cards for IFI B.

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:

  1. Create card order by creating an Account for the Account Holder.
  2. Generate embossing file by calling the /dispatch API
  3. 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 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'
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_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 sample 
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"
}
}'
JSON sample 
{
"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:

  1. Create non-personalized or personalized bulk card order
  2. Generate embossing file
  3. Map card to Account Holder by assigning Form Factor to Resource
  4. 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 sample 
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": {
}
}
]
}'
JSON sample 
{
"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 sample 
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": ""
}
}'
JSON sample 
{
"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 as CardID and CGUID.
  • 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 sample 
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"
}'
JSON sample 
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 sample 
curl -X GET 'https://fusion.preprod.zeta.in/api/v1/ifi/140827/cards/orders/cardorder801' \
-H 'Authorization: {{AUTH_TOKEN}}'
JSON sample 
{
"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.

The recipient can then use the tracking ID to track the delivery on the courier company’s website.

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 sample 
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'
JSON sample 
N/A

On this page

Need Help?

Drop a mail at fusion-support@zeta.tech or call us on 080-6690 5995.

  • No labels

© 2019 Better World Technology Pvt. Ltd.