Card Issuance Guide

Virtual Card Issuance 💳

GET /cards/bins
    → Create or reuse cardholder
    → Complete preparation if required
    → POST /cards
    → GET /cards

Call Create a new card with channelId, cardType=virtual, and cardOptions (including cardHolderId and your callId), plus any amount or budget settings.

For products requiring preparation, confirm isPrepared=true before creating the card. Products with requiresPreparation=false can proceed directly to issuance.

c_015 supports one virtual card per request.

Save the returned cardId. Query the card state using Get card list with cardId or callId. If the create response is unclear, query using the original callId before attempting another creation.

Subscribe to card.status.update as a notification and refresh signal.

Physical Card Issuance 📮

Both physical-card fulfillment modes create a card placeholder through POST /cards before binding.

The difference is whether a physical card quote and platform delivery application are required:

Both modes use flow=standard for c_015 physical cards.

Merchant Stock: merchant_stock

Merchant stock means the merchant already owns physical card stock, typically purchased offline. This API does not purchase physical stock.

Before creating the card, make sure the product supports merchant_stock and complete preparation if required.

Call POST /cards with:

• channelId: The product ID.
• cardType=physical.
• cardOptions.cardHolderId: The local cardholder ID.
• cardOptions.callId: Your unique issuance identifier.
• cardOptions.fulfillmentMode=merchant_stock.
• Optional label.
• Optional budgetId.

Omit amount, shippingAddress, and physicalApplicationId.

This flow does not create a platform delivery application, require a shipping quote, reserve platform inventory, or initiate platform shipping and review.

Fee handling: POST /cards applies the configured card issuance fee, if applicable. Binding the physical card does not charge the card issuance fee again. Offline stock purchase does not automatically mean the API issuance fee is zero.

After creation, receive the physical card, verify the end-user identity, and proceed with binding and activation.

Platform Delivery: platform_delivery

The platform arranges physical card fulfillment and delivery. This flow requires a quote before card creation.

Step 1: Obtain a quote

Call Quote a physical card with:

• cardChannelId: The product ID.
• cardHolderId: The local cardholder ID.
• shippingAddress: The delivery address.
• Optional budgetId.
• Optional language.

Read and save the returned:

• applicationId
• createFee
• shippingFee
• totalFee
• expiresAt

Step 2: Create the card

Call POST /cards with:

• channelId: The same product ID used in the quote.
• cardType=physical.
• cardOptions.cardHolderId: The same cardholder ID.
• cardOptions.callId: Your unique issuance identifier.
• cardOptions.fulfillmentMode=platform_delivery.
• cardOptions.physicalApplicationId: The applicationId returned by the quote.
• The applicable budget information.

Omit amount and shippingAddress from the create request when the quoted application already contains the delivery information.

Successful creation charges the quoted fees and reserves the required stock for review according to the platform delivery process.

Step 3: Track the application

Use Get physical application with applicationId or callId to read review, shipment, and refund progress.

Rejection refunds the applicable fees and marks the card as rejected. Only after rejection may DELETE /cards be used to soft-delete the card.

Shipping information may include carrier, trackingNumber, and trackingUrl.

Physical Card Issuance Operations

Quote and Create Constraints

Platform-delivery application status values:

quoted, pending_review, awaiting_shipment, shipped, binding, bound, bind_failed, rejected.

Approval leads to shipment. Rejection refunds applicable fees and returns rejectionReason.

Shipping information may contain carrier, trackingNumber, and trackingUrl.

Binding and Activation

PIN rules

• Exactly six digits.
• Cannot consist of six identical digits.
• Must not appear within the holder's phone number.
• Must not end with the card's last four digits.

Webhook responsibilities

The Webhook envelope is:

{event_id, event_identifier, data}

Activation data may contain:

• id or cardId
• accountId
• activationCode
• applicationId for platform-delivery application flows, when applicable

applicationId is not a universal field for all physical-card fulfillment modes. Merchant-stock cards do not have a platform-delivery application.

Encryption, Retries and Identifiers 🔐

Binding and activation reuse the existing CardDataEncryption protocol with a request body containing only encrypted, iv, and tag.

The key is derived from the authenticated API Key, not the API Secret and not an uploaded public key.

See ApiPhysicalBindPayload and ApiPhysicalActivatePayload for the plaintext schema.

For either physical-card fulfillment mode:

• Bind uses {operation: "bind", cardId, cardNumber, timestamp}.
• Activate uses {operation: "activate", cardId, activationCode, pinCode, timestamp}.

timestamp is Unix milliseconds generated immediately before encryption and must stay within ±2 seconds of server time.

A ciphertext is single-use. If the operation result is unclear, query the operation status before retrying. Never reuse the same ciphertext.

Retry and Query Rules

Key Constraints 🚧

• Check the product's issuance capabilities before issuance.
• For c_015, both virtual and physical cards use flow=standard.
• Physical card fulfillment is selected through fulfillmentMode, not by changing flow.
• Use merchant_stock for merchant-owned physical stock and platform_delivery for platform-arranged delivery.
• Complete preparation and confirm isPrepared=true when the product requires preparation.
• Create card uses channelId; preparation and quote use cardChannelId. Both represent the same product ID.
• Both physical fulfillment modes use POST /cards to create the card record.
• Only platform delivery requires a quote and has a platform-delivery application.
• Use GET /cards?callId=... to query card records for either physical fulfillment mode.
• Use the physical application endpoint to track platform-delivery review, shipment, and refund progress.
• applicationId is specific to platform-delivery application flows; do not assume it exists for merchant-stock cards.
• A successful POST /cards creates a card record but does not mean the physical card has been bound or activated.
• Application or binding status bound does not mean activation succeeded; continue querying card and operation results.
• Activation codes arrive through Webhook. The 30-minute window refers to platform delivery/retry, not the bank-issued code's validity.
• Binding is irreversible. After failure, do not automatically bind another card or issue an automatic refund.
• For uncertain creation results, query the original callId before creating another card.
• isPrepared=true means preparation is ready; it does not guarantee successful card issuance.