Card Transfers

Flow Summary

The transfer flow is:

Step 1. Make sure both cards are active Use Card List to confirm card status first

Step 2. Start a transfer Use POST /api/v1/cards/transfer

Step 3. Check the transfer record Use GET /api/v1/cards/transfer/{id}

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

Authorization: Bearer <access_token>

1. Create Card Transfer

POST /api/v1/cards/transfer

Transfers balance from one card to another.

Request

{
  "source_card_uuid": "5e5d4990-2241-46dc-9dbd-8abcf97e6061",
  "destination_card_uuid": "6f77454d-400f-4ec4-8e2c-7a7ebfa0bcfe",
  "amount": "25.50",
  "remark": "Split payment"
}

Request rules

• source_card_uuid is required and must be a UUID
• destination_card_uuid is required and must be a UUID
• amount is required
• amount must be sent as a JSON string, not a JSON number
• amount must parse as a decimal value greater than 0
• remark is optional, max length 255

Important backend behavior

• The route is IP-rate-limited to 60 requests per minute
• The source and destination cards cannot be the same card
• The source card must belong to the current user
• Both cards must be ACTIVE
• The service checks the source-card balance before executing the transfer
• If the transaction type is empty internally, the service defaults it to TRANSFER
• A transfer row is created first with status = PENDING, then the transfer executes synchronously
• If the downstream transfer fails, the API returns an error and includes transfer metadata such as transfer_uuid and status in the error payload

2. Get Transfer By ID

GET /api/v1/cards/transfer/{id}

Returns one transfer record by local numeric ID.

Notes

• The lookup is scoped to the current mobile user
• If the transfer belongs to another user or does not exist, the route returns not found
• Use this endpoint as the follow-up record lookup after creating a transfer