Create Recharge

Async recharge endpoint. Returns transaction_id + initial status: 1 (processing); final result is delivered via card.recharged / card.recharge_failed webhook.

Endpoint

Item	Value
Method	POST
Path	/api/v1/openapi/card/recharge
Auth	HMAC
Idempotency Key	Required

Request Fields

Field	Type	Required	Description
card_id	string	✅	card_<id>
amount	string (decimal)	✅	Recharge amount (in card currency)

Example Request

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

Required header:

Idempotency-Key: 7b3e9d5c-1a2b-4f3e-8c7d-6f5e4a3b2c1d

Response Fields

Field	Type	Description
transaction_id	string	txn_<...>
card_id	string	Echo
amount	string	Requested amount
currency	string	Card currency
status	int	1=processing 2=success 3=failed
status_desc	string	English description
created_at	string	RFC3339 timestamp

Example Response

{
  "code": 200,
  "message": "OK",
  "data": {
    "transaction_id": "txn_OO20260429120000xyz",
    "card_id": "card_12345",
    "amount": "100.00",
    "currency": "USD",
    "status": 1,
    "status_desc": "processing",
    "created_at": "2026-04-29T12:00:00Z"
  }
}

Common Errors

HTTP	message_key	Description
400	amount_required	amount missing
400	insufficient_balance	Insufficient balance
400	openapi_invalid_card_id	Bad card ID
400	openapi_idempotency_key_required	Missing idempotency key
401	openapi_invalid_credentials	Auth failure
404	card_not_found	Card not found
409	openapi_idempotency_key_conflict	Same key, different body
500	openapi_recharge_failed	Server error

Notes

• Don't reuse the same Idempotency-Key for different amounts on the front-end (will 409)
• Same key used as a safety net for network retries → returns the original response
• transaction_id is txn_<...> — match it against the transaction_id in webhooks (treat as opaque)