Switch to dark theme

Switch to light theme

Bulk Card Issuance

There are many practical real-world use cases and scenarios where you would want to bulk issue cards to your account holders. Examples include:- when you as a Fintech have a network of corporates who want to bulk disburse gift cards or General Purpose Reloadable(GPR) payroll cards to their employees. Another example could be when you have a network of branches or resellers each of whom is trying to resell your gift cards or payment instruments on your behalf to their users.

The problem that most fintechs run into while going after this use case are many

  • How to issue multiple cards in a single API call as against calling a single card issuance API multiple times iteratively?
  • How to securely issue cards with zero balance and blocked state so that financial risk is mitigated?
  • How to issue non-personalized cards which could later be associated with account holders?
  • How to manage the lifecycle of such cards including PIN disbursal, card activation, card blocking, etc.?
  • How to understand the cards disbursed, their associated usage and access branch wide reports?

Fusion has a bulk card issuance API that allows you to solve for each of the above-mentioned pain points. From here onwards, we are going to call cards as form factors (the representative term we use in Fusion)

In this tutorial, you would use Fusion to bulk issue cards to your account holders. We would be building for a scenario where a company by the name of ZegPay is trying to bulk disburse gift cards to the employees of its partner corporate network. These gift cards are non-reloadable and there is no KYC needed for the employees/account holder if the employee were to just hold this card. The corporates on the other hand need to get a KYC done.

However, let’s complicate the scenario slightly by assuming that ZegPay is trying to provide 2 types of cards to the employees - one a bulk card that is a non-GPR gift card and the other a GPR open-loop gift card that is provided to the employee. So in this case the employee KYC would also be required.

Before you begin

Keep the following points in mind before making calls to Fusion APIs:

  • Endpoint URI: To ensure data privacy and security, all Fusion APIs are served over HTTPS and use the common URI https://fusion.preprod.zeta.in/
  • Authentication: Before testing any endpoint using the cURL sample provided, replace {{AUTH_TOKEN}} with the X-Zeta-AuthToken provided by Zeta.
  • accountHolderID and individualID are same and used interchangeably in the tutorial
  • A unique identifier (ifiID) 140827 is assigned to the fintech for this tutorial.

Sequence

You can create two types of Account Holders on Fusion - Real Account Holder and Legal Account Holder. For the following use case, let’s start off by creating a new Legal Account Holder by the name of ZegWorld.

Pass application details in the body to create a Legal Account Holder for ZegWorld, under ifiID 140827. Note the Account Holder identifier (individualID) in the response. We will be needing this in subsequent steps.

Retrieve Account Holder Details

To view Account Holder details, call the /accountHolders/{accountHolderID} endpoint. To view ZegWorld’s details, pass the value of individualID obtained from the Create Primary Account Holder step in the endpoint.

Assuming that ZegWorld has been KYC’d and is onboarded as a Legal Account Holder in the system, ZegPay can then proceed to do bulk card issuance on ZegWorld’s behalf.

Step 2: ZegPay makes a bulk card order

The fundamental concept to be aware of in this step is that Fintech first places the bulk card order with a certain quantity alongwith a bunch of other configurations and thereafter proceeds to link these cards, once they are delivered, to the employees who get these cards.

Please note that at this moment we have not issued any bundle to the account holder created in Step 1. All we do here is create a certain number of empty form factors with zero balance and/or blocked status scheduled to be embossed and delivered to either the fintech, who can then go ahead and dispatch it to ZegWorld or directly to ZegWorld.

In the following API, the fintech orders 200 quantity of certain types of cards (assume non-personalized, open-loop Rupay gift cards) captured in cardSkuID with a certain expiry date to be delivered to ZegWorld’s address at DirectiPlex in Mumbai. The cardSkuIDs are created at the time of VBO onboarding on behalf of a VBO.



The arrangement is as shown above. Typically the cardSkuIDs are created for personalized and bulk orders separately in order to enabled different levels of controls on the card embossing process (ORDER_RECEIVED, CARD_DATA_GENERATED, EMBOSSING_FILE_PENDING, EMBOSSING_FILE_GENERATED). For personalized card orders, typically the fintechs ask us to stop at CARD_DATA_GENERATED state, the journey post which is completed by a manual dispatch API call by the fintech. For bulk card orders, typically the fintechs ask us to take the order through to EMBOSSING_FILE_GENERATED state with no manual intervention.

Also noteworthy, in the following case is that fintech has specifically asked the orders to be delivered to DirectiPlex. In certain cases, when the fintech has directly chatted and provided the embossing vendor with a certain address, the vendor disregards this field in the embossing file and proceeds to deliver the order at the address mutually agreed upon between the fintech and the card personalization vendor.

cURL Sample
Switch Theme
Expand More
Copy
curl -X POST \
  {{base_url}}/api/v1/ifi/140793/cards/orders \
  -H 'Accept: application/json, text/plain, */*' \
  -H 'Authorization: Bearer {{token}}' \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -d '{
    "quantity": "200",
    "orderID": "ZegWorldbulkcardorder10",
    "cardSkuID": "Bank_60827122_PHYSICAL_ZEGWORLD",
    "plasticCode": "WHITEC",
    "expiry": {
        "month": 1,        "year": 5,
        "separator": "/"
    },
    "thirdLineEmbossing": "", //this is not used in the bulk card order flow
    "fourthLineEmbossing": "", //this is not used in the bulk card order flow
    "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": ""
    }
}'
Code Copied
JSON Sample
Switch Theme
Expand More
Copy
{
    "quantity": 200,
    "orderID": "zegworldbulkcardorder10",
    "cardSkuID": "Bank_60827122_PHYSICAL_ZEGWORLD",
    "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": {
        "corporateName": "",
        "corporateID": "",
        "templateID": ""
    },
    "vendorAttributes": {
        "consignmentID": ""
    }
}
Code Copied

