Card Withdrawals

Flow Summary

The current withdrawal flow is:

Step 1. Make sure the source card is active
Use Virtual Cards first

Step 2. Create the withdrawal
POST /api/v1/card-withdrawals

Step 3. Check the latest withdrawal state
GET /api/v1/cards/{uuid}/withdraw-status

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

Authorization: Bearer <access_token>

The create endpoint also passes through DecryptField(), so it accepts either plain JSON or the encrypted wrapper described in Overview.

1. Create Card Withdrawal

POST /api/v1/card-withdrawals

Creates a withdrawal from a card to a blockchain wallet.

Request

{
  "source_card_uuid": "5e5d4990-2241-46dc-9dbd-8abcf97e6061",
  "wallet_address": "TP6fJc4Y7Qm6kQ1u1FfH2uZzGgQqV1kB2u",
  "amount": "50.00",
  "network": "TRC20"
}

Request rules

• source_card_uuid is required and must be a UUID
• wallet_address is required
• 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
• network is required

Important backend behavior

• The route is IP-rate-limited to 60 requests per minute
• The source card must belong to the current user
• The source card must be ACTIVE
• The network must be a valid blockchain network enum
• The current accepted values include TRC20 and ERC20
• Only one pending withdrawal is allowed per user at a time
• The submitted amount must be greater than the configured withdrawal fee
• The service creates the withdrawal row first, then executes the withdrawal synchronously

2. Get Latest Withdrawal Status

GET /api/v1/cards/{uuid}/withdraw-status

Returns the raw status of the latest withdrawal for a specific card UUID.

Path parameter

• uuid is required
• uuid is the card UUID, not the withdrawal UUID

Returned statuses

The current service returns the latest row's raw status, commonly:

• PENDING
• PROCESSING
• SUCCESS
• FAILED
• NOT_FOUND

Important backend caveat

• Some Swagger comments describe summarized values such as APPROVED, PENDING, or DECLINED
• The current implementation does not map to that simplified set
• Instead, it returns the raw latest entity status, or NOT_FOUND if no withdrawal exists yet
• The handler requires an authenticated user, but the service currently loads the card by UUID without explicitly verifying that the card belongs to that user before reading the latest withdrawal row

Success response shape

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