Card Topup

Goal: add funds to a card. The total amount (topup plus fees) is charged to the master balance when the order is created.

Review the encrypted request rules in Overview before starting.

Workflow steps

Create the topup order
Submit the topup request with card_id and amount. Include the Idempotency-Key header.
Track the order
Poll until the order reaches completed or failed.

API Endpoints

POST/api/v1/cards/topupCreate the topup order.
POST/api/v1/orders/checkTrack the topup order status.

Schemas

CardTopupOrder

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`, `activating`, `processing`, `completed`, `failed`
`card_id`	string	Optional	Related card identifier, if applicable.
`balance_before`	string	Optional	Project balance before this order (decimal string).
`balance_after`	string	Optional	Project balance after this order (decimal string).
`last_error`	string	Optional	Last error message when status is failed.
`last_error_slug`	string	Optional	Machine-readable error code.
`data`	object	Required	Order-specific data payload.
`created_at`	string	Required	Order creation time (ISO 8601).
`completed_at`	string	Optional	Completion time (ISO 8601).
`failed_at`	string	Optional	Failure time (ISO 8601).
`topup_status`	string	Optional	Sub-status for topup processing. Enum: `new`, `provider_in_progress`, `new_error`, `provider_in_progress_error`, `provider_verification`, `provider_verification_error`, `completed`, `failed`

Error table

These error slugs are the most common when topping up cards.

Error Slug	Description
`idempotency_key_required`	Missing Idempotency-Key header.
`invalid_amount`	Topup amount is invalid.
`amount_below_minimum`	Amount is below the minimum allowed.
`amount_above_maximum`	Amount is above the maximum allowed.
`card_not_found`	Card not found.
`card_not_active`	Card is not active.
`currency_mismatch`	Topup currency does not match card currency.
`insufficient_funds`	Master balance is too low for topup and fees.
`invalid_pricing`	Pricing rules are misconfigured.