Once you call this API, the order gets created in the ORDER_RECEIVED state.

Formfactor id’s are created once the order reaches “EMBOSSING_FILE_GENERATED” state (cron job runs at Zeta’s end at 2.30 am every night). So the VBO can only retrieve form factor IDs/card IDs after the order reaches this state because this is the state post which the actual card data is generated. CRN numbers are however immediately available for consumption.

The embossing file is shared to the personalization vendor for card printing.

Step 3: ZegPay does a Get Card Order

Once the order is placed, ZegPay makes the GET call on the orderId in Step 2 to get the list of all CRNs (card reference numbers) that are generated as part of the order. These are the CRNs which would be used by the account holder to link to his/her account at the time of actual linking of the delivered card to the account holder. These CRNs are printed on the welcome kit printed by the card personalization vendor alongwith the card.

In the following example, you would see cardID as well which is technically generated only after you reach EMBOSSING_FILE_GENERATED state. As you can also see in the response each object in the arraylist also has a CRN number.

cURL Sample
Switch Theme
Expand More
Copy
curl -X GET \
  '{{base_url}}/api/v1/ifi/{{ifiID}/orders/zegworldbulkcardorder10/cards/list?limit=2&offset=0' \
  -H 'Authorization: Bearer {{token}}' 
Code Copied
JSON Sample
Switch Theme
Expand More
Copy
[
    {
        "cardID": "8992e2e5-d64a-4731-a095-60673c221991",
        "crn": "164690900185",
        "cardType": "PHYSICAL",
        "maskedPan": "608271-xxxxxx-8277",
        "cardStatus": "ENABLED",
        "orderDetails": {
            "orderID": "vbobulkcardorder10",
            "cardSkuID": "Bank_60827122_PHYSICAL_VBO",
            "cardSku": {
                "cardSkuId": "Bank_60827122_PHYSICAL_VBO",
                "productID": "203229671356371",
                "ifi": "140793",
                "bin": "608271",
                "plasticCode": "SI1205",
                "vendorID": "SELP",
                "tags": [
                    "tag://vbo/6a90160f-1306-420a-945a-080a3edd0325"
                ],
                "range": "22"
            },
            "plasticCode": "WHITEC",
            "thirdLineEmbossing": "NA",
            "fourthLineEmbossing": "NA",
            "expiry": {
                "month": "7",
                "year": "43"
            },
            "deliveryAddress": {
                "country": "India",
                "city": "Mumbai",
                "postalCode": "400053",
                "contactNumber": "02228875511",
                "addressLine1": "Directiplex, Old Nagardas road",
                "addressLine2": "Andheri (East)",
                "addressLine3": "Mumbai",
                "state": "Maharashtra",
                "addressLine4": "NA"
            },
            "tenantAttributes": {
                "templateID": "",
                "corporateID": "",
                "corporateName": ""
            },
            "orderStatus": "EMBOSSING_FILE_GENERATED"
        },
        "binRange": {
            "bin": "608271",
            "range": "22"
        }
    },
    {
        "cardID": "6ae083ea-70ee-47fb-8178-6c27323d1434",
        "crn": "122376302566",
        "cardType": "PHYSICAL",
        "maskedPan": "608271-xxxxxx-3836",
        "cardStatus": "ENABLED",
        "orderDetails": {
            "orderID": "vbobulkcardorder10",
            "cardSkuID": "Bank_60827122_PHYSICAL_VBO",
            "cardSku": {
                "cardSkuId": "Bank_60827122_PHYSICAL_VBO",
                "productID": "203229671356371",
                "ifi": "140793",
                "bin": "608271",
                "plasticCode": "SI1205",
                "vendorID": "SELP",
                "tags": [
                    "tag://vbo/6a90160f-1306-420a-945a-080a3edd0325"
                ],
                "range": "22"
            },
            "plasticCode": "WHITEC",
            "thirdLineEmbossing": "NA",
            "fourthLineEmbossing": "NA",
            "expiry": {
                "month": "7",
                "year": "43"
            },
            "deliveryAddress": {
                "country": "India",
                "city": "Mumbai",
                "postalCode": "400053",
                "contactNumber": "02228875511",
                "addressLine1": "Directiplex, Old Nagardas road",
                "addressLine2": "Andheri (East)",
                "addressLine3": "Mumbai",
                "state": "Maharashtra",
                "addressLine4": "NA"
            },
            "tenantAttributes": {
                "templateID": "",
                "corporateID": "",
                "corporateName": ""
            },
            "orderStatus": "EMBOSSING_FILE_GENERATED"
        },
        "binRange": {
            "bin": "608271",
            "range": "22"
        }
    }
]
Code Copied

Alternatively, you can also get the cardID by doing a list card by CRN.

cURL Sample
Switch Theme
Expand More
Copy
curl -X GET \
  {{base_url}}/api/v1/ifi/140793/cards/164690900185 \
  -H 'Authorization: Bearer {{token}}' \
  -H 'Content-Type: application/json'
