Field Conventions & Glossary
Canonical definitions used across API documentation.
| Header | Required | Definition |
|---|
| x-api-key | Yes | API-key issued in the app ("Business" section). The organization is resolved from the request host |
| Content-Type | Yes (POST) | application/json for create requests |
Amount & Currency
| Term | Definition |
|---|
| amount | String of an integer in minor units (e.g. cents, smallest token fraction) |
| amount_with_fee | Amount plus applied fee (minor units) |
| currency | ISO-like currency / token code (e.g. USDT) |
| currency_dest | Destination currency for conversion (FX). Optional; defaults to currency |
Identifiers
| Term | Definition |
|---|
| id | Internal system UUID of transaction |
| txid | Client-supplied idempotent external identifier. Must be a valid UUID when provided; may be omitted |
Routing & Environment
| Term | Definition |
|---|
| route | Processing path alias configured for API key |
| env | Execution environment: prod (default) or test |
Status Lifecycle
| Status | Meaning |
|---|
| created | Accepted, awaiting processing |
| new | Initial state before processing starts |
| authorizing | Authorization in progress |
| pre_authorized_3ds | Awaiting 3DS authentication |
| action_required | Awaiting an additional action (3DS / extra authorization) |
| charging | In progress (authorization / funding) |
| payment_suspended | Inbound transaction temporarily suspended |
| payout_suspended | Outbound transaction temporarily suspended |
| charged | Successfully completed (terminal) |
| reversed | Charge reversed (terminal) |
| refunded | Refunded (terminal) |
| rejected | Irrecoverably failed (terminal) |
| failed | Failed (terminal) |
Terminal states are charged, reversed, refunded, rejected, failed. The most common happy path is created → charging → charged.
Time Fields
| Field | Definition |
|---|
| started | ISO timestamp when processing began |
| finished | ISO timestamp when terminal (charged/rejected) reached |
Money Storage Objects
| Field | Definition |
|---|
| network | Blockchain network (ETH, TRX, etc.) |
| type | Instrument type (bank_card, p2p_proxy, etc.) |
| wallet_id | Internal wallet identifier (payout/payment target) |
| cardnumber | Virtual card PAN (masked in some responses) |
| cvv | Virtual card security code (never log in plaintext) |
| exp_month / exp_year | Card expiry values (string, zero padded) |
| cardholder | Cardholder name (ASCII or UTF-8) |
Error Fields
| Field | Definition |
|---|
| error_description | Human-readable failure reason (non-stable text) |
Idempotency Guidance
Use a unique txid (a valid UUID) per business operation. Retry identical creation requests only with the same txid to avoid duplicate charges — a repeated txid returns the originally created transaction instead of creating a new one. A non-UUID txid is rejected with 422 invalid_txid.
Polling Strategy
- Submit transaction.
- Poll: 1s, 2s, 4s, 8s ... cap at 30s.
- Stop on terminal status or timeout budget.
Webhooks indicate state change but are not authoritative. Always confirm via GET Transaction.