Cards

Card Request

Create a new card request and track its latest request status.

Flow Summary

The current card request flow is:

Step 1. Complete KYC and cardholder setup Use KYC first

Step 2. Create the card requestPOST /api/v2/card-request

Step 3. Check the latest summary statusGET /api/v2/card-request/status

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

Authorization: Bearer <access_token>

Important Prerequisite

The backend does not allow a card request unless the current mobile user already has a card_holder record with:

card_status = SUCCESS

In practice, that means the user must already have completed the KYC/cardholder flow successfully before POST /api/v2/card-request can work.

For v2, the user must already have a successful UQPay cardholder.

If no successful cardholder exists, the request fails.

1. Create Card Request

POST /api/v2/card-request

This route is protected and also IP-rate-limited to 60 requests per minute.

Request

{
  "card_type": "VIRTUAL",
  "country_id": 114,
  "address": "1 Raffles Place",
  "city": "Singapore",
  "state": "Singapore",
  "post_code": "048616"
}

URL Query Parameters:

  • method (required): Payment method
    • agent-pay: Agent pays on behalf of user using agent's prepaid balance

Request rules

  • card_type is required
  • Current enum values are VIRTUAL and PHYSICAL
  • country_id is required
  • address is required
  • city is optional
  • state is optional
  • post_code is required
  • post_code can be sent as a string or number, but sending a string is safer if leading zeroes matter
  • post_code must contain digits only
  • post_code must be 4 to 20 characters long
  • method is a required URL parameter and must be agent-pay

Request behavior

  • user association is derived from the authenticated access token; clients do not send it directly
  • The service generates a unique merchant_order_sn in the format HTP-<uuid>
  • The initial record is created with:
    • card_status = AWAITING_PAYMENT
    • admin_status = PENDING
    • request_by = MOBILE

Payment Methods

Agent Payment (agent-pay):

  • Payment is automatically deducted from agent's prepaid balance
  • Card request is immediately approved
  • Card creation starts right away
  • No payment order processing required

Success response

{
  "status_code": 201,
  "message": "Success",
  "data": {
    "id": 42,
    "uuid": "5e5d4990-2241-46dc-9dbd-8abcf97e6061",
    "card_status": "PROCESSING",
    "payment_status": "SUCCESS",
    "admin_status": "APPROVED",
    "merchant_order_sn": "HTP-8c2af6ac-7d58-4b1e-8bb7-3ee80f7a9d64",
    "card_type": "VIRTUAL",
    "country_id": 114,
    "address": "1 Raffles Place",
    "post_code": "048616"
  }
}

2. List Card Requests

GET /api/v2/card-request

Lists the current user’s card requests with pagination.

Query parameters

NameRequiredNotes
pageNoDefault 1
limitNoDefault 10
statusNoFilters by card_status

Success response shape

{
  "status_code": 200,
  "message": "Success",
  "data": [
    {
      "id": 42,
      "card_status": "AWAITING_PAYMENT",
      "created_at": "2026-02-28T10:00:00Z",
      "card_type": "VIRTUAL",
      "payment_status": "PENDING"
    }
  ],
  "metadata": {
    "current_page": 1,
    "limit": 10,
    "total": 1
  }
}

Notes

  • The list is filtered to the authenticated mobile user
  • Results are sorted by created_at DESC
  • The status filter applies to the raw card_status field, not the computed summary status from /status

3. Get Card Request By UUID

GET /api/v2/card-request/{uuid}

Returns the full request details for one specific card request owned by the current user, including card details if the card has been successfully created.

4. Get Latest Card Request Status

GET /api/v2/card-request/status

Returns the latest request status summary for the authenticated user.

Query parameter

  • card_type is optional
  • Common values include VIRTUAL and PHYSICAL
  • provider is optional
  • Supported value is UQPAY
  • If provider is omitted, the backend defaults to UQPAY

Important backend behavior

  • This route reads the authenticated mobile user from the auth context
  • It returns the latest status summary rather than the full request detail payload
  • Use this route for lightweight “what is my latest card request state?” polling
  • If the user has not submitted a card request yet, the API can return a not-found style status payload
  • For physical-card requests, the summary can return PROCESSING when the request is already being created and an activation code exists
  • The v2 summary response does not embed the final card object; use GET /api/v2/card-request/{uuid} for full detail

Response structure

The response has two parts:

  1. Computed summary status:
    • status: high-level state for polling
    • Common values are APPROVED, PENDING, FAILED, PROCESSING, and NOT_FOUND
  2. Card Request Details (returned when a matching request exists):
    • id: Local database ID
    • uuid: Card request UUID
    • payment_status: Payment status (PENDING, SUCCESS, EXPIRED, FAILED)
    • card_status: Card request status (AWAITING_PAYMENT, PROCESSING, SUCCESS, FAILED)
    • admin_status: Admin approval status
    • card_type: VIRTUAL or PHYSICAL
    • merchant_order_sn: Merchant order serial number
    • country_id, address, post_code: Request details (post_code is returned as a string in v2)

Success response examples

When card is still being processed:

{
  "status_code": 200,
  "message": "Success",
  "data": {
    "status": "PROCESSING",
    "card_request": {
      "id": 42,
      "uuid": "5e5d4990-2241-46dc-9dbd-8abcf97e6061",
      "payment_status": "SUCCESS",
      "card_status": "PROCESSING",
      "admin_status": "APPROVED",
      "merchant_order_sn": "HTP-8c2af6ac-7d58-4b1e-8bb7-3ee80f7a9d64",
      "card_type": "PHYSICAL",
      "country_id": 114,
      "address": "1 Raffles Place",
      "post_code": "048616"
    }
  }
}

When no matching request exists yet:

{
  "status_code": 200,
  "message": "Success",
  "data": {
    "status": "NOT_FOUND"
  }
}

Important behavior notes

  • This route is a polling summary endpoint, not the full detail endpoint
  • For full card-request detail, use GET /api/v2/card-request/{uuid}
  • The summary payload is provider-aware in v2 through the optional provider query parameter
  • post_code is documented as a string in v2 responses

Common failures

  • 404: request not found for this user/agent
  • 401: auth context missing

Integration Notes

  1. Do not treat POST /card-request as the whole card issuance result; it only creates the request.
  2. Use /card-request/{uuid} to get the full detail screen for a specific request.
  3. Poll card creation status:
    • For agent-pay: Card creation starts immediately after request
    • When you need the actual card object, use /card-request/{uuid} instead of /card-request/status
    • Recommended polling interval: 2-5 seconds
Copyright © 2026