Code Copied
JSON Sample
Switch Theme
Expand More
Copy
{
    "resource": {
        "uri": "resource://e0a0c703-2280-41a0-b1df-4a83ba01c73c",
        "attributes": {}
    },
    "cardID": "8992e2e5-d64a-4731-a095-60673c221991",
    "crn": "164690900185",
    "cardType": "PHYSICAL",
    "maskedPan": "608271-xxxxxx-8277",
    "cardStatus": "ENABLED",
    "orderDetails": {
        "orderID": "Vbobulkcardorder10",
        "cardSkuID": "Bank_60827122_PHYSICAL_PESEVA",
        "cardSku": {
            "cardSkuId": "Bank_60827122_PHYSICAL_PESEVA",
            "productID": "203229671356371",
            "ifi": "140793",
            "bin": "608271",
            "plasticCode": "SI1205",
            "vendorID": "SELP",
            "tags": [
                "tag://vbo/6a90160f-1306-420a-945a-080a3edd0325"
            ],
            "range": "22"
        },
        "plasticCode": "WHITEC",
        "thirdLineEmbossing": "NA",
        "fourthLineEmbossing": "NA",
        "expiry": {
            "month": "7",
            "year": "43"
        },
        "deliveryAddress": {
            "country": "India",
            "city": "Mumbai",
            "postalCode": "400053",
            "contactNumber": "02228875511",
            "addressLine1": "Directiplex, Old Nagardas road",
            "addressLine2": "Andheri (East)",
            "addressLine3": "Mumbai",
            "state": "Maharashtra",
            "addressLine4": "NA"
        },
        "tenantAttributes": {
            "templateID": "",
            "corporateID": "",
            "corporateName": ""
        },
        "orderStatus": "EMBOSSING_FILE_GENERATED"
    },
    "tenantAttributes": {},
    "binRange": {
        "bin": "608271",
        "range": "22"
    }
}
Code Copied

Step 4: Create Account Holder

In a real-world scenario, creating an Account Holder consists of submitting an application request for the applicant with details. This involves calling multiple APIs to complete the process. After Zeta verifies and approves the request, an Account Holder with a unique identifier is created on Fusion. For the sake of this tutorial, we are taking the following deviations:

  • Call only the /newIndividual endpoint.
  • Aadhar is used for KYC verification.
  • The request is auto-approved, as indicated by status:APPROVED in the response.

You can create two types of Account Holders on Fusion - Real Account Holder and Legal Account Holder . For this use-case, you create a Real Account Holder for Abhinav Shukla .

Pass application details in the body to create Account Holder for Abhinav, under ifiID 140827. Note the Account Holder identifier (individualID) in the response. We will be needing this in subsequent steps.

Step 6: Get eligible Bundles for the account holder

Before you can proceed with issuing the requisite bundle to the account holder Abhinav Shukla, you can get the list of all eligible bundles that can be issued to the account holders under the fintech’s approved program from the Financial Institute.

To do this, call the /bundles endpoint. The response returns a unique identifier, id, for each available product.

