Sign in

v1

latestOpenAPI 3.0.22026-07-26123510445.2 KB
Card Lifecycle

Retrieve Card

Retrieves the details for a card you issued previously. The card's secure information are not returned in the response.

get/v1/issuing/cards/{id}

Path parameters

idstring uuid required
Example:b3d9d2d5-4c12-4946-a09d-953e82sed2b0

Universally unique identifier (UUID v4) of a resource.

Headers

x-on-behalf-ofstring

Specifies the sub-account on whose behalf the request is made. This should be set to the account_id, which can be retrieved via the List Connected Accounts API. If omitted or empty, the request is executed using the master account. More information at Connected Accounts.

Response

OK - Successfully retrieved a card.

card_idstring required

Unique identifier for the card.

card_binstring required

Card number prefix (BIN).

card_schemestring required

Card scheme.

card_currency'SGD' | 'USD' | 'XUSD'

The card currency.

card_numberstring required

Masked card number

form_factor'VIRTUAL' | 'PHYSICAL' required

Form of the card - VIRTUAL or PHYSICAL, currently only support virtual card.

mode_type'SHARE' | 'SINGLE' required

Mode type enum - SINGLE or SHARE.

  • SINGLE - A single card only has prepaid mode.
  • SHARE - A share card can have debit mode, meaning it is associated with debit program and account.
card_product_idstring uuid

The card product's unique identifier.

card_limitnumber required

The total credit limit assigned to the card, currency refer to card_currency. This is not a cumulative balance, but a fixed credit limit similar to that of a credit card.

Field behavior by card product:
  • Business Mastercard and Personal Visa: card_limit is required during card creation and must be greater than or equal to 0.01.
  • Business Visa: card_limit is optional.
    • If omitted, the system defaults card_limit to 0.
    • If provided, the value must be greater than or equal to 0, with up to two decimal places. Negative values are not allowed.

See Card products for the full capability matrix.

available_balancestring required

The available balance, currency refer to card_currency.

no_pin_payment_amountstring required

The allowable amount for card transactions without PIN verification, including the currency unit (e.g., 2000USD). This response field should be distinguished from the corresponding request parameter, which specifies the amount without a currency unit.

metadataMetadata

Any key-value object. Max length = 512 bytes. This must be valid JSON data.

card_status'PENDING' | 'ACTIVE' | 'FROZEN' | 'BLOCKED' | 'PRE_CANCEL' | 'CANCELLED' | 'LOST' | 'STOLEN' | 'FAILED' required

Card status enum. See the Card lifecycle and statuses guide for more information.

  • PENDING: The request to create the card has been received and is under review.
  • ACTIVE: The request to create the card was successful and the card is ready to use.
  • FROZEN: All incoming authorization requests will be declined. The card can be reactivated to accept new authorizations.
  • BLOCKED: The card was blocked by UQPAY due to suspicious activity.
  • PRE_CANCEL: The card is scheduled for cancellation and is in a waiting period during which all incoming authorization requests are declined. It transitions to CANCELLED when the waiting period ends.
  • CANCELLED: The card cannot be reactivated from this state, all incoming authorization requests will be permanently declined.
  • LOST: The card has been reported as lost to UQPAY.
  • STOLEN: The card has been reported as stolen to UQPAY.
  • FAILED: The request to create a card using Create Card failed.
update_reasonstring

The reason for updating card status.

consumed_amountstring

Reflects the cumulative amount of the card limit that has already been used.

Example response

{
  "card_id": "c0cef051-29c5-4796-b86a-cd5b684bfad7",
  "card_bin": "40963608",
  "card_scheme": "VISA",
  "card_currency": "USD",
  "card_number": "************5668",
  "form_factor": "VIRTUAL",
  "mode_type": "SHARE",
  "card_product_id": "3bd1656b-e691-4aab-a76a-3ead39e7a6f6",
  "card_limit": 2100.02,
  "cardholder": {
    "cardholder_id": "7c4ff2cd-1bf6-4aaa-bf16-266771425011",
    "email": "demo@example.com",
    "number_of_cards": 1,
    "first_name": "Emily",
    "last_name": "Toy",
    "create_time": "2024-05-09 15:52:23",
    "date_of_birth": "1990-01-01",
    "country_code": "SG",
    "phone_number": "86683306",
    "gender": "MALE",
    "nationality": "SG",
    "residential_address": {
      "country": "SG",
      "state": "Singapore",
      "city": "Singapore",
      "district": "Buona Vista",
      "line1": "9 N Buona Vista Dr",
      "line2": "THE METROPOLIS",
      "line_en": "9 N Buona Vista Dr, THE METROPOLIS",
      "postal_code": "138666"
    },
    "review_status": "SUCCESS",
    "idv_verification_url": "https://idv.sumsub.com/verify/abc123",
    "idv_url_expires_at": "2026-04-10T10:00:00+08:00"
  },
  "spending_controls": [
    {
      "amount": "100.03",
      "interval": "PER_TRANSACTION"
    }
  ],
  "no_pin_payment_amount": "2000USD",
  "risk_controls": {
    "enable_3ds": "Y",
    "allow_3ds_transactions": "Y",
    "blocked_mcc": [
      "5999",
      "6011"
    ]
  },
  "network_protection": {
    "enabled": true,
    "card_scheme": "VISA",
    "action_code": "41",
    "definition": "Lost card, pickup",
    "status": "ENROLL_PENDING",
    "submitted_time": "2026-05-14T09:00:00Z"
  },
  "metadata": {
    "key1": "value1",
    "key2": "value2"
  },
  "card_status": "ACTIVE",
  "consumed_amount": "51.00"
}