Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers-sandbox.uqpaytech.com/llms.txt

Use this file to discover all available pages before exploring further.

A one-time card is a virtual card that automatically cancels itself after a single transaction event you choose at creation — either the first approved authorization or the first successful capture (settlement). After the card cancels, any unused balance is released back to your issuing balance, and the card cannot be reactivated.

​
When to use a one-time card

ScenarioWhy a one-time card fits
Single SaaS or API chargeCard auto-cancels after the charge, so the merchant cannot silently rebill or convert the trial into a subscription.
Per-trip travel or one-off reimbursementLimit is locked at creation and the card disappears after use, simplifying control and reconciliation.
Anti-fraud for one-shot paymentsEven if the card number leaks after the transaction, it cannot be used again.

​
How a one-time card differs from a standard card

BehaviorStandard cardOne-time card
Number of transactionsMultipleOne transaction event, then cancelled
LimitAdjustable; supports recharge and withdrawLocked at creation; no recharge, withdraw, or limit change
CancellationManual cancellation onlyAuto-cancellation on trigger event or at expiry_at
Reuse after cancelCard cannot be reactivatedCard cannot be reactivated

​
Supported card BINs

One-time cards are available on selected card BINs only. To work with one-time cards in sandbox, use product BIN 40963608. For production, contact your UQPAY account manager to confirm which BINs on your account have one-time card enabled. If you call Create Card with usage_type: ONE_TIME against a BIN that does not have the feature enabled, the request is rejected.

​
Create a one-time card

Send the same Create Card request you would for a standard card, plus three additional fields:
FieldWhen requiredDescription
usage_typeTo issue a one-time card, set to ONE_TIME. Defaults to NORMAL.Selects between standard and one-time card.
auto_cancel_triggerWhen usage_type is ONE_TIMEThe transaction event that auto-cancels the card. See Cancel-trigger modes.
expiry_atWhen usage_type is ONE_TIMEAbsolute date-time after which the card auto-cancels if no qualifying transaction has occurred. Must be in the future.

​
Example

curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cards \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{
    "cardholder_id": "3a1d3ce4-977b-4f1d-8076-8d2dd59e942c",
    "card_product_id": "467e993f-317a-49fc-9ea0-bf49de7d1f76",
    "card_currency": "USD",
    "card_limit": 50,
    "usage_type": "ONE_TIME",
    "auto_cancel_trigger": "ON_AUTH",
    "expiry_at": "2026-12-31T23:59:59+08:00"
  }'
Response: 
{
  "card_order_id": "2ee8b7c4-9458-4c6a-90cc-7f4cb4299b73",
  "card_id": "246c1e6a-90ba-4968-9b41-3a5a09395391",
  "cardholder_id": "3a1d3ce4-977b-4f1d-8076-8d2dd59e942c",
  "card_status": "PENDING",
  "order_status": "PROCESSING",
  "create_time": "2026-04-27T15:32:17+08:00"
}
The card starts in PENDING status. Within seconds, it transitions to ACTIVE and is ready for the single transaction.

​
Cancel-trigger modes

Pick one mode at creation. The card cannot switch modes later.

​
ON_AUTH — cancel after the first approved authorization

Choose this when you want the card to be unusable the moment it is authorized once. As soon as one authorization is approved, the card is cancelled. Any subsequent authorization on the same card — including from the same merchant — is declined.

​
ON_CAPTURE — cancel after the first successful capture

The card stays usable until the first authorization clears (settles). During the window between authorization and capture, the card is locked to the merchant of the first approved authorization: that merchant can re-authorize on the same card (for example, to adjust the amount or retry), and any of those authorizations will be approved as long as the available balance allows. Authorizations from any other merchant are declined. After the first capture clears, the card is cancelled.

​
Decision summary

Trigger modeFirst authorizationSame-merchant re-authorization (before capture)Other-merchant authorizationCard cancels at
ON_AUTHApproved (if balance sufficient)DeclinedDeclinedFirst approved authorization
ON_CAPTUREApproved (if balance sufficient); merchant is locked to this cardApproved (if balance sufficient)DeclinedFirst successful capture
Verification authorizations under USD 1 (or the equivalent in another currency) are intentionally excluded from the trigger so that customers can complete card-on-file binding before the real charge.

​
Operations not allowed on a one-time card

The following endpoints reject one-time cards with HTTP 400: Example response: 
{
  "code": "400",
  "message": "This operation cannot be performed on One-Time Card."
}

​
What happens after a one-time card is cancelled

  • The card transitions directly to CANCELLED and cannot be reactivated. It does not pass through the PRE_CANCEL intermediate state used when a standard card is manually cancelled.
  • Any unused available balance is released back to your issuing balance automatically.
  • The card record is retained and can be retrieved by card_id for reconciliation.
  • Refunds and reversals are still accepted on the cancelled card; the refunded amount is credited to your issuing balance, not to the cancelled card.

​
Fees and quotas

  • Card-count quotas are shared with standard cards. A one-time card consumes one slot from the same per-cardholder and per-account card limits.

​
FAQ

No. Once the trigger fires (or expiry_at is reached), the card is permanently cancelled and cannot be reactivated.
ON_CAPTURE mode locks the card to the merchant of the first approved authorization. If the second authorization came from a different merchant, it is declined by design. Authorizations from the same merchant continue to be approved until the first capture clears.
Yes. Refunds and reversals on a cancelled one-time card are accepted; the refunded amount is credited to your issuing balance.