Card Issuance Flow and Physical Card Fulfillment Modes Updated

• Effective Date: 2026-11-13 (UTC+8)
• Scope: Card Issuance / CaaS Open API

---

[API] New Physical Card Issuance: Merchant Stock and Platform Delivery

Physical card issuance is now supported through POST /cards, with two fulfillment modes:

• merchant_stock: Use this mode when you already hold physical card stock purchased offline and distribute the cards to your users.
• platform_delivery: Use this mode when DogPay handles the physical card application, review and shipment.

Both modes create a physical card record first. After the user receives the physical card, complete binding and activation using the same cardId.

Choose Your Issuance Flow

Start by calling GET /cards/bins to discover the available card products and their issuance capabilities.

Check issuance.virtual or issuance.physical for the selected product. If requiresPreparation=true, complete the preparation process until isPrepared=true. Otherwise, skip preparation.

For physical cards, select a fulfillment mode only from the product's advertised fulfillmentModes. Do not assume that every physical card product supports both modes.

Merchant Stock

Use merchant_stock when you already hold physical card stock purchased offline.

1. Query preparation with cardType=physical and fulfillmentMode=merchant_stock, if preparation is required.
2. Call POST /cards with cardType=physical and cardOptions.fulfillmentMode=merchant_stock.
3. Save the returned card identifier as cardId.
4. After the user receives the card, complete binding and activation.

No physical delivery quote, platform delivery application or platform inventory reservation is required.

Any applicable card issuance fee is handled according to the configured product pricing. Binding does not require a separate card issuance fee.

Platform Delivery

Use platform_delivery when DogPay handles the physical card application and delivery.

1. Query preparation with cardType=physical and fulfillmentMode=platform_delivery, if preparation is required.
2. Call POST /cards/physical/quote with the recipient's shipping address.
3. Review the returned createFee, shippingFee, totalFee and expiresAt.
4. Call POST /cards with cardType=physical, cardOptions.fulfillmentMode=platform_delivery and the returned applicationId as cardOptions.physicalApplicationId.
5. Query GET /cards/physical/application to check application review and shipment progress.
6. After the user receives the card, complete binding and activation.

Obtaining a quote does not debit funds or reserve platform inventory. Card creation charges the quoted issuance and shipping fees. If the application is rejected during review, the applicable fees are refunded.

Bind and Activate Physical Cards

The following steps apply to both physical-card fulfillment modes:

1. Call POST /cards/physical/bind using the physical card's cardId and the received card details.
2. Query GET /cards/physical/operation to confirm the binding result.
3. Receive the activation code through the card.physical.activation.code Webhook.
4. Let the user set a six-digit PIN, then call POST /cards/physical/activate.
5. Query the card or operation status to confirm that the card is active.

Configure your activation-code Webhook before starting the binding process. Binding and activation requests must use the documented encrypted payload.

Store and process activation codes securely when they are received. Creating a card, completing binding or receiving an activation code does not by itself mean the card is active. Confirm the final card status before treating the card as ready for use.

Retry Safely

• Save your callId before creating a card.
• If the result of POST /cards is uncertain, query GET /cards?callId=... using the original callId before submitting another creation request.
• If a creation retry is required, follow the documented idempotency rules and use the original callId and issuance parameters.
• For pending or unknown operations, query their status before retrying.
• Binding is irreversible and cannot be undone or reassigned.
• A virtual card cardId cannot be used for physical card binding.

Updated Guides

[Guides] Card Product Discovery and Issuance Preparation

The product discovery and issuance preparation guide has been updated:

• Added fulfillmentModes discovery guidance.
• Documented preparation requirements for merchant_stock and platform_delivery.
• Clarified that preparation is required only when the product declares requiresPreparation=true.
• Explained that merchant-stock cards do not require a quote and can be created directly through POST /cards after any required preparation.
• Retained material submission, preview and isPrepared=true handling rules.

[Guides] Card Issuance Guide

The card issuance guide has been updated to cover the virtual and physical card flows:

• Clarified that both virtual and physical cards use flow=standard when declared by the product.
• Added separate issuance instructions for merchant_stock and platform_delivery.
• Removed the legacy physical/apply application step.
• Added physical-card creation parameters, quote handling, binding and activation instructions.
• Clarified the account-level callId namespace and the correct card/application query endpoints.
• Updated retry guidance, irreversible binding constraints and activation-code Webhook handling.

[Guides] Card Dictionary and Issuance Error Codes

Added card issuance error-code guidance to the Card dictionary while retaining the existing Card Transaction Type and Transaction Reason Code dictionaries.

The new guidance covers resource ownership, preparation state, quotes, stock, binding and encryption handling.

---

Thank you for choosing DogPay! If you encounter any issues or need assistance during integration, please feel free to reach out to the technical support team.