Conventions
Protocol, request headers, response format, data formats, and idempotency.
Protocol
| Item | Description |
|---|---|
| Protocol | HTTPS (TLS 1.2+) |
| Methods | GET for query endpoints, POST for operation endpoints |
| Request format | application/json. The token endpoint uses application/x-www-form-urlencoded |
| Response format | application/json |
| Encoding | UTF-8 |
| Timeout | 30 seconds recommended |
Request headers
| Header | Description | Required |
|---|---|---|
Authorization | Bearer {accessToken} | Yes |
Content-Type | application/json | Yes, required for POST requests |
Idempotency-Key | Unique request identifier. Use a UUID or a unique business serial number | Yes, required for POST requests |
Response format
Success response example
{
"code": 200,
"message": "OK",
"traceId": "trace-uuid-string",
"data": {}
}Error response example
{
"code": 500,
"message": "Payment intent not found: pi_MNOL0POUV8IDPXCD",
"traceId": "trace-uuid-string"
}Use the HTTP status code to determine whether a request succeeded. The code in an error response body is not always the same as the HTTP status code. When you contact support, provide the traceId. For the meaning of each error, see Error codes.
Data formats
| Type | Format | Example |
|---|---|---|
| Amount | Decimal string in the standard currency unit, output at the currency precision. Minor currency units are not used | "20.00" (USD), "2000" (JPY) |
| Currency | Uppercase code. Stablecoins are also treated as currencies | USD, USDT |
| Network | Platform chain name | Polygon, Ethereum |
| Time | ISO 8601 with a time zone offset. Parse it as ISO 8601. Do not assume a fixed time zone | 2026-05-11T14:12:34+08:00 |
| Enum | Uppercase code value | COMPLETED, REQUESTED_BY_CUSTOMER |
Fields with empty values are omitted from responses.
Idempotency
The Stabo API uses Idempotency-Key to prevent POST operations from running more than once. If a network timeout occurs or you receive no response, you can retry the same request with the same Idempotency-Key.
- Every
POSTrequest must include anIdempotency-Key - When you retry the same business request, reuse the same
Idempotency-Key - Different business requests must use different
Idempotency-Keyvalues - Use a UUID, a value derived from the order number, or a unique business serial number
For how to retry after a timeout, see Best practices.
Products handle a duplicate Idempotency-Key differently. Payment transfer endpoints reject a duplicate key (HTTP 400, Duplicate request detected) and do not return the original result. After a timeout, call the result query endpoint with referenceNo to confirm the status. Do not resubmit. See Payment idempotency.
Do not reuse the same Idempotency-Key for different transactions. Otherwise, a request can be identified as a duplicate.