JSON Sample
Switch Theme
Expand More
Copy
[
    {
        "id": "afc3e19e-21af-4846-a6bd-a4250c28ed7a",
        "ifiID": 304876,
        "vboID": "48302dbf-e689-4887-87a8-b23808c03be0",
        "name": "Test Bundle (Gift)",
        "accountProducts": [
            {
                "id": "2763edf1-fa67-45f2-8106-88a6e7e5feb5",
                "productName": "GIFT_Product",
                "description": "",
                "productID": "4956860845545643343",
                "type": "ACCOUNT",
                "programIDs": "",
                "ifiID": 304876,
                "attributes": {}
            }
        ],
        "paymentProducts": [
            {
                "id": "fe9c7226-4c8f-49b2-95d1-0cfb32d2134c",
                "productName": "PAYMENT PRODUCT UAT VBO RBL",
                "description": "Payment Product For UAT VBO RBL",
                "productID": "2960f096-62bf-4743-ae1e-a1d964c1e004",
                "type": "PAYMENT",
                "programIDs": "",
                "ifiID": 304876,
                "attributes": {}
            }
        ],
        "status": "active",
        "attributes": {},
        "createdAt": "Oct 7, 2020 4:00:15 PM",
        "updatedAt": "Oct 7, 2020 4:00:15 PM",
        "shortCode": "BUNGIFT"
    },
    {
        "id": "9638f6f0-80ff-435f-9191-338327eb8ab0",
        "ifiID": 304876,
        "vboID": "72c60745-0b76-48c5-a8b7-ac30b6fef57c",
        "name": "VBOUAT Bundle(GPR Min KYC With Pan)",
        "accountProducts": [
            {
                "id": "6b1645fd-4eb8-4963-adcb-2e2290859505",
                "productName": "GPR_MIN_KYC_WITH_PAN_UAT",
                "description": "",
                "productID": "1678556640324530811",
                "type": "ACCOUNT",
                "programIDs": "",
                "ifiID": 304876,
                "attributes": {}
            }
        ],
        "paymentProducts": [
            {
                "id": "fc4e5c0b-7c06-42ee-bfdf-4e11ae74a477",
                "productName": "PAY_PRODUCT_ATCAP_PHY_UAT",
                "description": "PAY_PRODUCT_ATCAP_PHY_UAT",
                "productID": "7bc93109-0596-4857-9ef2-15b40cbcaa57",
                "type": "PAYMENT",
                "programIDs": "",
                "ifiID": 304876,
                "attributes": {}
            }
        ],
        "status": "active",
        "attributes": {},
        "createdAt": "Dec 14, 2020 5:40:10 AM",
        "updatedAt": "Dec 14, 2020 5:40:10 AM",
        "shortCode": "BUNIN1412"
    },
    {
        "id": "c5f96d7c-cb49-4f5d-926b-cd81d205712f",
        "ifiID": 304876,
        "vboID": "946b74ee-0cad-4516-9e0c-f4030c7e36bf",
        "name": "VBOUAT Bundle(GPR Min KYC With Pan)",
        "accountProducts": [
            {
                "id": "f8ddd32d-94b4-4cd4-9e1b-b157a55184c4",
                "productName": "GPR_MIN_KYC_WITH_PAN_UAT",
                "description": "",
                "productID": "1678556640324530811",
                "type": "ACCOUNT",
                "programIDs": "",
                "ifiID": 304876,
                "attributes": {}
            }
        ],
        "paymentProducts": [
            {
                "id": "b1778501-49f3-4ff0-8023-aa6176719166",
                "productName": "PAY_PRODUCT_ANTIQ_PHY_UAT",
                "description": "PAY_PRODUCT_ANTIQ_PHY_UAT",
                "productID": "fe72ed51-2195-4744-b385-d4e766356936",
                "type": "PAYMENT",
                "programIDs": "",
                "ifiID": 304876,
                "attributes": {}
            }
        ],
        "status": "active",
        "attributes": {},
        "createdAt": "Jan 29, 2021 10:45:26 AM",
        "updatedAt": "Jan 29, 2021 10:45:26 AM",
        "shortCode": "BUNIN2901"
    },
    {
        "id": "502cb813-8ccb-49ec-8e32-63a95f8fb6e8",
        "ifiID": 304876,
        "vboID": "ea4f06a3-6b9f-4948-bc75-e4bdb4d6cc9b",
        "name": "VBOUAT Bundle(GPR Min KYC With Pan)",
        "accountProducts": [
            {
                "id": "1966ef63-5d02-4f3f-aa32-f9c7146f3831",
                "productName": "GPR_MIN_KYC_WITH_PAN_UAT",
                "description": "",
                "productID": "1678556640324530811",
                "type": "ACCOUNT",
                "programIDs": "",
                "ifiID": 304876,
                "attributes": {}
            }
        ],
        "paymentProducts": [
            {
                "id": "1ca677a1-0b8a-4d55-b2ee-d91fbec21fab",
                "productName": "PAYMENT_PRODUCT_JUNIOUAT",
                "description": "PAYMENT_PRODUCT_JUNIOUAT",
                "productID": "f19883e7-c917-4732-a67d-1896b2a38d8b",
                "type": "PAYMENT",
                "programIDs": "",
                "ifiID": 304876,
                "attributes": {}
            }
        ],
        "status": "active",
        "attributes": {},
        "createdAt": "Nov 23, 2020 11:27:14 AM",
        "updatedAt": "Nov 23, 2020 11:27:14 AM",
        "shortCode": "BUNINJU01"
    },
    {
        "id": "f0a95ccb-1bad-4afa-a488-2cbfa9760a74",
        "ifiID": 304876,
        "vboID": "48302dbf-e689-4887-87a8-b23808c03be0",
        "name": "Test Bundle (GPR Aadhar OTP without PAN without ATM support)",
        "accountProducts": [
            {
                "id": "8ea7a854-7fe4-4b2c-b9dc-404bbb4cf49a",
                "productName": "GPR_AADHAR_OTP_KYC_WITHOUT_PAN",
                "description": "",
                "productID": "5208776346483433353",
                "type": "ACCOUNT",
                "programIDs": "",
                "ifiID": 304876,
                "attributes": {}
            }
        ],
        "paymentProducts": [
            {
                "id": "7a47be1b-ce97-4020-8279-2ab0319a6bce",
                "productName": "PAYMENT PRODUCT UAT VBO RBL",
                "description": "Payment Product For UAT VBO RBL",
                "productID": "2960f096-62bf-4743-ae1e-a1d964c1e004",
                "type": "PAYMENT",
                "programIDs": "",
                "ifiID": 304876,
                "attributes": {}
            }
        ],
        "status": "active",
        "attributes": {},
        "createdAt": "Oct 7, 2020 3:49:47 PM",
        "updatedAt": "Oct 7, 2020 3:49:47 PM",
        "shortCode": "GPRADROTP"
    },
    {
        "id": "d7cc6c8e-a33d-4395-84d7-db603b0b42a8",
        "ifiID": 304876,
        "vboID": "48302dbf-e689-4887-87a8-b23808c03be0",
        "name": "Test Bundle (GPR Aadhar OTP with PAN with ATM support)",
        "accountProducts": [
            {
                "id": "142f2e7e-0a25-4a5a-9963-191df652fa2c",
                "productName": "GPR_WITH_ATM_AADHAAR_OTP_KYC_WITH_PAN",
                "description": "",
                "productID": "4469735783243004067",
                "type": "ACCOUNT",
                "programIDs": "",
                "ifiID": 304876,
                "attributes": {}
            }
        ],
        "paymentProducts": [
            {
                "id": "e3b05149-6865-4edc-a068-8c5832f56cbe",
                "productName": "PAYMENT PRODUCT UAT VBO RBL",
                "description": "Payment Product For UAT VBO RBL",
                "productID": "2960f096-62bf-4743-ae1e-a1d964c1e004",
                "type": "PAYMENT",
                "programIDs": "",
                "ifiID": 304876,
                "attributes": {}
            }
        ],
        "status": "active",
        "attributes": {},
        "createdAt": "Oct 7, 2020 3:15:43 PM",
        "updatedAt": "Oct 7, 2020 3:15:43 PM",
        "shortCode": "GPRATMPAN"
    },
    {
        "id": "308bcdea-cd91-4bbf-bc0e-46fda19a3bb7",
        "ifiID": 304876,
        "vboID": "48302dbf-e689-4887-87a8-b23808c03be0",
        "name": "Test Bundle (GPR Full KYC Aadhar OTP With PAN)",
        "accountProducts": [
            {
                "id": "e607bfbc-fcca-4f5e-a9b8-54fe0eb225ad",
                "productName": "GPR_AADHAR_OTP_KYC_WITH_PAN",
                "description": "",
                "productID": "5637478803458463019",
                "type": "ACCOUNT",
                "programIDs": "",
                "ifiID": 304876,
                "attributes": {}
            }
        ],
        "paymentProducts": [
            {
                "id": "21ec7737-1f2d-41c1-812e-da7c0a6475dd",
                "productName": "PAYMENT PRODUCT UAT VBO RBL",
                "description": "Payment Product For UAT VBO RBL",
                "productID": "2960f096-62bf-4743-ae1e-a1d964c1e004",
                "type": "PAYMENT",
                "programIDs": "",
                "ifiID": 304876,
                "attributes": {}
            }
        ],
        "status": "active",
        "attributes": {},
        "createdAt": "Oct 7, 2020 3:55:53 PM",
        "updatedAt": "Oct 7, 2020 3:55:53 PM",
        "shortCode": "GPRFULLKYC"
    },
    {
        "id": "48250452-4571-4913-aecf-7391964040c7",
        "ifiID": 304876,
        "vboID": "48302dbf-e689-4887-87a8-b23808c03be0",
        "name": "Test Bundle(GPR Min KYC Without Pan)",
        "accountProducts": [
            {
                "id": "0624a306-1fef-4f92-8a14-c1149434ec9b",
                "productName": "GPR_MIN_KYC_WITHOUT_PAN",
                "description": "",
                "productID": "1103692671169244247",
                "type": "ACCOUNT",
                "programIDs": "",
                "ifiID": 304876,
                "attributes": {}
            }
        ],
        "paymentProducts": [
            {
                "id": "cfd0e7c4-9437-4283-b9cd-e35710cb2e69",
                "productName": "PAYMENT PRODUCT UAT VBO RBL",
                "description": "Payment Product For UAT VBO RBL",
                "productID": "2960f096-62bf-4743-ae1e-a1d964c1e004",
                "type": "PAYMENT",
                "programIDs": "",
                "ifiID": 304876,
                "attributes": {}
            }
        ],
        "status": "active",
        "attributes": {},
        "createdAt": "Oct 7, 2020 3:41:52 PM",
        "updatedAt": "Oct 7, 2020 3:41:52 PM",
        "shortCode": "GPRMINKYC"
    },
    {
        "id": "ea2568c0-bff5-4e74-9796-07cf93a13205",
        "ifiID": 304876,
        "vboID": "48302dbf-e689-4887-87a8-b23808c03be0",
        "name": "Test Bundle(GPR Min KYC With Pan)",
        "accountProducts": [
            {
                "id": "314e39b7-d0aa-429d-8e48-ad0a1a45e5cb",
                "productName": "GPR_MIN_KYC_WITH_PAN",
                "description": "",
                "productID": "1678556640324530811",
                "type": "ACCOUNT",
                "programIDs": "",
                "ifiID": 304876,
                "attributes": {}
            }
        ],
        "paymentProducts": [
            {
                "id": "ad442ad7-bc12-4587-81f9-b463bd6338af",
                "productName": "PAYMENT PRODUCT UAT VBO RBL",
                "description": "Payment Product For UAT VBO RBL",
                "productID": "2960f096-62bf-4743-ae1e-a1d964c1e004",
                "type": "PAYMENT",
                "programIDs": "",
                "ifiID": 304876,
                "attributes": {}
            }
        ],
        "status": "active",
        "attributes": {},
        "createdAt": "Oct 7, 2020 3:44:27 PM",
        "updatedAt": "Oct 7, 2020 3:44:27 PM",
        "shortCode": "GPRMINKYCP"
    },
    {
        "id": "26db95d9-bc9c-49f1-8aed-a3877381c07a",
        "ifiID": 304876,
        "vboID": "48302dbf-e689-4887-87a8-b23808c03be0",
        "name": "Test Bundle (GPR Aadhar OTP without PAN with ATM support)",
        "accountProducts": [
            {
                "id": "bfed6883-8eae-433e-b88f-8f6aa8e63821",
                "productName": "GPR_WITH_ATM_AADHAAR_OTP_KYC_WITHOUT_PAN",
                "description": "",
                "productID": "2235350173450490986",
                "type": "ACCOUNT",
                "programIDs": "",
                "ifiID": 304876,
                "attributes": {}
            }
        ],
        "paymentProducts": [
            {
                "id": "83a44b97-78f2-48c1-b054-c8406ba0c85e",
                "productName": "PAYMENT PRODUCT UAT VBO RBL",
                "description": "Payment Product For UAT VBO RBL",
                "productID": "2960f096-62bf-4743-ae1e-a1d964c1e004",
                "type": "PAYMENT",
                "programIDs": "",
                "ifiID": 304876,
                "attributes": {}
            }
        ],
        "status": "active",
        "attributes": {},
        "createdAt": "Oct 7, 2020 5:18:55 AM",
        "updatedAt": "Oct 7, 2020 5:18:55 AM",
        "shortCode": "GPROTPATM"
    }
]
Code Copied

