Overview

Coinepay OpenAPI v1.2 is a set of HMAC-authenticated HTTPS REST APIs focused on virtual card issuance, recharge and status queries. All endpoints are POST only; both requests and responses are application/json.

Key Characteristics

• POST-only: every endpoint is POST — easy uniform middleware on both ends.
• HMAC-SHA256 auth: 4 headers (X-App-Id / X-Timestamp / X-Nonce / X-Signature) — no OAuth/JWT.
• Idempotency: write endpoints require Idempotency-Key, dedup window is 24 hours.
• Prefixed resource IDs: every public resource has a business prefix (e.g. card_12345, pkg_67); internal DB primary keys never leak.
• Async webhook delivery: card open / recharge / close completion are pushed actively; same HMAC-SHA256 signing.
• i18n errors: switch zh/en with Accept-Language, while message_key stays stable for programmatic checks.

Scope (v1.2)

Currently supported

Virtual cards only: virtual_l / virtual_p / virtual_v / virtual_r / virtual_g / virtual_a

Not supported yet

• Physical cards (master_e / visa_h)
• Transfer endpoints (transfer)

Recommended Reading Order

1. Quick Start — make your first request in 5 minutes
2. HMAC Authentication — required reading: signature input format
3. IDs & Prefixes — resource identifier convention
4. Idempotency — safe retries on write endpoints
5. Error Codes — message_key dictionary
6. Webhook Spec — receive async events
7. API Reference — request/response schemas for all 12 endpoints

Endpoint Prefix

{base_url}/api/v1/openapi/{endpoint}

Environment	base_url
Production	https://api.coinepay.net
Local dev	http://localhost:8801

Always use HTTPS

Call the production API over HTTPS only at https://api.coinepay.net. Your API key and the HMAC signature travel in request headers — a plain-HTTP request would leak them in transit. Pin the host exactly: do not add a trailing slash to base_url, and never substitute a look-alike domain.

Sandbox

v1.2 does not ship a separate sandbox. Use a test account with small amounts in production. See Sandbox & Testing.