IDs & Prefixes

All public resource IDs are prefixed strings rather than raw integer DB keys. When you send IDs back, keep the prefix as-is.

Prefix Table

Resource	Prefix	Example	Where it appears
Card	card_	card_12345	apply response / card_id field on subsequent endpoints
Package	pkg_	pkg_67	card_configs/list response / apply request
Card header	hdr_	hdr_5	card_headers/list response / apply request
Recharge transaction	txn_	txn_OO20260429110012abc	recharge response / webhook payload
Webhook event	evt_	evt_550e8400-e29b-41d4-a716-446655440000	webhook_events/list response

Webhooks use the same convention

All IDs in webhook payloads are also prefixed. The Webhook-Id header value with evt_ stripped is the original UUID.

transaction_id is opaque

Treat txn_<...> as an opaque string for storage, lookup and reconciliation. The internal structure after the txn_ prefix is server-generated and not stable across versions or providers — never parse, slice or pattern-match it. Internal order references are intentionally not exposed.

Validation Rules

Error	Returns
Missing prefix (e.g. sending 5 instead of hdr_5)	400 openapi_invalid_header_id
Resource doesn't exist / not owned by you	400 openapi_invalid_*_id (same key as "missing prefix" — no leakage)

No distinction between "format error" and "not found"

openapi_invalid_*_id covers all of:

• Missing prefix
• Wrong prefix
• ID not owned by current AppID's account
• ID does not exist

The server deliberately returns the same key — preventing enumeration attackers from probing valid ID ranges via response differences.

Internal Fields That Are Never Exposed

The response shape documented for each endpoint is the complete contract. Internal database identifiers, provider-side order references, intermediate computation values, and internal labels are never returned via OpenAPI.

If you see anything outside the documented response shape, please report it to the Coinepay team.

Tips

• Store IDs with their prefix; send them back as-is (don't strip the digit part)
• Logs/alerts should include the full ID (card_12345) for debugging
• Differentiate from your internal IDs: Coinepay's IDs are card_xxx; your internal IDs should use a different prefix (e.g. kart_xxx) to avoid confusion.