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. Read one card or run the next card action
Use card detail lookup, status update, blocked-card appeal, no-pin payment 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>

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.

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

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
  • the upstream card UUID field used by transfer and withdrawal routes

2. Get Card By UUID

GET /api/v1/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/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 the payment provider 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

4. 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

5. Create Blocked Card Appeal

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

6. Get Blocked Card Appeal Status

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

7. 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

8. Update No-PIN Payment Amount

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

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

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

9. 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

10. 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
• The service sends the upstream 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