AllScale Open API
Version: v5
Last updated: 2026-10-02
Base Path: /v1/checkout_intents

Overview

The Checkout Intent API allows merchants to create a checkout intent and obtain a hosted payment URL. This API is used to:

Create a checkout intent
Generate a hosted checkout URL
Price the order in either a fiat currency (converted to stable coin at the current FX rate) or natively in a stable coin (no FX, 1:1)
Receive stable-coin–based settlement

Important Design Notes

All enum values are represented as integers in API requests and responses
API consumers must always send and receive integer values
USDT and USDC are supported as settlement stable coins

Authentication

All requests must include the following headers:

Header	Description
X-API-Key	API key
X-Timestamp	Unix timestamp (seconds)
X-Nonce	Unique request identifier
X-Signature	HMAC signature

Notes

X-Nonce must be unique per request
X-Timestamp must be within allowed time window
Signature must be generated using raw request body bytes
Requests are protected against replay attacks

POST /v1/checkout_intents/

Description

Create a checkout intent and return a hosted checkout URL.

Request

POST /v1/checkout_intents/

Headers

X-API-Key: <your_api_key>
X-Timestamp: <unix_timestamp>
X-Nonce: <uuid>
X-Signature: v1=<signature>
Content-Type: application/json

Body Example — Fiat pricing (FX-converted)

{
  "currency": 44,
  "amount_cents": 100,
  "order_id": "order_123",
  "order_description": "Monthly subscription",
  "user_id": "user_456",
  "user_name": "Tom",
  "redirect_url": "https://example.com/checkout/allscale",
  "extra": {
    "source": "web"
  }
}

Body Example — Native stable-coin pricing (no FX)

amount_cents is interpreted as stable-coin “cents”: 1000 = 10.00 USDT. currency_rate on the resulting intent is null because no FX conversion happens.

{
  "stable_coin": 1,
  "amount_cents": 1000,
  "order_id": "order_124",
  "redirect_url": "https://example.com/checkout/allscale"
}

Request Fields

Field	Type	Required	Description
currency	int \| null	⚠️	Fiat currency enum value (see Appendix A). Set exactly one of `currency` or `stable_coin`. When set, `amount_cents` is FX-converted to the stable coin at the current rate.
stable_coin	int \| null	⚠️	Stable-coin enum value (see Appendix B). Set exactly one of `currency` or `stable_coin`. When set, `amount_cents` is the native stable-coin amount × 100 (no FX).
amount_cents	int	✅	Amount in cents (fiat cents when `currency` is set; stable-coin cents when `stable_coin` is set — `100` = `1.00` coin)
order_id	string \| null	❌	Merchant order ID
redirect_url	string \| null	❌	URL to which the user will be redirected after payment is completed
order_description	string \| null	❌	Merchant order description
user_id	string \| null	❌	Merchant user ID
user_name	string \| null	❌	Merchant user name
extra	object \| null	❌	More metadata from merchant
accepted_stable_coins	list[int] \| null	❌	StableCoin enum values the payer may settle in (Appendix B; e.g. `[1]` USDT-only, `[2]` USDC-only, `[1, 2]` either). When omitted, the backend falls back to the merchant’s store/business setting and finally to the global default (USDT).

⚠️ Important

Exactly one of currency or stable_coin must be set. Sending both, or neither, returns a 10001 validation error.
currency and stable_coin must be integer values (Appendix A / B). Do NOT pass "USD" or "USDT" strings.
For native stable-coin pricing, USDT (1) and USDC (2) are accepted. Other stable-coin enum values are reserved for future rollout and will be rejected.
The payment amount must be greater than 0.1 USDT / 0.1 USDC. Orders at or below this floor are rejected with a 50002 error of the form amount must be greater than 0.1 <coin>, where <coin> is the resolved settlement coin name (USDT or USDC).
Test stores have a lower floor: the minimum is 0.01 coin, and orders at or below 0.1 coin carry no service fee (see “Test Stores” below).
For fiat-priced orders that should settle in a specific stable coin, send accepted_stable_coins — the first entry picks the settlement coin used for FX conversion. Example: "currency": 1, "accepted_stable_coins": [2] settles a USD-priced order in USDC. Without accepted_stable_coins the FX target defaults to USDT (the merchant’s store/business accepted_stable_coins setting controls only which coins the payer may settle in via the response bitflag — it does not influence the FX target coin).
accepted_stable_coins must be non-empty when provided and contain only valid StableCoin enum values; otherwise the request is rejected with 10001.