Step 7: Issue bundle to the Account Holder

On Fusion, Account/Payment products are issued to an Account Holder using Bundles. Bundle is an encapsulation of Account and Payment products that can be provisioned to your Account Holders. For example, a liability account that provides a salary account and a prepaid card.

For the cookbook, we would be issuing the bundle that was shown in the figure below



The key point to note is that since Abhinav has not yet gotten a physical card which he can immediately associate with his account, we would be issuing the bundle using a disableFFCreation flag that would issue an account from the account product and an empty resource thereby not issuing either the personalized/bulk card form factor product nor the phone form factor product.

To issue the bundle to Abhinav, call /bundles/{bundleID}/issueBundle endpoint and pass the identifier, id, of the eligible bundle, obtained from



Get eligible bundles step.

cURL Sample
Switch Theme
Expand More
Copy
curl -X POST \
  {{base_url}}/api/v1/ifi/140793/bundles/38856ecb-08d4-4bda-ab71-76a490bb54d5/issueBundle \
  -H 'Content-Type: application/json' \
  -H 'X-Zeta-AuthToken: {{token}}' \
  -d '{
    "accountHolderID": "75c0cb03-d440-4862-8bfb-86c4d37bd7e4",
    "name": "debitIssueBundle",
    "disableFFCreation" : "true"
}'
Code Copied
JSON Sample
Switch Theme
Expand More
Copy
{
    "requestID": "9b30210a-9c50-4a6e-865e-0add04cc2324",
    "accounts": [
        {
            "bundleID": "38856ecb-08d4-4bda-ab71-76a490bb54d5",
            "accountHolderID": "75c0cb03-d440-4862-8bfb-86c4d37bd7e4",
            "accountID": "134c110a-9f55-4b07-99b5-c7a6d9563634"
        }
    ],
    "paymentInstruments": [
        {
            "bundleID": "38856ecb-08d4-4bda-ab71-76a490bb54d5",
            "resourceID": "e0a0c703-2280-41a0-b1df-4a83ba01c73c",
            "status": "ACTIVE",
            "targetAccount": "account://134c110a-9f55-4b07-99b5-c7a6d9563634"
        }
    ]
}
Code Copied

