Constants
The values below are stable in v1.2. Any breaking changes will ship via a changelog entry + version bump, with advance notice to integrators.
Base URL
| Environment | URL |
|---|---|
| Production | https://api.coinepay.net |
| Sandbox | None (not provided in v1.2) |
| Local dev | http://localhost:8801 |
API Prefix
/api/v1/openapiHTTP Convention
| Item | Value |
|---|---|
| Method | All POST (project hard rule) |
| Request Content-Type | application/json |
| Response Content-Type | application/json; charset=utf-8 |
| Max body | 4 MB (4194304 bytes) |
| Charset | UTF-8 |
Authentication
| Item | Value |
|---|---|
| Algorithm | HMAC-SHA256 |
| Required headers | X-App-Id / X-Timestamp / X-Nonce / X-Signature |
| AppID format | cp_<28 hex>, fixed length 31 |
| Secret format | 64 hex characters |
| Secret prefix display | <first 4>**** |
| Timestamp unit | Seconds (not milliseconds) |
| Timestamp tolerance | ±300 seconds |
| Nonce length | 8–64 characters |
| Nonce replay window | 600 seconds |
| Signature format | lowercase hex |
| Signature length | 64 characters |
Idempotency
| Item | Value |
|---|---|
| Header | Idempotency-Key |
| Required endpoints | /api/v1/openapi/card/apply / /api/v1/openapi/card/recharge |
| Max length | 128 characters |
| Dedup window | 24 hours |
| Conflict status | 409 |
Rate Limit
| Item | Value |
|---|---|
| Dimension | (AppID, IP) |
| Quota | 600 / minute |
| Window | 60 seconds (rolling) |
| Exceeded | HTTP 429 |
Webhook Delivery
| Item | Value |
|---|---|
| Signature header | Webhook-Signature |
| Signature format | v1,<hex_hmac_sha256> |
| Signature input | {timestamp}.{raw_body} |
| Event ID header | Webhook-Id |
| Timestamp header | Webhook-Timestamp |
| Type header | Webhook-Type |
| Retry backoff (seconds) | [60, 300, 900, 3600, 21600, 86400] |
| Total delivery attempts | 7 (1 initial + 6 retries; then dead_letter) |
| Receiver response-header timeout | 5 seconds |
| Receiver total request timeout | 10 seconds |
| HTTPS required | ✅ (production; HTTP only when AllowHTTP=true in dev) |
| Public IP required | ✅ (rejects private / loopback / link-local) |
| Allowed ports | 443 in production |
Card Types (v1.2 OpenAPI scope)
| card_type | Description |
|---|---|
virtual_l | Virtual card class L |
virtual_p | Virtual card class P |
virtual_v | Virtual card class V |
virtual_r | Virtual card class R |
virtual_g | Virtual card class G |
virtual_a | Virtual card class A (email required, phone not collected — see Apply) |
OpenAPI rejects non-virtual types
master_e / visa_h / transfer etc. are out of scope and return 400 openapi_card_type_not_supported.
apply does not accept card_type
/card/apply doesn't take card_type; it's derived from header_id.
Business Prefixes
| Resource | Prefix | Example |
|---|---|---|
| Card | card_ | card_12345 |
| Package | pkg_ | pkg_67 |
| Card header | hdr_ | hdr_5 |
| Recharge transaction | txn_ | txn_OO20260429110012abc |
| Webhook event | evt_ | evt_550e8400-e29b-41d4-a716-446655440000 |
Useful SHA-256 Constants
| Input | sha256 hex |
|---|---|
| Empty string | e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 |
{} | 44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a |
Localization
| Header | Behavior |
|---|---|
Accept-Language not set | Default Chinese |
Accept-Language: zh-CN | Chinese |
Accept-Language: en-US | English |
message_key is not affected by Accept-Language — always stable, use it for programmatic checks.
Credentials
| Item | Value |
|---|---|
| Validity | Indefinite (until reset / disabled) |
| Per-user limit | 1 active credential pair (v1) |
| After reset | Old secret immediately invalid |
| After disable | 401 invalid_credentials; can re-enable |