API URL
POST /api/v2/checkoutRequest
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 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 - 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 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 |
| 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 |
| Name | Type | Required | Description |
|---|---|---|---|
| shopping_cost | decimal | N | Shipping cost |
| tax_cost | decimal | N | Tax |
| items | JSONArrayString | N | Product List |
| 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 |
| item_quantity | integer(int64) | N | Quantity of an item ordered |
| Name | Type | Required | Description |
|---|---|---|---|
| sub_merchant_id | string | N | Sub merchant’s ID |
| sub_merchant_name | string | N | Name of sub merchant |
Request Example
{
"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": "[email protected]",
"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
{
"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/[email protected]",
"token_decimals": 6,
"receive_amount": "0.642951",
"receive_currency": "USDT",
"exchange_rate": "0.1285902181",
"asset_logo": "https://static.cregis.io/pic/coin/tether%[email protected]"
},
{
"payment_address": "0xf9d70ab23195cfc9c0c14b384a1fd3a3f12cd4f8",
"token_symbol": "USDT",
"blockchain": "BNB-BSC",
"token_name": "USDT-BEP20",
"logo_url": "https://static.cregis.io/pic/coin/USDT-BNB%[email protected]",
"token_decimals": 18,
"receive_amount": "0.642951",
"receive_currency": "USDT",
"exchange_rate": "0.1285902181",
"asset_logo": "https://static.cregis.io/pic/coin/tether%[email protected]"
},
]
}
}