> ## Documentation Index
> Fetch the complete documentation index at: https://developer.cregis.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Payment order
> Create a payment order using the Cregis checkout page
### API URL
POST /api/v2/checkout
### Request
#### Request Parameters
| Name | Type | Required | Description |
| -------------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| pid | integer(int64) | Y | Unique identifier of the acquiring project in Cregis |
| nonce | string | Y | A 6-character random string |
| timestamp | integer(int64) | Y | 13-digit unix timestamp format |
| sign | string | Y | The digital signature of the request to prevent illegal tampering. Refer to the [Signature](/api-reference/signature) section for the signing rules. |
| order\_id | string | Y | Merchant's internal order ID. Must be equal or less than 128 characters |
| order\_amount | string | Y | Order amount (based on the order currency)
Order amount (fiat amount if order\_currency is fiat currency / crypto amount if order\_currency is crypto currency) |
| order\_currency | string | Y | Please refer to the Order Currency under [Order currency List](/api-reference/request-apis/payment/payment-order-currency)
- If the order currency is a cryptocurrency, examples are USDT, ETH, etc.
- If the order currency is a fiat currency, please enter the ISO 4217 3-character currency code. Examples are HKD, USD, etc |
| order\_details | JSONString | N | The breakdown of the order items including price, quantity and product description that will be displayed on the Cregis checkout page under the order details section |
| sub\_merchant | JSONString | N | If the merchant has a sub merchant assigned under this acquiring project, it can be used by the merchant to assign their own internal sub merchant ID to associate with a payment.
Field:
sub\_merchant\_id
sub\_merchant\_name |
| payer\_id | string | Y | Can be used by the merchant to assign their own internal user ID to associate with a payment |
| payer\_name | string | N | Payer's name |
| payer\_email | string | N | Payer's email, If accept\_partial\_payment / accept\_over\_payment is false, then Yes |
| tokens | ArrayString | N | This field enables you to limit the tokens that you allow your customers to pay with. Leaving this field empty means you allow all Cregis-supported tokens for payment.
For this parameter format, please refer to the Payment Currency and Payment Network from the [Pay currency List](/api-reference/request-apis/payment/payment-pay-currency) Parameters page; for example, USDT-BEP20, USDT-TRC20, etc. |
| stablecoin\_realtime\_rate | string | N | Default value：false
false：means using a fixed 1:1 exchange rate of USDT/USDC to USD
true：means using the real-time exchange rate of USDT/USDC to USD obtained on CoinMarketCap |
| underpaid\_tolerance | float | N | The lower tolerance threshold for payment amount deviations of this order, underpaid\_tolerance is calculated based on order\_currency, and the default value is 0.
This lower tolerance threshold is used to calculate the minimum amount you would accept the order. Unit is according to the parameter of order\_currency
- "paid" order status: order\_amount - underpaid\_tolerance `<=` Actual Paid Amount `<=` order\_amount + overpaid\_tolerance
- "partial\_paid" order status: Actual Paid Amount \< order\_amount - underpaid\_tolerance
- "overpaid" order status: order\_amount + overpaid\_tolerance \< Actual Paid Amount
Example: order\_currency is HKD and underpaid\_tolerance is 3.50. Order status will be
- "paid" if the order is underpaid by HKD 3.50 or less
- "partial\_paid" if the order is underpaid by HKD 3.50 and more |
| overpaid\_tolerance | float | N | The upper tolerance threshold for payment amount deviations of this order, overpaid\_tolerance is calculated based on order\_currency, and the default value is 0.
This upper tolerance threshold is used to calculate the maximum amount you would accept the order. Unit is according to the parameter of order\_currency
- "paid" order status: order\_amount - underpaid\_tolerance `<=` Actual Paid Amount `<=` order\_amount + overpaid\_tolerance
- "partial\_paid" order status: Actual Paid Amount \< order\_amount - underpaid\_tolerance
- "overpaid" order status: order\_amount + overpaid\_tolerance \< Actual Paid Amount
Example: order\_currency is HKD and overpaid\_tolerance is 3.50. Order status will be
- "paid" if the order is overpaid by HKD 3.50 or less
- "overpaid" if the order is overpaid by HKD 3.50 and more |
| accept\_partial\_payment | string | N | Default value: "true"
- "false": If the order does NOT accept the partial payment and the actual payment amount is less than the order\_amount, the payer must make an additional payment or proceed a refund
- "true": If the order accepts the partial payment, the payer is not required to make an additional payment or proceed a refund |
| accept\_over\_payment | string | N | Default value: "true"
- "false": If the order does NOT accept the overpayment and the actual payment amount is more than the order\_amount, the payer must proceed a refund for the extra amount
- "true": If the order accepts the overpayment, the payer is not required to proceed a refund for the extra amount |
| language | string | N | Default value：en
Used to specify the default language for the Cregis checkout page or emails. The optional are:
en - English
tc - Traditional Chinese
sc - Simplified Chinese |
| callback\_url | string | N | URL to which Cregis sends webhook notifications on payment status update to the merchant, details for [Payment notify](/api-reference/callback/payment-engine) |
| remark | string | N | For the merchant to make remarks about a payment |
| valid\_time | integer | Y | Unit: Minutes (Integer value from 10 to 1440)
The valid time for this order. If the valid time is expired, the payment will not be accepted. |
| success\_url | string | Y | The payer will be redirected to this URL when clicking on the Return to Store button after a successful payment. Be sure to include "http\://" or "https\://" in the url |
| cancel\_url | string | Y | Redirect to this url if the payer does not pay or click on the "Cancel" button. Be sure to include "http\://" or "https\://" in this url |
**order\_details object**
| Name | Type | Required | Description |
| -------------- | --------------- | -------- | ------------- |
| shopping\_cost | decimal | N | Shipping cost |
| tax\_cost | decimal | N | Tax |
| items | JSONArrayString | N | Product List |
**items object**
| Name | Type | Required | Description |
| --------------- | -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| item\_id | string | N | The unique identifier of the item |
| item\_name | string | N | Item name |
| item\_price | decimal | N | Item price |
| price\_currency | string | N | Please refer to Order Currency under [Order currency List](/api-reference/request-apis/payment/payment-order-currency) |
| item\_quantity | integer(int64) | N | Quantity of an item ordered |
**sub\_merchant object**
| Name | Type | Required | Description |
| ------------------- | ------ | -------- | -------------------- |
| sub\_merchant\_id | string | N | Sub merchant's ID |
| sub\_merchant\_name | string | N | Name of sub merchant |
###### Request Example
```json theme={null}
{
"timestamp": 1734327655,
"nonce": "dositl",
"sign": "f5be13fdd8c6f63951ca4427359457cb",
"order_id": "merchant_order_id_12334567",
"order_amount": "5",
"order_currency": "USD",
"callback_url": "https://callback.com",
"remark": "VIP order",
"payer_id": "payer001",
"payer_name": "payer",
"payer_email": "payer@gmail.com",
"valid_time": 60,
"pid": 1419287201923072,
"cancel_url": "https://cancel.merchant.com",
"success_url": "https://success.merchant.com",
"tokens": "[\"USDT-TRC20\",\"USDT-BEP20\"]",
"order_details": "{\"items\": [{\"item_id\": \"10001\", \"item_name\": \"Product1\",\"item_price\": 123.00,\"item_quantity\": 1,\"price_currency\": \"USD\"},{\"item_id\": \"10002\", \"item_name\": \"Product2\",\"item_price\": 100.00,\"item_quantity\": 2,\"price_currency\": \"USD\"}],\"shopping_cost\": 10.88,\"tax_cost\": 10.00}"
"sub_merchant": "{\"sub_merchant_id\": \"submerchant10001\",\"sub_merchant_name\": \"Merchant1\"}"
}
```
### Response
#### Response Result
| Name | Type | Description |
| ---- | ------ | -------------- |
| code | string | Return code |
| msg | string | Return message |
| data | Object | Return data |
#### `data` Object
| Name | Type | Description |
| ------------------- | -------------- | -------------------------------------------------------------------------------------------------------------- |
| cregis\_id | string | Unique identifier of a payment generated by Cregis |
| checkout\_url | string | Checkout page url |
| merchant\_name | string | Merchant name to be displayed on Cregis checkout page |
| merchant\_logo\_url | string | Merchant logo to be displayed on Cregis checkout page |
| order\_amount | string | Order amount. |
| order\_currency | string | Order currency |
| created\_time | integer(int64) | Order creation time in 13-digit unix timestamp format
e.g. 1720508269092 (2024-07-09 14:57:49 092) |
| expire\_time | integer(int64) | Order expiration time in 13-digit unix timestamp format
e.g. 1720508269092 i.e. 2024-07-09 14:57:49 092 |
| payment\_info | ArrayObject | Payment detail information |
#### `payment_info` object
| Name | Type | Description |
| ----------------- | ------- | -------------------------------------------------------------------------------------------- |
| payment\_address | string | Wallet address that receives payment |
| token\_symbol | string | Available cryptocurrency for payment. Can refer to the parameter of tokens in order creation |
| blockchain | string | Blockchain network |
| token\_name | string | crypto token name |
| logo\_url | string | crypto token logo |
| token\_decimals | integer | crypto token decimal places |
| receive\_amount | string | The amount of the order after exchange rate conversion |
| receive\_currency | string | The order currency code after exchange rate conversion |
| exchange\_rate | string | Currency exchange rate |
| asset\_logo | string | crypto asset logo |
###### Response Example
```json theme={null}
{
"code": "00000",
"msg": "ok",
"data": {
"cregis_id": "po1420761885130752",
"checkout_url": "http://192.168.2.60:9099?cid=b2fb433c953a43bd9bdfc3f611567887",
"merchant_name": null,
"merchant_logo_url": null,
"order_amount": "5",
"order_currency": "HKD",
"created_time": 1734328473070,
"expire_time": 1734332073070,
"payment_info": [
{
"payment_address": "TX8GZJfLYPtmzRgd3FoiXuCHbptiQ37NSM",
"token_symbol": "USDT",
"blockchain": "TRON",
"token_name": "USDT-TRC20",
"logo_url": "https://static.cregis.io/pic/coin/USDT-Tron-TRC20@8x.png",
"token_decimals": 6,
"receive_amount": "0.642951",
"receive_currency": "USDT",
"exchange_rate": "0.1285902181",
"asset_logo": "https://static.cregis.io/pic/coin/tether%20usd-usdt-with-currency@8x.png"
},
{
"payment_address": "0xf9d70ab23195cfc9c0c14b384a1fd3a3f12cd4f8",
"token_symbol": "USDT",
"blockchain": "BNB-BSC",
"token_name": "USDT-BEP20",
"logo_url": "https://static.cregis.io/pic/coin/USDT-BNB%20Chain-BEP20@8x.png",
"token_decimals": 18,
"receive_amount": "0.642951",
"receive_currency": "USDT",
"exchange_rate": "0.1285902181",
"asset_logo": "https://static.cregis.io/pic/coin/tether%20usd-usdt-with-currency@8x.png"
},
]
}
}
```