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 list
GET /api/v1/cards

Step 3. Run the next card action
Use status update, limit update, CVV lookup, or secure iframe reveal

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

Authorization: Bearer <access_token>

Most write endpoints below also pass through DecryptField(), so they accept either plain JSON or the encrypted wrapper described in Overview.

1. List Issued Cards

GET /api/v1/cards

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

Query parameters

Notes

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

2. Get Card By Card Number

POST /api/v1/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

Important backend behavior

• This route is protected, but the service first queries UQPay by card number
• After that upstream lookup, the service finds the local card by returned upstream card_id
• The current implementation does not document a strict ownership filter at that final lookup step, so do not assume it is as tightly scoped as GET /api/v1/cards

3. Update Card Status

POST /api/v1/cards/update-status

Queues a card-status change such as freeze, cancel, or re-activate.

Request

{
  "card_id": 508,
  "card_status": "FROZEN"
}

Request rules

• card_id is required
• card_id is the local numeric card record ID
• card_status is required
• Current allowed values are ACTIVE, FROZEN, and CANCELLED

Important backend behavior

• The card must belong to the current user
• The route is IP-rate-limited to 60 requests per minute
• If the card is already in local PROCESSING state, the service rejects the change
• The service publishes the change request to an async queue, then immediately marks the local card as PROCESSING
• The handler currently returns the static success message Card successfully frozen even when the requested status is not FROZEN

4. Update Transaction Limit

POST /api/v1/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 queued asynchronously and the local card is moved to PROCESSING

5. Show CVV

POST /api/v1/cards/show-cvv

Fetches live sensitive card data for a card.

Request

{
  "card_id": 508
}

Notes

• card_id is the local numeric card record ID
• The card must belong to the current user
• The service then calls an internal webhook to fetch the upstream card data
• This endpoint is the one intended for CVV reveal, so treat the returned data as sensitive and avoid caching it on the client

6. Show CVV In Secure Iframe

POST /api/v1/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

• This route uses the same request body as show-cvv
• card_id is the local numeric card record ID
• The card must belong to the current user
• Unlike show-cvv, this route does not pass through DecryptField(), so send plain JSON
• The service sends the upstream UQPay card ID plus the current request language to an RPC route
• If the upstream RPC succeeds but returns an empty iframe_url, the handler still converts that into a server error
• Use this endpoint when the client should display sensitive card data inside a hosted secure frame instead of handling raw PAN/CVV values directly