Cards

Card List

List issued cards and manage shared card controls used most often with virtual cards.

Flow Summary

The current virtual-card flow is:

Step 1. Finish card request approval
Start from Card Request

Step 2. Load the issued card list
GET /api/v2/cards

Step 3. Read one card or run the next card action
Use card detail lookup, status update, blocked-card appeal, no-pin payment update, limit update, or secure iframe reveal

Step 4. Load schema or dev/simulation helpers when needed
Use GET /api/v2/cards/schema, POST /api/v2/cards/simulation/validate, or POST /api/v2/cards/dev/{uuid}/block

All routes below should be treated as protected routes and sent with:

Authorization: Bearer <access_token>

1. List Issued Cards

GET /api/v2/cards

Returns the current mobile user's cards with pagination and optional filtering. Use card_type=VIRTUAL when you want the virtual-only view.

Important: A user can have up to 5 non-cancelled cards. Once that limit is reached, the backend rejects new card creation or assignment flows.

Query parameters

NameRequiredNotes
pageNoDefault 1
limitNoDefault 10
card_typeNoCommon values include VIRTUAL and PHYSICAL
statusNoFilters by the raw local card status. Current values include ACTIVE, FROZEN, BLOCKED, PRE_CANCEL, and PROCESSING
searchNoFree-text search on card data

Notes

  • The list is scoped to the authenticated mobile user
  • Results are returned in descending created_at order
  • The current backend status set exposed by this list includes both PRE_CANCEL and PROCESSING
  • The response contains local card records, including both:
    • the local numeric id used by routes such as update-status, transaction-limit, and show-cvv-iframe
    • the upstream card UUID field used by transfer and withdrawal routes

2. Get Card By UUID

GET /api/v2/cards/{uuid}

Returns one specific card record by UUID.

Important backend behavior

  • uuid must be a valid card UUID
  • The handler returns the local card record shape used by the list endpoint
  • This is the cleanest route for card detail screens that start from a previously selected card UUID

3. Get Card By Card Number

POST /api/v2/cards/get-by-number

Looks up a card by its 16-digit card number.

Request

{
  "card_number": "4111111111111111"
}

Request rules

  • card_number is required
  • It must be exactly 16 digits
  • It must be numeric only

Usage note

  • Use this route in controlled support or assisted lookup flows
  • For normal user-facing card screens, prefer the card UUID routes from the authenticated card list

4. Get Card Fee Schema

GET /api/v2/cards/schema

Returns the card fee schema for the selected provider and card type.

Query parameters

  • provider is optional
  • Current documented value is UQPAY
  • card_type is optional
  • Current documented values include VIRTUAL and PHYSICAL

Notes

  • Use this route when the app needs the current card pricing matrix before card creation
  • This route is available in v2 even though older docs usually skipped it

5. Update Card Status

POST /api/v2/cards/update-status

Freezes, unfreezes, or cancels a card.

{
  "card_id": 508,
  "card_status": "FROZEN"
}
  • card_status can be ACTIVE, FROZEN, or CANCELLED
  • card_id is the local numeric card record ID
  • The card moves to PROCESSING until the card provider confirms the change

See Card Status for the status reference, status flow, freeze / unfreeze / cancel examples, balance handling on cancellation, and errors.

6. Create Blocked Card Appeal

POST /api/v2/cards/blocked-appeal

Creates a blocked-card appeal for a card owned by the authenticated user.

Request

{
  "card_id": 508,
  "request_message": "Please review and unblock this card."
}

Important backend behavior

  • card_id is the local numeric card record ID
  • The card must belong to the current user
  • The route is IP-rate-limited to 10 requests per minute
  • The backend stores the appeal request and sends it onward using the configured system email flow
  • The route is intended for blocked-card recovery cases, not as a generic support form

7. Get Blocked Card Appeal Status

GET /api/v2/cards/blocked-appeal/status/{card_id}

Checks whether the current user has already submitted a blocked-card appeal for the selected card.

Important backend behavior

  • card_id is the local numeric card record ID
  • The card must belong to the current user
  • The response can include:
    • has_appeal_request
    • card_status
    • request_id
    • request_uuid
    • status
    • email_status

8. Update Transaction Limit

POST /api/v2/cards/transaction-limit

Queues a per-transaction spending limit update for a card.

Request

{
  "card_id": 508,
  "limit_per_transaction": 250
}

Request rules

  • card_id is required
  • limit_per_transaction is required
  • limit_per_transaction must be >= 0

Important backend behavior

  • The card must belong to the current user
  • The card must be in local ACTIVE status
  • If the card is already PROCESSING, the service rejects the change
  • The handler converts the submitted value into cents before sending it downstream
  • Like status updates, this change is processed asynchronously and the local card is moved to PROCESSING

9. Update No-PIN Payment Amount

POST /api/v2/cards/no-pin-payment

Updates the maximum amount that can be approved on the card without entering a PIN.

10. Validate Card For Simulation

POST /api/v2/cards/simulation/validate

Validates a card for the public payment simulation page.

Notes

  • This is a v2-only helper endpoint
  • Use it only for simulation or demo flows, not for normal card-management UI

11. Dev Card Status Block Toggle

POST /api/v2/cards/dev/{uuid}/block

Changes a card status to BLOCKED or ACTIVE for development and testing only.

Important backend behavior

  • This route is intended only for development and testing
  • It is not part of normal production user flows
  • The request uses the card UUID in the path, not the local numeric card ID

Request

{
  "card_id": 508,
  "no_pin_payment_amount": 50
}

Important backend behavior

  • card_id is the local numeric card record ID
  • The card must belong to the current user
  • no_pin_payment_amount must be >= 0
  • The API returns a message-only payload in data.message

12. Show CVV In Secure Iframe

POST /api/v2/cards/show-cvv-iframe

Returns a secure iframe URL for card-data viewing.

Request

{
  "card_id": 508
}

Response shape

{
  "status_code": 200,
  "message": "Iframe URL retrieved successfully",
  "data": {
    "iframe_url": "https://..."
  }
}

Important backend behavior

  • card_id is the local numeric card record ID
  • The card must belong to the current user
  • If the upstream response does not include a usable iframe_url, the request fails
  • This is the supported way to display sensitive card data: the client renders the hosted secure frame instead of handling raw PAN/CVV values directly
Copyright © 2026