Card Product Discovery and Issuance Preparation

Position in the Flow

flowchart TD
    A["List card products"] --> B["Identify card form and capabilities"]
    B --> C["Create or reuse cardholder"]
    C --> D{"requiresPreparation?"}
    D -- "true" --> E["Complete preparation"]
    E --> F["isPrepared=true"]
    D -- "false" --> G["Skip preparation"]
    F --> H["Proceed to issuance"]
    G --> H
    H --> I{"Card form and fulfillment mode"}
    I -- "Virtual card" --> J["POST /cards"]
    I -- "Physical: merchant_stock" --> K["POST /cards"]
    I -- "Physical: platform_delivery" --> L["Quote → POST /cards"]

Step 1: Identify the Card Product

Call List available card products, then inspect issuance.virtual or issuance.physical for the requested card form.

1.1 Determine the Issuance Flow

Important: c_015 issuance rules

Both c_015 virtual and physical cards use flow=standard.

For c_015 physical cards, the fulfillment mode determines the subsequent process:

Check the product's returned fulfillmentModes to determine which fulfillment modes are supported. Do not assume every physical card product supports both modes.

1.2 Product ID Mapping

The product id returned by GET /cards/bins is used under different parameter names:

These parameters refer to the same product ID.

Step 2: Create or Reuse the Cardholder

Save the returned holder ID and pass it as cardHolderId in subsequent operations where required.

For c_015 enterprise holders, valid names, email, phone number, and calling code are required before preparation.

Step 3: Complete Issuance Preparation

Skip this step when the selected product and card form return requiresPreparation=false.

3.1 Query Preparation Readiness

Call Get card preparation.

Fulfillment mode selection

For physical cards, specify the intended fulfillment mode when querying preparation:

• merchant_stock: The merchant provides the physical card.
• platform_delivery: The platform arranges physical card fulfillment and delivery.

For c_015 physical cards, explicitly pass fulfillmentMode=merchant_stock when using merchant-owned stock. Do not rely on the default value.

If fulfillmentMode is omitted, the API default is platform_delivery. Always verify the selected mode against the product's supported fulfillmentModes.

preparation.requiredContextFields describes the context required for the preparation query, not the material fields to submit.

If missingContextFields is returned, provide the missing context and query again. No preparation record or form URL is created until the required context is complete.

Read steps, requirements, revision, nextAction, and form availability.

Identify steps using steps[].type together with steps[].id. The current steps[].type is holder; do not use form.type as a template identifier.

3.2 Submit Materials

3.3 Handle the Preparation Result

Changing local names or contact details does not update a bank-registered holder identity.

If a mismatch occurs, compare records through preview, restore the original local details, or contact technical support. Do not overwrite the bank identity automatically.

Stage Constraints

• The product id is cardChannelId in preparation and quote, and channelId in create card. Both represent the same product ID.
• For c_015, both virtual and physical cards use flow=standard.
• Physical card fulfillment is selected through fulfillmentMode, not by changing flow.
• For merchant-owned physical stock, explicitly pass fulfillmentMode=merchant_stock.
• For platform delivery, use fulfillmentMode=platform_delivery and follow the quote → create flow.
• Do not send accountId to select an account. Use dgp-entity-id for child-account operations.
• Product discovery, preparation, issuance, and subsequent queries must use the same dgp-entity-id.
• isPrepared=true means preparation is ready; it does not guarantee successful card issuance.
• Preparation materials are submitted as a complete snapshot. Incremental submission is not supported.