API Reference

Endpoint Overview

#	Endpoint	Path	Idempotency Key	Description
1	List Card Headers	/api/v1/openapi/card_headers/list	—	List available card headers
2	List Card Configs	/api/v1/openapi/card_configs/list	—	List packages under a header
3	List Cards	/api/v1/openapi/cards/list	—	List the merchant's cards (status / date / balance filters)
4	Apply Virtual Card	/api/v1/openapi/card/apply	✅ Required	Async card open
5	Preview First Deposit	/api/v1/openapi/card/first_deposit/preview	—	Dry-run first-deposit fee / freeze
6	Create Recharge	/api/v1/openapi/card/recharge	✅ Required	Async recharge
7	Get Card Info	/api/v1/openapi/card/info	—	Status polling
8	Webhook Events History	/api/v1/openapi/webhook_events/list	—	Debug webhook delivery
9	List Transactions	/api/v1/openapi/transactions/list	—	Transaction details across all cards
10	List Card Transactions	/api/v1/openapi/card/transactions/list	—	Transaction details for one card
11	Freeze Card	/api/v1/openapi/card/freeze	—	Freeze an active virtual card
12	Unfreeze Card	/api/v1/openapi/card/unfreeze	—	Unfreeze a user-frozen card

Common Conventions

• Method: all endpoints are POST
• Content-Type: application/json (both request and response)
• Auth: 4 signing headers per request (HMAC Authentication)
• Localization: switch zh/en via Accept-Language: zh-CN | en-US
• Response envelope:

{
  "code": 200,           // Mirrors HTTP status
  "message": "OK",
  "message_key": "...",  // Only on errors
  "data": { ... }        // Business payload
}

Pagination

All */list endpoints (except /card_configs/list) support pagination:

Field	Type	Default	Limit
page	int	1	≥ 1
page_size	int	20	≤ 100

Response includes:

{
  "list": [...],
  "total": 12,
  "page": 1,
  "page_size": 20,
  "total_pages": 1,
  "has_next": false,
  "has_prev": false
}