As you can see in the response, the call has just issued an accountID: 134c110a-9f55-4b07-99b5-c7a6d9563634. In the paymentInstruments section it has just created an empty resource with a resource ID of e0a0c703-2280-41a0-b1df-4a83ba01c73c that maps to the above account.

Step 8: Fintech issues a personalized card to the Account Holder

At this stage, since the bulk card is yet to get delivered, the fintech can go ahead and issue the personalized virtual card to Abhinav Shukla immediately so that Abhinav gets to see the card details on his app and gets instant gratification. You can do that using the following calls

In order to issue the relevant form factor, the fintech will have to use the Get Resource API to get the form factor product details specific for the bundle.

cURL Sample
Switch Theme
Expand More
Copy
curl --location --request GET '{{base_url}}/api/v1/ifi/{{ifiID}}/resources/{{resourceID}}' \
--header 'X-Zeta-AuthToken: {{token}}\'
Code Copied
JSON Sample
Switch Theme
Expand More
Copy
{
    "ifi": 304876,
    "id": "b8577dde-1b99-4dad-a61c-e41e9e6048d2",
    "resourceProductId": "a4ac7f33-0e06-4bea-940f-d1b0754992c9",
    "resourceProduct": {
        "ifi": 304876,
        "id": "a4ac7f33-0e06-4bea-940f-d1b0754992c9",
        "code": "RP_UAT_RBL_03",
        "name": "RESOURCE PRODUCT UAT VBO RBL",
        "description": "Resource Product For UAT VBO RBL",
        "formFactorProducts": [
            {
                "ifi": 304876,
                "id": "7d866732-59b1-4c04-8d6d-c1e90e6b6d35",
                "code": "CMS_UAT_RBL_03",
                "name": "CMS Form Factor UAT VBO RBL",
                "description": "Form Factor For UAT Test VBO RBL",
                "type": "card",
                "policies": {
                    "issuancePolicies": [],
                    "paymentPolicies": []
                },
                "provider": "CMS",
                "skuID": "Fusion_test_12345633",
                "tags": [
                    "tag://vbo/48302dbf-e689-4887-87a8-b23808c03be0"
                ],
                "attributes": {},
                "issuanceStatus": "ACTIVE",
                "paymentStatus": "ACTIVE",
                "createdAt": "Sep 17, 2020 7:55:32 AM",
                "modifiedAt": "Sep 17, 2020 7:55:32 AM",
                "headers": {
                    "tenantID": "304876",
                    "object": "[email protected]"
                }
            },
            {
                "ifi": 304876,
                "id": "973fa451-5a1c-4bf1-bd4a-362f78a3f931",
                "code": "PMS_UAT_RBL_03",
                "name": "PMS Form Factor UAT VBO RBL",
                "description": "Form Factor For UAT Test VBO RBL",
                "type": "phoneNumber",
                "policies": {
                    "issuancePolicies": [],
                    "paymentPolicies": []
                },
                "provider": "PMS",
                "skuID": "Fusion_test_12345633",
                "tags": [
                    "tag://vbo/48302dbf-e689-4887-87a8-b23808c03be0"
                ],
                "attributes": {},
                "issuanceStatus": "ACTIVE",
                "paymentStatus": "ACTIVE",
                "createdAt": "Sep 17, 2020 7:55:36 AM",
                "modifiedAt": "Sep 17, 2020 7:55:36 AM",
                "headers": {
                    "tenantID": "304876",
                    "object": "[email protected]"
                }
            }
        ],
        "tags": [
            "tag://vbo/48302dbf-e689-4887-87a8-b23808c03be0"
        ],
        "policies": {
            "issuancePolicies": [],
            "paymentPolicies": []
        },
        "status": "ACTIVE",
        "createdAt": "Sep 17, 2020 7:55:40 AM",
        "modifiedAt": "Sep 17, 2020 7:55:40 AM",
        "headers": {}
    },
    "targetURI": "account://7d5947c5-c65d-4345-98b9-ac43c4937823",
    "formFactors": [
        {
            "id": "b7eaeb39-7d6f-4540-a1f3-4a2a5ad74764",
            "ifi": 304876,
            "formFactorProductID": "7d866732-59b1-4c04-8d6d-c1e90e6b6d35",
            "formFactorID": "dfdb3c40-1481-4033-b4e4-436e8d6f8d97",
            "targetURI": "account://7d5947c5-c65d-4345-98b9-ac43c4937823",
            "tags": [],
            "attributes": {},
            "policies": {
                "issuancePolicies": [],
                "paymentPolicies": []
            },
            "status": "ACTIVE",
            "createdAt": "Feb 1, 2021 1:01:30 PM",
            "modifiedAt": "Feb 1, 2021 1:01:30 PM",
            "headers": {}
        },
        {
            "id": "fb140ae9-44ce-4e57-85ba-6eedd044fb72",
            "ifi": 304876,
            "formFactorProductID": "973fa451-5a1c-4bf1-bd4a-362f78a3f931",
            "formFactorID": "+910077007791",
            "targetURI": "account://7d5947c5-c65d-4345-98b9-ac43c4937823",
            "tags": [],
            "attributes": {
                "phoneNumber": "+910077007791"
            },
            "policies": {
                "issuancePolicies": [],
                "paymentPolicies": []
            },
            "status": "ACTIVE",
            "createdAt": "Feb 1, 2021 1:01:30 PM",
            "modifiedAt": "Feb 1, 2021 1:01:30 PM",
            "headers": {}
        }
    ],
    "tags": [],
    "vectors": [
        "vector://ACCOUNTHOLDER/d4b23b46-3e12-4295-898b-a7a48ee24458"
    ],
    "policies": {
        "issuancePolicies": [],
        "paymentPolicies": []
    },
    "attributes": {},
    "status": "ACTIVE",
    "createdAt": "Feb 1, 2021 1:01:30 PM",
    "modifiedAt": "Feb 1, 2021 1:01:30 PM",
    "headers": {}
}
Code Copied