Successful Response

{
  "code": 0,
  "payload": {
    "checkout_url": "https://checkout.allscale.io/abc123",
    "allscale_checkout_intent_id": "65b2f3d0d2d9c0a1b2c3d4e5",
    "amount_coins": "1.0000",
    "stable_coin_type": 1,
    "rate": "1.3500",
    "accepted_stable_coins": 1
  },
  "error": null,
  "request_id": "req_xxxxx"
}

Response Fields

Field	Type	Description
code	int	0 indicates success
payload.checkout_url	string	Hosted checkout URL
payload.allscale_checkout_intent_id	string	Checkout intent ID
payload.amount_coins	string	Stable coin amount
payload.stable_coin_type	int	Stable coin enum value
payload.rate	string \| null	Exchange rate
payload.accepted_stable_coins	int \| null	StableCoinFlag bitmask of stablecoins the payer may settle in for this intent (`1` = USDT, `2` = USDC, `3` = either; bit `n` = StableCoin enum value `n+1`). `null` on intents created before the multi-coin rollout.
error	object \| null	Error object
request_id	string	Request identifier

Possible Errors

Code	Meaning
10001	Validation error
20001	Missing authentication headers
20002	Invalid signature
30001	Forbidden (IP not allowed)
40001	Rate limit exceeded
50002	Create checkout intent error (e.g. amount at or below the 0.1-coin floor)

Notes

All enum values are integers
Do not send string enum names
Nonce must be unique per request
Timestamp must be UTC
Always log request_id for debugging

Test Stores — Simulating Payment Outcomes via `currency`

A test store (also called a sandbox store — is_sandbox = true in the dashboard) lets you rehearse every checkout outcome, including the ones you cannot trigger on demand in production: KYT rejection, refund, stuck settlement and forwarding failure. On a test store the currency field of POST /v1/checkout_intents/ doubles as a scenario selector. The payer still sends real USDT to the deposit address; the outcome after the funds arrive is overridden by the currency you chose when creating the intent. Production stores are not affected. There currency is only the pricing currency and every intent follows the normal flow.

How the override works

The underpaid check runs first, for every currency. Paying less than amount_coins always ends in UNDERPAID (-3) with an automatic refund — identical to production.
A full payment is then replaced by the scenario for the currency:

`currency`	Code	Simulated scenario	Status transitions	Final status	Webhook delivered?
USD	1	Happy path	`3 → 10 → 20`	`CONFIRMED` (20)	Yes
CNY	31	KYT rejection — the risk score is forced over the store threshold and the full amount is refunded to the payer	`3 → 5 → -2`	`REJECTED` (-2)	No
AUD	9	KYT rejection + refund failure — the refund transfer also fails; funds stay in the deposit wallet pending manual recovery	`3 → 5 → -1`	`FAILED` (-1)	No
SGD	126	Stuck settlement — forwarding to the merchant wallet never completes	`3 → 4`	`PENDING_MANUAL_OPERATION` (4), non-terminal	No
HKD	57	Forwarding failure — generic on-chain error before any refund is attempted	`3 → -1`	`FAILED` (-1)	No
any other currency	—	Same as USD	`3 → 10 → 20`	`CONFIRMED` (20)	Yes

Status integers refer to the Checkout Intent Status enum (3 TEMP_WALLET_RECEIVED, 4 PENDING_MANUAL_OPERATION, 5 SEND_BACK, 10 ON_CHAIN, 20 CONFIRMED, -1 FAILED, -2 REJECTED, -3 UNDERPAID).

