API Doc - Checkout Intent Routes - Create Checkout Intent

AllScale Open API Version: v4 Last updated: 2026-05-06 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).

• 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 backend falls back to the merchant's configured default.

• 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

---

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.