Card Issue

Goal: issue a virtual card for an existing cardholder or user. Issuance fees are charged when the order is created.

Review the encrypted request rules in Overview before starting.

Workflow steps

Create the card order
Provide product_id and either external_user_id or cardholder_id. Include the Idempotency-Key header.
Track the order
Poll until order.status is completed or failed.
Fetch card data (optional)
Retrieve the newly issued card details if you need them immediately.

API Endpoints

POST/api/v1/cards/createCreate the card issue order.
POST/api/v1/orders/checkTrack the order status and issue progress.
POST/api/v1/cards/getFetch card data after the order completes.

Schemas

CardIssueOrder

Field	Type	Required	Description
`order_id`	string	Required	Order identifier.
`order_type`	string	Required	Order type (card_issue, card_topup, etc.).
`status`	string	Required	Overall order status. Enum: `new`, `paid`, `activating`, `processing`, `completed`, `failed`
`created_at`	string	Required	Order creation time (ISO 8601).
`updated_at`	string	Optional	Last update time (ISO 8601).
`completed_at`	string	Optional	Completion time (ISO 8601).
`failed_at`	string	Optional	Failure time (ISO 8601).
`issue_status`	string	Optional	Sub-status for card issuance. Enum: `card_create_pending`, `card_create_done`, `card_create_error`, `initial_topup_pending`, `initial_topup_in_progress`, `initial_topup_error`, `initial_topup_done`, `initial_topup_verify_error`, `completed`
`is_issued`	boolean	Optional	Whether the card is issued successfully.
`provider_card_status`	string	Optional	Provider-level status string.

Error table

These are the most common error slugs when issuing cards.

Error Slug	Description
`idempotency_key_required`	Missing Idempotency-Key header.
`external_user_id_required`	external_user_id is required if cardholder_id is missing.
`product_not_found`	Card product not found.
`product_not_active`	Card product is not active.
`cardholder_not_found`	Cardholder not found.
`cardholder_not_ready`	Cardholder is not ready for issuance.
`insufficient_funds`	Master balance is too low for issue fees.
`invalid_pricing`	Pricing rules are misconfigured.
`card_product_limits_invalid`	Card product limits are invalid.