What to verify in your integration

One message per terminal state. REJECTED, FAILED and UNDERPAID are different outcomes for your customer; do not collapse them into one generic failure.
PENDING_MANUAL_OPERATION (4) is not terminal. It does not advance on its own; AllScale operations may later complete it to CONFIRMED. Your poller must stop on its own timeout and must not treat 4 as a failure.
SEND_BACK (5) means a refund is in flight. Keep the order pending until -2 or -1 arrives.
The webhook fires only on CONFIRMED. Its payload carries status = 20. No webhook is sent for rejection, refund or failure, so order state for those scenarios must come from GET /v1/checkout_intents/{checkout_intent_id}/status or the full intent object.
Reconciliation fields. On the full intent, actual_paid_amount is populated in every scenario where funds arrived (CNY, AUD, SGD, HKD); net_income_amount is only meaningful on CONFIRMED.

Timing. USD, CNY, AUD and HKD resolve as soon as the payment is observed on-chain. SGD reaches PENDING_MANUAL_OPERATION only when the stalled-payment sweep picks the intent up, about 10 minutes after the funds arrive. Amounts. A test store accepts orders from 0.01 coin (production requires more than 0.1), and charges no service fee on orders at or below 0.1 coin. A 0.1 USD intent is enough to exercise every scenario. Additional points before you rely on the scenario map:

The scenario is selected by currency alone. It does not depend on the store’s risk-screening setting (a test store with screening off still returns REJECTED for CNY, because the scenario is applied before screening runs), and it applies on every chain the store accepts.
An intent priced natively in a stable coin carries no currency, so it follows the USD path. Send currency if you want to select a scenario.
CNY refunds on-chain. The refund is a real transfer back to the paying address; SEND_BACK (5) → REJECTED (-2) once it confirms. For HKD and AUD the funds stay in the intent’s ephemeral wallet and are released by manual recovery, as in production.

Other test-store differences

Area	Test store	Production
Minimum order amount	0.01 coin	greater than 0.1 coin (`50002` below that)
Service fee	none on orders at or below 0.1 coin	`max(0.1, amount × fee rate)`
Webhook URL / Claim Link webhook URL	`http://` or `https://`	`https://` only
Sepolia testnet (chain `11`)	accepted	rejected
Risk screening	off on a new store, and not run on testnet chains	on by default
Claim Link auto-payout	not available to test-store API keys	available once onboarded
Store lifetime	suspended 30 days after creation; cannot be renewed	no expiry
Number of stores	one active test store per business	no limit

Move to a production store once your integration is stable.

Appendix A — Currency Enum (IntEnum)

