Payment
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 | Project id |
| nonce | string | Y | 6 random string |
| timestamp | integer(int64) | Y | Timestamp |
| sign | string | Y | Signature |
| order_id | string | Y | Can be used by the merchant to assign their own internal order ID to a payment. No more than 128 characters |
| order_amount | string | Y | The total payment amount, in the order currency |
| order_currency | string | Y | ISO 4217 3-character currency code. This is the currency associated with the order amount field eg: USD、HKD Get support currency from Get support fiat currency |
| order_details | JSONString | N | The breakdown details of an order, each item will be displayed on the Cregis checkout page, under 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 |
| tokens | ArrayString | N | By inputing corresponding token_name to this field to control the tokens you allow your customers to pay in. If this field is left blank, that means you accept all tokens supported by Cregis as the payin tokens by customers. eg: [“USDT-TRC20”,“USDT-BEP20”] Get support currency from Get support crypto currency |
| 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. - The order status will be ‘paid’: When order actual pay-in amount falls within the upper and lower tolerance range - The order status will be ‘partial_paid’: When order actual pay-in amount is lower than order receivable amount minus underpaid_tolerance value - The order status will be ‘overpaid’: When order actual pay-in amount is higher than order receivable amount plus overpaid_tolerance value For example: The original order_currency is HKD, and the value for underpaid_tolerance is: 2.25, which means that the order is still considered paid exact if the underpayment is within 2.25 HKD, and the ‘paid’ order status will be returned. If the underpayment exceeds 2.25 HKD, it will return partial paid |
| 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. - The order status will be ‘paid’: When order actual pay-in amount falls within the upper and lower tolerance range - The order status will be ‘partial_paid’: When order actual pay-in amount is lower than order receivable amount minus underpaid_tolerance value - The order status will be ‘overpaid’: When order actual pay-in amount is higher than order receivable amount plus overpaid_tolerance value For example: The original order_currency is HKD, and the overpaid_tolerance is 3.50, which means that the order is still considered paid exact if an overpayment is HKD 3.50 or lower. If the overpayment exceeds HKD 3.50, the status will be returned as overpaid |
| accept_partial_payment | string | N | Default value: true - false: If the merchant does NOT accept partial payment and needs user to pay remaining amount for partial paid orders - true: If the merchant accepts partial payment and does NOT need user to pay remaining amount for partial paid orders |
| accept_over_payment | string | N | Default value: true - false: If the merchant does NOT accept overpayment and needs to refund the overpaid value to user - true: If the merchant accepts overpayment and does NOT needs to refund the overpaid value to user |
| 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 | Validation time in minute (within 10 to 60 minutes) for a payment, a payment will be expired after this assigned validation timeframe |
| 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 | URL to redirect if the payer does not pay and click on the Cancel button instead. Be sure to include “http://” or “https://” in the url |
order_details object
| Name | Type | Required | Description |
|---|---|---|---|
| shopping_cost | decimal | N | Shipping cost of the order |
| tax_cost | decimal | N | Tax amount of the order |
| items | JSONArrayString | N | The breakdown details of each item in the order |
items object
| Name | Type | Required | Description |
|---|---|---|---|
| item_id | string | N | The unique identifier of a payment in the merchant’s system |
| item_name | string | N | Name of an item purchase |
| item_price | decimal | N | Unit price of an item |
| price_currency | string | N | ISO 4217 3-character currency code. This is the currency associated with the order amount field |
| item_quantity | integer(int64) | N | Quantity of an item ordered |
sub_merchant object
| Name | Type | Required | Description |
|---|---|---|---|
| sub_merchant_id | string | N | ID of sub merchant |
| sub_merchant_name | string | N | Name of sub merchant |
Request Example
Response
Response Result
| Name | Type | Description |
|---|---|---|
| code | string | Return code |
| msg | string | Return message |
| data | Array | Return data |
Response data Array 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 | The total payment amount, in the order currency |
| order_currency | string | ISO 4217 3-character currency code. This is the currency associated with the order amount field |
| created_time | integer(int64) | Order creation time in 13-digit e.g. 1720508269092 |
| expire_time | integer(int64) | Order expiration time in 13-digit e.g. 1720508269092 |
| payment_info | array | Payment detail information |
payment_info object
| Name | Type | Description |
|---|---|---|
| payment_address | string | Wallet address that receives payment |
| token_symbol | string | crypto asset symbol |
| 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 |