Out of the 2 form factor products returned use the one where the provider is CMS. Once we have the form factor ID of the card, call the get card by cguid API

cURL Sample
Switch Theme
Expand More
Copy
curl --location --request GET ’{{base_url}}/api/v1/ifi/{ifiID}}/cards/{{cguid}}' \
--header 'X-Zeta-AuthToken: {{token}}' 
Code Copied
JSON Sample
Switch Theme
Expand More
Copy
{
    "account": {
        "attributes": {}
    },
    "resource": {
        "uri": "resource://b8577dde-1b99-4dad-a61c-e41e9e6048d2",
        "attributes": {}
    },
    "cardID": "dfdb3c40-1481-4033-b4e4-436e8d6f8d97",
    "crn": "191751887445",
    "cardType": "VIRTUAL",
    "maskedPan": "123456-xxxxxx-9487",
    "cardStatus": "ENABLED",
    "orderDetails": {
        "orderID": "d616a8e6-6c28-48e6-9487-16f41449d872",
        "cardSkuID": "Fusion_test_12345633",
        "cardSku": {
            "cardSkuId": "Fusion_test_12345633",
            "productID": "204841670116610",
            "ifi": "304876",
            "bin": "123456",
            "plasticCode": "WHITEC",
            "vendorID": "NA",
            "tags": [
                "tag://dispatchmode/manual",
                "tag://vbo/6543734f-5763-4b88-969a-1daa0afe548b"
            ],
            "range": "33"
        },
        "plasticCode": "WHITEC",
        "thirdLineEmbossing": "",
        "fourthLineEmbossing": "",
        "expiry": {
            "month": "1",
            "year": "26"
        },
        "deliveryAddress": {},
        "tenantAttributes": {},
        "orderStatus": "CARD_DATA_GENERATED"
    },
    "tenantAttributes": {},
    "binRange": {
        "bin": "123456",
        "range": "33"
    }
}
Code Copied

Note : The Account Holder can also view the 16 digit card number on the fintech’s app, if the fintech has integrated with Fusion Cards SDK

In case the account holder needs the physical card the /dispatch API is to be called

cURL Sample
Switch Theme
Expand More
Copy
curl --location --request POST '{{base_url}}/api/v1/ifi/304876/cards/dfdb3c40-1481-4033-b4e4-436e8d6f8d97/dispatch' \
--header 'X-Zeta-AuthToken: {{token}}' \
--data-raw '{
    "plasticCode": "WHITEC",
    "thirdLineEmbossing": "Ramana",
    "fourthLineEmbossing": "Kumar",
    "deliveryAddress": {
        "name": "Ramana Kumar",
        "addressLine1": "Directiplex",
        "addressLine2": "Near Andheri Subway",
        "addressLine3": "Old Nagardas Road",
        "addressLine4": "Andheri East",
        "city": "Mumbai",
        "state": "Maharashtra",
        "country": "India",
        "postalCode": "400069",
        "contactNumber": "+917070707070"
    },
    "vendorAttributes": {
        "shipping-partner.name": "BLUEDART",
        "shipping-partner.trackingNumber": "098137643242412312414",
        "welcome-kit.fullName": "Ramana Kumar",
        "welcome-kit.qrCode": "c48tn73793cfh93cg24c872t478r4ft3ubdcy8g3cr",
        "welcome-kit.templateID": "template-id"
    }
}'
Code Copied
JSON Sample
Switch Theme
Expand More
Copy
{
    "quantity": 1,
    "orderID": "d616a8e6-6c28-48e6-9487-16f41449d872",
    "cardSkuID": "Fusion_test_12345633",
    "plasticCode": "WHITEC",
    "expiry": {
        "month": 0,
        "year": 5
    },
    "thirdLineEmbossing": "Ramana",
    "fourthLineEmbossing": "Kumar",
    "deliveryAddress": {
        "name": "Ramana Kumar",
        "addressLine1": "Directiplex",
        "addressLine2": "Near Andheri Subway",
        "addressLine3": "Old Nagardas Road",
        "addressLine4": "Andheri East",
        "city": "Mumbai",
        "state": "Maharashtra",
        "country": "India",
        "postalCode": "400069",
        "contactNumber": "+917070707070"
    },
    "tenantAttributes": {},
    "vendorAttributes": {
        "welcome-kit.qrCode": "c48tn73793cfh93cg24c872t478r4ft3ubdcy8g3cr",
        "welcome-kit.fullName": "Ramana Kumar",
        "shipping-partner.name": "BLUEDART",
        "welcome-kit.templateID": "template-id",
        "shipping-partner.trackingNumber": "098137643242412312414"
    },
    "additionalAttributes": {},
    "orderStatus": "EMBOSSING_FILE_PENDING",
    "orderedAt": "2021-02-01T13:01:30.274Z"
}
Code Copied