Value	Code	Currency
1	USD	US Dollar
2	AED	United Arab Emirates Dirham
3	AFN	Afghan Afghani
4	ALL	Albanian Lek
5	AMD	Armenian Dram
6	ANG	Netherlands Antillean Guilder
7	AOA	Angolan Kwanza
8	ARS	Argentine Peso
9	AUD	Australian Dollar
10	AWG	Aruban Florin
11	AZN	Azerbaijani Manat
12	BAM	Bosnia and Herzegovina Convertible Mark
13	BBD	Barbadian Dollar
14	BDT	Bangladeshi Taka
15	BGN	Bulgarian Lev
16	BHD	Bahraini Dinar
17	BIF	Burundian Franc
18	BMD	Bermudian Dollar
19	BND	Brunei Dollar
20	BOB	Bolivian Boliviano
21	BRL	Brazilian Real
22	BSD	Bahamian Dollar
23	BTN	Bhutanese Ngultrum
24	BWP	Botswanan Pula
25	BYN	Belarusian Ruble
26	BZD	Belize Dollar
27	CAD	Canadian Dollar
28	CDF	Congolese Franc
29	CHF	Swiss Franc
30	CLP	Chilean Peso
31	CNY	Chinese Yuan
32	COP	Colombian Peso
33	CRC	Costa Rican Colón
34	CUP	Cuban Peso
35	CVE	Cape Verdean Escudo
36	CZK	Czech Koruna
37	DJF	Djiboutian Franc
38	DKK	Danish Krone
39	DOP	Dominican Peso
40	DZD	Algerian Dinar
41	EGP	Egyptian Pound
42	ERN	Eritrean Nakfa
43	ETB	Ethiopian Birr
44	EUR	Euro
45	FJD	Fijian Dollar
46	FKP	Falkland Islands Pound
47	FOK	Faroese Króna
48	GBP	British Pound
49	GEL	Georgian Lari
50	GGP	Guernsey Pound
51	GHS	Ghanaian Cedi
52	GIP	Gibraltar Pound
53	GMD	Gambian Dalasi
54	GNF	Guinean Franc
55	GTQ	Guatemalan Quetzal
56	GYD	Guyanese Dollar
57	HKD	Hong Kong Dollar
58	HNL	Honduran Lempira
59	HRK	Croatian Kuna
60	HTG	Haitian Gourde
61	HUF	Hungarian Forint
62	IDR	Indonesian Rupiah
63	ILS	Israeli New Shekel
64	IMP	Isle of Man Pound
65	INR	Indian Rupee
66	IQD	Iraqi Dinar
67	IRR	Iranian Rial
68	ISK	Icelandic Króna
69	JEP	Jersey Pound
70	JMD	Jamaican Dollar
71	JOD	Jordanian Dinar
72	JPY	Japanese Yen
73	KES	Kenyan Shilling
74	KGS	Kyrgyzstani Som
75	KHR	Cambodian Riel
76	KID	Kiribati Dollar
77	KMF	Comorian Franc
78	KRW	South Korean Won
79	KWD	Kuwaiti Dinar
80	KYD	Cayman Islands Dollar
81	KZT	Kazakhstani Tenge
82	LAK	Lao Kip
83	LBP	Lebanese Pound
84	LKR	Sri Lankan Rupee
85	LRD	Liberian Dollar
86	LSL	Lesotho Loti
87	LYD	Libyan Dinar
88	MAD	Moroccan Dirham
89	MDL	Moldovan Leu
90	MGA	Malagasy Ariary
91	MKD	Macedonian Denar
92	MMK	Myanmar Kyat
93	MNT	Mongolian Tögrög
94	MOP	Macanese Pataca
95	MRU	Mauritanian Ouguiya
96	MUR	Mauritian Rupee
97	MVR	Maldivian Rufiyaa
98	MWK	Malawian Kwacha
99	MXN	Mexican Peso
100	MYR	Malaysian Ringgit
101	MZN	Mozambican Metical
102	NAD	Namibian Dollar
103	NGN	Nigerian Naira
104	NIO	Nicaraguan Córdoba
105	NOK	Norwegian Krone
106	NPR	Nepalese Rupee
107	NZD	New Zealand Dollar
108	OMR	Omani Rial
109	PAB	Panamanian Balboa
110	PEN	Peruvian Sol
111	PGK	Papua New Guinean Kina
112	PHP	Philippine Peso
113	PKR	Pakistani Rupee
114	PLN	Polish Złoty
115	PYG	Paraguayan Guaraní
116	QAR	Qatari Riyal
117	RON	Romanian Leu
118	RSD	Serbian Dinar
119	RUB	Russian Ruble
120	RWF	Rwandan Franc
121	SAR	Saudi Riyal
122	SBD	Solomon Islands Dollar
123	SCR	Seychellois Rupee
124	SDG	Sudanese Pound
125	SEK	Swedish Krona
126	SGD	Singapore Dollar
127	SHP	Saint Helena Pound
128	SLE	Sierra Leonean Leone (new)
129	SLL	Sierra Leonean Leone (old)
130	SOS	Somali Shilling
131	SRD	Surinamese Dollar
132	SSP	South Sudanese Pound
133	STN	São Tomé and Príncipe Dobra
134	SYP	Syrian Pound
135	SZL	Swazi Lilangeni
136	THB	Thai Baht
137	TJS	Tajikistani Somoni
138	TMT	Turkmenistani Manat
139	TND	Tunisian Dinar
140	TOP	Tongan Paʻanga
141	TRY	Turkish Lira
142	TTD	Trinidad and Tobago Dollar
143	TVD	Tuvaluan Dollar
144	TWD	New Taiwan Dollar
145	TZS	Tanzanian Shilling
146	UAH	Ukrainian Hryvnia
147	UGX	Ugandan Shilling
148	UYU	Uruguayan Peso
149	UZS	Uzbekistani Som
150	VES	Venezuelan Bolívar
151	VND	Vietnamese Dong
152	VUV	Vanuatu Vatu
153	WST	Samoan Tālā
154	XAF	Central African CFA Franc
155	XCD	East Caribbean Dollar
156	XCG	Caribbean Guilder
157	XDR	IMF Special Drawing Rights
158	XOF	West African CFA Franc
159	XPF	CFP Franc
160	YER	Yemeni Rial
161	ZAR	South African Rand
162	ZMW	Zambian Kwacha
163	ZWL	Zimbabwe Dollar

