Payment
Create Payment order
Create a payment order using the Cregis checkout page
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 60) 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
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 |