Card Request
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 methodagent-pay: Agent pays on behalf of user using agent's prepaid balance
Request rules
card_typeis required- Current enum values are
VIRTUALandPHYSICAL country_idis requiredaddressis requiredcityis optionalstateis optionalpost_codeis requiredpost_codecan be sent as a string or number, but sending a string is safer if leading zeroes matterpost_codemust contain digits onlypost_codemust be 4 to 20 characters longmethodis a required URL parameter and must beagent-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_snin the formatHTP-<uuid> - The initial record is created with:
card_status = AWAITING_PAYMENTadmin_status = PENDINGrequest_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
| Name | Required | Notes |
|---|---|---|
page | No | Default 1 |
limit | No | Default 10 |
status | No | Filters 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
statusfilter applies to the rawcard_statusfield, 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_typeis optional- Common values include
VIRTUALandPHYSICAL provideris optional- Supported value is
UQPAY - If
provideris omitted, the backend defaults toUQPAY
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
PROCESSINGwhen the request is already being created and an activation code exists - The v2 summary response does not embed the final
cardobject; useGET /api/v2/card-request/{uuid}for full detail
Response structure
The response has two parts:
- Computed summary status:
status: high-level state for polling- Common values are
APPROVED,PENDING,FAILED,PROCESSING, andNOT_FOUND
- Card Request Details (returned when a matching request exists):
id: Local database IDuuid: Card request UUIDpayment_status: Payment status (PENDING, SUCCESS, EXPIRED, FAILED)card_status: Card request status (AWAITING_PAYMENT, PROCESSING, SUCCESS, FAILED)admin_status: Admin approval statuscard_type: VIRTUAL or PHYSICALmerchant_order_sn: Merchant order serial numbercountry_id,address,post_code: Request details (post_codeis 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
providerquery parameter post_codeis documented as a string in v2 responses
Common failures
404: request not found for this user/agent401: auth context missing
Integration Notes
- Do not treat
POST /card-requestas the whole card issuance result; it only creates the request. - Use
/card-request/{uuid}to get the full detail screen for a specific request. - 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
- For