# 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: X-Timestamp: X-Nonce: X-Signature: v1= Content-Type: application/json ``` **Body Example — Fiat pricing (FX-converted)** ```json { "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. ```json { "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 !`, where `` 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 ```json { "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: ```json "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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.allscale.io/allscale-checkout/api-reference/api-doc-checkout-intent-routes-create-checkout-intent.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.