Appendix B — StableCoin Enum (IntEnum)

Value	Code	Name	Status
1	USDT	Tether USD	✅ Supported
2	USDC	USD Coin	✅ Supported
3	BUSD	Binance USD	❌ Disabled
4	DAI	Dai	❌ Disabled
5	TUSD	TrueUSD	❌ Disabled
6	PAX	Pax Dollar	❌ Disabled
7	GUSD	Gemini Dollar	❌ Disabled
8	USTC	TerraClassicUSD	❌ Disabled
9	FRAX	Frax	❌ Disabled
10	EURS	Stasis Euro	❌ Disabled

✅ Current Behavior Successful checkout intents return stable_coin_type equal to the resolved settlement coin:

"stable_coin_type": 1   // USDT
"stable_coin_type": 2   // USDC

The value matches whichever supported coin was selected by the merchant via stable_coin (native pricing) or accepted_stable_coins (fiat pricing fallback order). Defaults to 1 (USDT) when neither is set.

End of document.

Getting Started

Checkout Intents

Claim Links

Webhooks

Create Checkout Intent

Overview

Important Design Notes

Authentication

Notes

POST /v1/checkout_intents/

Description

Request

Headers

Body Example — Fiat pricing (FX-converted)

Body Example — Native stable-coin pricing (no FX)

Request Fields

Successful Response

Response Fields

Possible Errors

Notes

Test Stores — Simulating Payment Outcomes via `currency`

How the override works

What to verify in your integration

Other test-store differences

Appendix A — Currency Enum (IntEnum)

Appendix B — StableCoin Enum (IntEnum)

​Overview

​Important Design Notes

​Authentication

​Notes

​POST /v1/checkout_intents/

​Description

​Request

​Headers

​Body Example — Fiat pricing (FX-converted)

​Body Example — Native stable-coin pricing (no FX)

​Request Fields

​Successful Response

​Response Fields

​Possible Errors

​Notes

​Test Stores — Simulating Payment Outcomes via currency

​How the override works

​What to verify in your integration

​Other test-store differences

​Appendix A — Currency Enum (IntEnum)

​Appendix B — StableCoin Enum (IntEnum)

Overview

Important Design Notes

Authentication

Notes

POST /v1/checkout_intents/

Description

Request

Headers

Body Example — Fiat pricing (FX-converted)

Body Example — Native stable-coin pricing (no FX)

Request Fields

Successful Response

Response Fields

Possible Errors

Notes

Test Stores — Simulating Payment Outcomes via `currency`

How the override works

What to verify in your integration

Other test-store differences

Appendix A — Currency Enum (IntEnum)

Appendix B — StableCoin Enum (IntEnum)