Card List
Flow Summary
The current virtual-card flow is:
Step 1. Finish card request approval
Start from Card Request
Step 2. Load the issued card listGET /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
| Name | Required | Notes |
|---|---|---|
page | No | Default 1 |
limit | No | Default 10 |
card_type | No | Common values include VIRTUAL and PHYSICAL |
status | No | Filters by the raw local card status. Current values include ACTIVE, FROZEN, BLOCKED, PRE_CANCEL, and PROCESSING |
search | No | Free-text search on card data |
Notes
- The list is scoped to the authenticated mobile user
- Results are returned in descending
created_atorder - The current backend status set exposed by this list includes both
PRE_CANCELandPROCESSING - The response contains local card records, including both:
- the local numeric
idused by routes such asupdate-status,transaction-limit, andshow-cvv-iframe - the upstream card UUID field used by transfer and withdrawal routes
- the local numeric
2. Get Card By UUID
GET /api/v2/cards/{uuid}
Returns one specific card record by UUID.
Important backend behavior
uuidmust 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_numberis 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
provideris optional- Current documented value is
UQPAY card_typeis optional- Current documented values include
VIRTUALandPHYSICAL
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_statuscan beACTIVE,FROZEN, orCANCELLEDcard_idis the local numeric card record ID- The card moves to
PROCESSINGuntil 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_idis the local numeric card record ID- The card must belong to the current user
- The route is IP-rate-limited to
10requests 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_idis the local numeric card record ID- The card must belong to the current user
- The response can include:
has_appeal_requestcard_statusrequest_idrequest_uuidstatusemail_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_idis requiredlimit_per_transactionis requiredlimit_per_transactionmust be>= 0
Important backend behavior
- The card must belong to the current user
- The card must be in local
ACTIVEstatus - 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_idis the local numeric card record ID- The card must belong to the current user
no_pin_payment_amountmust 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_idis 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