Card Top-Ups

Flow Summary

The top-up flow is:

Step 1. Make sure the source card is active Use Card List to confirm card status first

Step 2. Start a top-up Use POST /api/v1/card-topup

Step 3. Check the top-up record Use GET /api/v1/card-topup

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

Authorization: Bearer <access_token>

1. Create Card Top-Up

POST /api/v1/card-topup

Creates a new top-up order for a card.

Request

{
  "amount": 100.00,
  "card_id": 508
}

URL Query Parameters:

• method (optional): Payment method
  • agent_pay: Agent pays on behalf of user using agent's prepaid balance
  • user_pay: User pays directly via payment gateway (default)

Request rules

• amount is required
• card_id is required
• card_id is the local numeric card record ID
• method is optional URL parameter, defaults to user_pay if not provided

Important backend behavior

• The card must belong to the current user
• The card must currently be ACTIVE
• The input amount is treated as the user's USDT funding amount
• Fees, adjusted exchange rate, and the final net amount are calculated server-side
• The new top-up row is created with status = PENDING
• After the DB row is created, the service makes a synchronous RPC call to create a payment order

Success response

{
  "status_code": 201,
  "message": "Success",
  "data": {
    "id": 123,
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "card_id": "508",
    "amount": "100.00",
    "amount_usdt": "100.00",
    "net_amount": "99.20",
    "top_up_fee": "0.80",
    "exchange_rate": 0.998857,
    "status": "PENDING",
    "merchant_order_sn": "HTP-550e8400-e29b-41d4-a716-446655440000",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Response fields:

• id: Local database ID
• uuid: Top-up unique identifier
• card_id: Card ID (as string)
• amount: Gross amount in cents, formatted to 2 decimal places
• amount_usdt: USDT amount from user
• net_amount: Net amount after fee, formatted to 2 decimal places
• top_up_fee: Fee charged for top-up, formatted to 2 decimal places
• exchange_rate: Exchange rate applied at time of top-up
• status: Top-up status (PENDING, SUCCESS, FAILED, etc.)
• merchant_order_sn: Unique merchant order reference for payment tracking
• created_at: ISO 8601 timestamp

2. List Card Top-Ups

GET /api/v1/card-topup

Lists top-up records with pagination.

Query parameters

Important backend caveat

• The current repository implementation is not explicitly scoped to the authenticated mobile user
• In practice, this behaves more like a shared top-up list filtered only by the provided query params
• Clients should treat this as an implementation gap and avoid assuming strict user-only isolation until the backend is tightened