Cregis Developer Docs
POST/api/v2/checkout

Create Order

Create a new crypto payment order or pending payment bill from the merchant backend. On success, the API returns cregis_id (the Cregis system transaction ID, which must be stored) and checkout_url (a time-limited checkout link).

Rate limit: 1000 requests/minute

Request

Request Body

required

application/json
  • noncestringrequired

    6-character random string.

  • pidinteger<int64>required

    Unique Cregis ID of this acquiring project.

  • signstringrequired

    Digital signature for this API request to prevent unauthorized requests. See the Signature Rules section.

  • timestampinteger<int64>required

    13-digit Unix timestamp format.

  • order_amountstringrequired

    Total payment amount. If order_currency is a fiat currency, the amount is calculated in fiat; if order_currency is a cryptocurrency, the amount is calculated in cryptocurrency.

  • order_currencystringrequired

    See the Order Currency List.

    • If the order currency is a cryptocurrency, examples include USDT and ETH.
    • If the order currency is fiat, enter the ISO 4217 3-letter currency code, such as HKD or USD.
  • order_idstringrequired

    Merchant internal order ID. Maximum 128 characters.

  • payer_idstringrequired

    Payer ID.

  • valid_timeintegerrequired

    Unit: minutes (integer from 10 to 1440).

    Order validity period. After the validity period expires, the order can no longer be paid.

  • success_urlstringrequired

    After payment succeeds, when the payer clicks the "Return to Store" button, the payer is redirected to this URL. Make sure the URL includes http:// or https://.

  • cancel_urlstringrequired

    If the payer does not pay or clicks the "Cancel" button, they are redirected to this URL. Make sure the URL includes http:// or https://.

  • order_detailsstring<json>

    Order item details, including price, quantity, and product description. This is displayed in the order details section on the Cregis checkout page.

    JSON 内部字段application/json
    • shopping_costnumber

      Shipping cost.

    • tax_costnumber

      Sales tax.

    • itemsarray

      Tax item.

      Array items

      • item_idstring

        Unique item ID.

      • item_namestring

        Item name.

      • item_pricenumber

        Item price.

      • price_currencystring

        See the Order Currency List.

      • item_quantityinteger<int64>

        Item quantity.

  • sub_merchantstring<json>

    Merchants can use this field to record an internal sub-merchant ID.

    JSON 内部字段application/json
    • sub_merchant_idstring

      Unique sub-merchant ID.

    • sub_merchant_namestring

      Merchant name.

  • payer_emailstring

    Payer email. Required if accept_partial_payment or accept_over_payment is false.

  • tokensstring

    This field restricts the tokens that you allow customers to pay with. If left empty, all supported tokens are accepted as payment tokens. See the Payment Currency List.

    For parameter values, refer to the payment currency and payment network units on the payment and settlement parameters page, for example USDT-BEP20 and USDT-TRC20.

  • payer_namestring

    Payer name. Maximum 32 characters.

  • stablecoin_realtime_ratestring
    default: "false" · enum: "true", "false"

    Default: false

    • falseUSDT/USDC to USD uses a fixed 1:1 exchange rate.
    • trueUSDT/USDC to USD uses the real-time exchange rate from CoinMarketCap.
  • underpaid_tolerancenumber<float>
    default: 0

    Partial-payment limit. The lower tolerance for the payment amount accepted by this order, denominated in order_currency. Default: 0.

    This lower tolerance is used to calculate the minimum acceptable payment amount for the order. Status rules:

    • paidorder_amount - underpaid_tolerance <= actual payment amount <= order_amount + overpaid_tolerance
    • partial_paidactual payment amount < order_amount - underpaid_tolerance
    • overpaidorder_amount + overpaid_tolerance < actual payment amount

    Example: if order_currency is HKD and underpaid_tolerance is 3.50:

    • paidthe order is underpaid by 3.50 HKD or less
    • partial_paidthe order is underpaid by more than 3.50 HKD
  • overpaid_tolerancenumber<float>
    default: 0

    Overpayment limit. The upper tolerance for the payment amount accepted by this order, denominated in order_currency. Default: 0.

    This upper tolerance is used to calculate the maximum acceptable payment amount for the order. Status rules:

    • paidorder_amount - underpaid_tolerance <= actual payment amount <= order_amount + overpaid_tolerance
    • partial_paidactual payment amount < order_amount - underpaid_tolerance
    • overpaidorder_amount + overpaid_tolerance < actual payment amount

    Example: if order_currency is HKD and overpaid_tolerance is 3.50:

    • paidthe order is overpaid by 3.50 HKD or less
    • overpaidthe order is overpaid by more than 3.50 HKD
  • accept_partial_paymentstring
    default: "true" · enum: "true", "false"

    Default: "true"

    • falseif the order does not accept partial payments and the actual payment amount is less than order_amount, the payer must top up the order or proceed with a refund.
    • trueif the order accepts partial payments, the payer does not need to top up or refund.
  • accept_over_paymentstring
    default: "true" · enum: "true", "false"

    Default: "true"

    • falseif the order does not accept overpayments and the actual payment amount is greater than order_amount, the payer must refund the difference.
    • trueif the order accepts overpayments, the payer does not need to refund the difference.
  • callback_urlstring

    Cregis sends order status update notifications to this callback URL. For callback details, see Order Payment Notification.

  • languagestring
    default: "en" · enum: "en", "tc", "sc"

    Default: en

    Specifies the default language for the checkout or email. Available values:

    • enEnglish
    • tcTraditional Chinese
    • scSimplified Chinese
  • remarkstring

    Merchant remark for this payment order. Maximum 256 characters.

Responses

200Success
application/json
  • codestring

    Response code.

  • msgstring

    Response message.

  • dataobject
    • cregis_idstring

      Cregis unique identifier.

    • checkout_urlstring

      Checkout URL.

    • merchant_namestring

      Merchant name displayed on the checkout.

    • merchant_logo_urlstring

      Merchant logo displayed on the checkout.

    • order_amountstring

      Order Amount

    • order_currencystring

      Order currency code.

    • created_timeinteger<int64>

      Order creation time in 13-digit Unix timestamp format

      e.g. 1720508269092, i.e. 2024-07-09 14:57:49 092

    • expire_timeinteger<int64>

      Order expiration time in 13-digit Unix timestamp format

      e.g. 1720508269092, i.e. 2024-07-09 14:57:49 092

    • payment_infoarray<object>

      Order-related information.

      Array items · object

      • payment_addressstring

        Deposit address.

      • token_symbolstring

        Payment token symbol. The asset code of the cryptocurrency, such as USDT, BTC, or ETH. It does not include the blockchain network.

      • blockchainstring

        Currency network.

      • token_namestring

        Network-specific token display name. Identifies the token variant on the specified blockchain, such as USDT-TRC20 or USDT-ERC20.

      • logo_urlstring

        Currency logo URL.

      • token_decimalsinteger

        Token decimals.

      • receive_amountstring

        Order amount after exchange-rate conversion.

      • receive_currencystring

        Order currency code after exchange-rate conversion.

      • exchange_ratestring

        Exchange rate.

      • asset_logostring

        Asset identifier logo.