Step 9: ZegWorld hands over the physical card to Abhinav Shukla

ZegWorld gets physical cards delivered to their office after 16 -20 days(depends on the vendor). ZegWorld hands over the physical cards to its users, card contains the CRN (Card Reference Number) information. Abhinav Shukla activates the card and links it to the prepaid account: Abhinav enters the CRN number and expiry date of the card to associate.

When Abhinav enters the CRN, ZegPay fetches the cardId using the CRN from the Get Card by CRN API.

cURL Sample
Switch Theme
Expand More
Copy
curl -X GET \
  {{base_url}}/api/v1/ifi/140793/cards/164690900185 \
  -H 'Authorization: Bearer {{token}}' \
  -H 'Content-Type: application/json'
Code Copied
JSON Sample
Switch Theme
Expand More
Copy
{
    "resource": {
        "uri": "resource://e0a0c703-2280-41a0-b1df-4a83ba01c73c",
        "attributes": {}
    },
    "cardID": "8992e2e5-d64a-4731-a095-60673c221991",
    "crn": "164690900185",
    "cardType": "PHYSICAL",
    "maskedPan": "608271-xxxxxx-8277",
    "cardStatus": "ENABLED",
    "orderDetails": {
        "orderID": "vbobulkcardorder10",
        "cardSkuID": "Bank_60827122_PHYSICAL_VBO",
        "cardSku": {
            "cardSkuId": "Bank_60827122_PHYSICAL_VBO",
            "productID": "203229671356371",
            "ifi": "140793",
            "bin": "608271",
            "plasticCode": "SI1205",
            "vendorID": "SELP",
            "tags": [
                "tag://vbo/6a90160f-1306-420a-945a-080a3edd0325"
            ],
            "range": "22"
        },
        "plasticCode": "WHITEC",
        "thirdLineEmbossing": "NA",
        "fourthLineEmbossing": "NA",
        "expiry": {
            "month": "7",
            "year": "43"
        },
        "deliveryAddress": {
            "country": "India",
            "city": "Mumbai",
            "postalCode": "400053",
            "contactNumber": "02228875511",
            "addressLine1": "Directiplex, Old Nagardas road",
            "addressLine2": "Andheri (East)",
            "addressLine3": "Mumbai",
            "state": "Maharashtra",
            "addressLine4": "NA"
        },
        "tenantAttributes": {
            "templateID": "",
            "corporateID": "",
            "corporateName": ""
        },
        "orderStatus": "EMBOSSING_FILE_GENERATED"
    },
    "tenantAttributes": {},
    "binRange": {
        "bin": "608271",
        "range": "22"
    }
}
Code Copied

Next associate the returned cardID (to be passed into this call in the field ‘formFactorID’) to the account holder. In order to do this you would need the formFactorProductID that is linked to the bulk form factor. Use the one that is provided to you by us or choose the one that is associated with the bulk SKU.

In addition the targetURI needs to be associated with the accountID provided to Abhinav when making the



Issue bundle call. In the vectors field, please provide the account holder ID in the format vector://ACCOUNTHOLDER/{{AccountHolderId}}

cURL Sample
Switch Theme
Expand More
Copy
curl -X POST \
  {{base_url}}/api/v1/ifi/140793/resources/e0a0c703-2280-41a0-b1df-4a83ba01c73c/form_factors \
  -H 'Authorization: Bearer {{token}}' \
  -d '{
    "formFactorProductID": "6955636d-99f0-472e-a1ee-58470a441750",
    "formFactorID": "8992e2e5-d64a-4731-a095-60673c221991",
    "targetURI": "account://134c110a-9f55-4b07-99b5-c7a6d9563634",
    "status": "ACTIVE",
    "vectors": ["vector://ACCOUNTHOLDER/75c0cb03-d440-4862-8bfb-86c4d37bd7e4"]
}'
Code Copied
JSON Sample
Switch Theme
Expand More
Copy
{
    "id": "24285fed-c8a3-42b6-850e-4cd76fee24ac",
    "ifi": 140793,
    "formFactorProductID": "6955636d-99f0-472e-a1ee-58470a441750",
    "formFactorID": "8992e2e5-d64a-4731-a095-60673c221991",
    "targetURI": "account://134c110a-9f55-4b07-99b5-c7a6d9563634",
    "tags": [],
    "policies": {
        "issuancePolicies": [],
        "paymentPolicies": []
    },
    "status": "ACTIVE",
    "createdAt": "Jul 2, 2020 8:16:02 AM",
    "modifiedAt": "Jul 2, 2020 8:16:02 AM",
    "headers": {}
}
Code Copied

Post this step, the card and phone number (already associated in



Step 8 of the user gets associated with the resource using the associate form factor API call. The form factors gets mapped to the account issued to the account holder

Step 10: Generate PIN

Use the generate PIN API to generate a 4 digit PIN that would be used over POS terminals and ATMs. This PIN is sent over the registered email id of Abhinav Shukla which is provided as phoneNumber/emailID as a vector during account holder creation.

cURL Sample
Switch Theme
Expand More
Copy
{{base_url}}/api/v1/ifi/140793/cards/8992e2e5-d64a-4731-a095-60673c221991/generatePin \
  -H 'Authorization: Bearer {{token}}' \
  -d '{
   "deliveryChannel": "PHONE"
}'
Code Copied

You can alternatively also use the deliveryChannel as EMAIL depending upon the vector type associated at the time of account holder creation.