Bulk Create Virtual Cards Guide

Prerequisites

Before using this functionality, you must subscribe to the issuing.report.succeeded webhook event.

Overview

The bulk virtual card creation process involves the following steps:

1. Subscribe to webhook events
2. Create bulk virtual cards
3. Receive webhook notification with report details
4. Download the encrypted card numbers file
5. Decrypt card numbers using the provided secret key
6. Assign cards to cardholders
7. Receive confirmation webhook

Step-by-Step Implementation

Step 1: Subscribe to Webhook Events

Subscribe to the issuing.report.succeeded webhook event to receive notifications when the bulk card creation report is ready.

Required Webhook Event:

• issuing.report.succeeded

Step 2: Create Bulk Virtual Cards

Call the bulk create virtual cards API endpoint with the following parameters:

Request Body:

{
    "card_bin": "40963608",
    "numbers": 2
}

Response:

{
    "expire_date": "2025-09-18 15:42:38",
    "report_id": "ba36ef65-c0f3-4aa4-9854-a0d644936418"
}

Step 3: Receive Webhook Notification

You will receive a webhook notification with the issuing.report.succeeded event type. Note that only issuing.report.succeeded will be triggered, not issuing.report.created.

Webhook Payload:

{
  "version": "V1.6.0",
  "event_name": "ISSUING",
  "event_type": "issuing.report.succeeded",
  "event_id": "da23f0e9-8c86-4de1-b2dd-2ce6986f3899",
  "source_id": "ba36ef65-c0f3-4aa4-9854-a0d644936418",
  "data": {
    "date_range": "",
    "expire_time": "2025-09-18 15:42:39",
    "report_id": "ba36ef65-c0f3-4aa4-9854-a0d644936418",
    "report_type": "Bulk Create Cards",
    "secret_key": "Ije4a3JVLCdt8wYbNoBCJtHZ13hPOWxeFsoiHKIyOObFDr8jW57c+uhIvzxpP6BnFdval66Ajcg9ZdKI"
  }
}

Extract the following values from the webhook:

• report_id: "ba36ef65-c0f3-4aa4-9854-a0d644936418"
• secret_key: "Ije4a3JVLCdt8wYbNoBCJtHZ13hPOWxeFsoiHKIyOObFDr8jW57c+uhIvzxpP6BnFdval66Ajcg9ZdKI"

Step 4: Download the Report File

Use the report_id to download the encrypted card numbers file.

API Endpoint:

GET https://api-sandbox.uqpaytech.com/api/v1/issuing/reports/{report_id}

Example:

GET https://api-sandbox.uqpaytech.com/api/v1/issuing/reports/ba36ef65-c0f3-4aa4-9854-a0d644936418

Response:

Card Number
WPxhMbRtRlALXuoe0WnNCikN+f/bjDmYHeCcvmmuzUZX/lrV6CfmWOADrWA=
O0pDWRgWtf+zxXUibF4ur6UlwpNc5Wn+Bn3ca5gyg/ehFOCnNk0dJrv2f6E=

Step 5: Decrypt Card Numbers

Use the secret_key obtained from the webhook to decrypt the card numbers. You will also need your API key (the same one used to obtain the x-auth-token) for the decryption process. Refer to the AES-256-GCM decryption documentation for implementation details.

Decrypted Result:

• 4096360800070026
• 4096360800070034

Step 6: Assign Cards to Cardholders

Use the decrypted card numbers to assign cards to cardholders using the Assign Card API.

Request Body:

{
  "cardholder_id": "4438b25d-caa7-4dcf-a8e0-970f05a7bf31",
  "card_number": "4096360800070026",
  "card_currency": "SGD",
  "card_mode": "SINGLE"
}

Response:

{
    "card_order_id": "9d89fb34-3a4d-4cb4-b2c0-c69942f78b1f",
    "card_id": "6e8e6dbd-e16a-4f2f-b8dd-355e9eb541ac",
    "card_status": "PENDING",
    "order_status": "PENDING",
    "create_time": "2025-09-11T17:25:49+08:00",
    "risk_controls": {}
}

Note: Unlike physical cards, virtual cards created through bulk creation are automatically activated upon successful assignment to cardholders. You do not need to call the activate card API separately.

Step 7: Receive Confirmation Webhook

Upon successful card assignment, you will receive a card.create.succeeded webhook notification.

Webhook Payload:

{
  "version": "V1.6.0",
  "event_name": "ISSUING",
  "event_type": "card.create.succeeded",
  "event_id": "a085d26f-9439-438e-977a-9c3fd126c6d3",
  "source_id": "9d89fb34-3a4d-4cb4-b2c0-c69942f78b1f",
  "data": {
    "card_available_balance": "0",
    "card_bin": "40963608",
    "card_id": "6e8e6dbd-e16a-4f2f-b8dd-355e9eb541ac",
    "card_number": "40963608****0026",
    "card_product_id": "b1963667-d688-414b-90df-467c30d3b4af",
    "card_scheme": "VISA",
    "card_status": "ACTIVE",
    "cardholder": {
      "cardholder_id": "4438b25d-caa7-4dcf-a8e0-970f05a7bf31",
      "cardholder_status": "SUCCESS",
      "create_time": "2025-05-27T13:54:11+08:00",
      "email": "[email protected]",
      "first_name": "marshalllll",
      "last_name": "hu"
    },
    "form_factor": "VIRTUAL",
    "metadata": {},
    "mode_type": "SINGLE",
    "risk_control": {
      "allow_3ds_transactions": "Y"
    },
    "spending_limits": [
      {
        "amount": "1281",
        "interval": "PER_TRANSACTION"
      }
    ]
  }
}

At this point, the card is activated and ready for use after funding.

Related Documentation

• Bulk Create Virtual Cards API
• Assign Card API
• Card Created Webhook
• Report Succeeded Webhook
• Download Report File API
• AES-256-GCM Decryption Guide