# Coinepay OpenAPI

> Coinepay OpenAPI v1.1 — Virtual card integration docs: HMAC auth, idempotency, webhooks, error codes, code samples.

Index follows the [llmstxt.org](https://llmstxt.org) spec. Full text at [llms-full.txt](/llms-full.txt).

## Guide

- [HMAC Authentication](/guide/authentication): Coinepay OpenAPI uses HMAC-SHA256 — 4 request headers complete signing + replay protection.
- [Error Codes](/guide/error-codes): Coinepay OpenAPI message_key → HTTP status → English/Chinese description reference.
- [Idempotency](/guide/idempotency): Write endpoints require Idempotency-Key. Same key + same body is deduplicated for 24 hours.
- [IDs & Prefixes](/guide/ids-and-prefixes): All Coinepay OpenAPI public resource IDs carry a business prefix. Always preserve the prefix when sending back.
- [Overview](/guide/overview): Coinepay OpenAPI v1.2 is a set of HMAC-authenticated HTTPS REST APIs focused on virtual card issuance, recharge and status queries.
- [Quick Start](/guide/quickstart): Make your first OpenAPI call in 5 minutes — list available card headers.
- [Rate Limit](/guide/rate-limit): Coinepay OpenAPI uses token-bucket rate limiting per (AppID, IP); exceeding the limit returns 429.
- [Sandbox & Testing](/guide/sandbox): v1.2 has no separate sandbox — use a real account with small amounts and webhook.site as a receiver.
- [Webhook Spec](/guide/webhooks): Coinepay sends HMAC-signed webhook events for card-open, recharge, close, etc.

## API Reference

- [API Reference](/api/): Coinepay OpenAPI v1.2 endpoint list — 12 endpoints, all POST, unified HMAC auth.
- [Apply Virtual Card](/api/card-apply): Async card-open endpoint. Returns card_id + initial status; final result via webhook. POST /api/v1/openapi/card/apply
- [List Card Configs](/api/card-configs-list): List packages (fees, deposits, monthly fees) available under a specific header. POST /api/v1/openapi/card_configs/list
- [Freeze Card](/api/card-freeze): Freeze an active virtual card so it can no longer be used for payments. POST /api/v1/openapi/card/freeze
- [List Card Headers](/api/card-headers-list): List available virtual card headers for the current account. POST /api/v1/openapi/card_headers/list
- [Get Card Info](/api/card-info): Retrieve card status, balance, and (optionally) full PAN / CVV / expiry. POST /api/v1/openapi/card/info
- [Create Recharge](/api/card-recharge): Async recharge endpoint. Returns transaction_id; result via webhook. POST /api/v1/openapi/card/recharge
- [List Card Transactions](/api/card-transactions-list): Query transaction details for one specific virtual card. POST /api/v1/openapi/card/transactions/list
- [Unfreeze Card](/api/card-unfreeze): Unfreeze a card that was frozen via the OpenAPI freeze endpoint. POST /api/v1/openapi/card/unfreeze
- [List Cards](/api/cards-list): List all virtual cards under the current AppID with status / date / balance filters. POST /api/v1/openapi/cards/list
- [Preview First Deposit](/api/first-deposit-preview): Read-only dry-run of the card-open first deposit (base + excess fee + amount credited + wallet freeze). POST /api/v1/openapi/card/first_deposit/preview
- [List Transactions](/api/transactions-list): Query card transaction details across all your virtual cards. POST /api/v1/openapi/transactions/list
- [Webhook Events History](/api/webhook-events-list): Query the webhook delivery history for the current account. POST /api/v1/openapi/webhook_events/list

## Code Samples

- [Code Samples](/examples/): Copy-paste ready clients for Python / Node.js / Go / Java / PHP / cURL.
- [cURL](/examples/curl): Call OpenAPI from the command line with cURL + openssl — handy for quick verification.
- [Go](/examples/go): Go 1.21+ client implementation — stdlib only.
- [Java](/examples/java): Java 11+ client implementation — JDK stdlib only (HttpClient + javax.crypto).
- [Node.js](/examples/nodejs): Node.js 18+ client implementation — only stdlib crypto + native fetch.
- [PHP](/examples/php): PHP 7.4+ client implementation — only depends on the curl extension (default).
- [Python](/examples/python): Python 3.6+ client implementation — HMAC signing + Webhook verification.

## Reference

- [Changelog](/reference/changelog): Coinepay OpenAPI version & change history.
- [Constants](/reference/constants): All "frozen" Coinepay OpenAPI v1.2 values — path prefixes, timeouts, limits, signing spec.

## Other

- [Coinepay OpenAPI v1.2](/): Virtual card integration docs — HMAC auth, idempotency, webhooks, error codes & code samples.