WEBHOOK

Order Payment Notification (Webhook)

A server-initiated callback. Implement a receiving endpoint in your service.

Based on the callback_url filled in when creating the order, Cregis notifies the caller through this callback URL when the order status changes. For details, see the callback_url parameter in the Create Order API. This API is a callback notification request initiated by Cregis to the business party and only generates one callback:

Callback Events

Callback event name (event_name)	Callback event type (event_type)	Description
order	expired	Order timeout notification
order	paid	Order payment completed notification
order	paid_partial	Order partial payment notification
order	paid_over	Order overpayment notification
order	refunded	Order refund notification
order	paid_remain	Order Additional Payment Notification

Request Method

Cregis initiates the callback request with HTTP POST application/json. The callback is successful when the response content is the success string; otherwise, the callback fails.

If a callback fails, you can manually retry it from the Callback Error Page in the Cregis portal to preserve business logic completeness.

Request

Callback Payload

application/json

noncestring
6-character random string.
pidinteger<int64>
Project ID.
signstring
Signature.
timestampinteger<int64>
Timestamp.
event_namestring
enum: "order"
Event name.
event_typestring
enum: "expired", "paid", "paid_partial", "paid_over", "refunded", "paid_remain"
Event type.
dataPayment result callback fields | Expired callback fields | Refund callback fields | Remaining payment callback fields
Order information.
Match one event payload shape
Option 1 · Payment result callback fields
order_amountstring
Order Amount
order_currencystring
Order currency code, that is, an ISO 4217 currency code such as CNY or HKD. See the Order Currency List.
cregis_idstring
Cregis order ID.
order_idstring
Merchant Order Id
statusstring
enum: "new", "paid", "expired", "paid_over", "paid_partial", "canceled"
Order status

newpending payment

paidpaid

expiredorder exceeded the validity period

paid_overpayment exceeds the order amount

paid_partialpayment is less than the order amount

canceledorder canceled, such as when refund is completed

valid_timeinteger<int32>
Order timeout duration, in minutes.
remarkstring
Order remark information.
payer_idstring
Payer ID identifier.
payer_namestring
Payer name.
payer_emailstring
Payer email.
created_timeinteger<int64>
Order creation time, 13-digit timestamp.
cancel_timeinteger<int64>
Order cancellation time, 13-digit timestamp.
payment_addressstring
Deposit address.
receive_amountstring
Order amount after exchange-rate conversion.
receive_currencystring
Order currency unit after exchange-rate conversion.
pay_amountstring
Actual received amount.
pay_currencystring
Received currency unit.
exchange_ratestring
Exchange rate.
tx_idstring
Transaction hash.
transact_timeinteger<int64>
Order payment completion time, 13-digit timestamp.
Option 2 · Expired callback fields
order_amountstring
Order Amount
order_currencystring
Order currency code, that is, an ISO 4217 currency code such as CNY or HKD. See the fiat currency information list API.
cregis_idstring
Cregis order ID.
order_idstring
Merchant Order Id
statusstring
enum: "new", "paid", "expired", "paid_over", "paid_partial", "canceled"
Order status

newpending payment

paidpaid

expiredorder exceeded the validity period

paid_overpayment exceeds the order amount

paid_partialpayment is less than the order amount

canceledorder canceled, such as when refund is completed

valid_timeinteger<int32>
Order timeout duration, in minutes.
remarkstring
Order remark information.
payer_idstring
Payer ID identifier.
payer_namestring
Payer name.
payer_emailstring
Payer email.
created_timeinteger<int64>
Order creation time, 13-digit timestamp.
cancel_timeinteger<int64>
Order cancellation time, 13-digit timestamp.
Option 3 · Refund callback fields
order_amountstring
Order Amount
order_currencystring
Order currency code, that is, an ISO 4217 currency code such as CNY or HKD. See the fiat currency information list API.
cregis_idstring
Cregis order ID.
order_idstring
Merchant Order Id
statusstring
enum: "new", "paid", "expired", "paid_over", "paid_partial", "canceled"
Order status

newpending payment

paidpaid

expiredorder exceeded the validity period

paid_overpayment exceeds the order amount

paid_partialpayment is less than the order amount

canceledorder canceled, such as when refund is completed

valid_timeinteger<int32>
Order timeout duration, in minutes.
remarkstring
Order remark information.
payer_idstring
Payer ID identifier.
payer_namestring
Payer name.
payer_emailstring
Payer email.
created_timeinteger<int64>
Order creation time, 13-digit timestamp.
cancel_timeinteger<int64>
Order cancellation time, 13-digit timestamp.
payment_addressstring
Deposit address.
receive_amountstring
Order amount after exchange-rate conversion.
receive_currencystring
Order currency unit after exchange-rate conversion.
pay_amountstring
Actual received amount.
pay_currencystring
Received currency unit.
exchange_ratestring
Exchange rate.
tx_idstring
Transaction hash.
transact_timeinteger<int64>
Order payment completion time, 13-digit timestamp.
refund_requestedstring
enum: "yes", "no"
Whether the order has a refund

nono refund record

yesrefund record exists

typeinteger
enum: 0, 1
Refund type

0partial refund

1full refund

refund_idstring
Cregis refund order ID.
refund_addressstring
Refund recipient on-chain address.
refund_currencystring
For the refund order token, pass the crypto token_name, such as USDT-BEP20 or USDT-TRC20.
refund_amountstring
Refund amount.
refund_feestring
Gas fee required for the refund.
actual_refund_amountstring
Actual refund amount after miner fees are deducted = refund order amount - gas_fee_amount.
refund_statusinteger
enum: 0, 1, 2
Refund status

0refund processing

1refund successful

2refund failed

refund_tx_idstring
Refund transaction hash.
refund_created_timeinteger<int64>
Refund order creation time, 13-digit timestamp

e.g. 1720508269092, i.e. 2024-07-09 14:57:49 092
refund_transact_timeinteger<int64>
Refund order last update time, 13-digit timestamp

e.g. 1720508269092, i.e. 2024-07-09 14:57:49 092
Option 4 · Remaining payment callback fields
order_amountstring
Order Amount
order_currencystring
Order currency code, that is, an ISO 4217 currency code such as CNY or HKD. See the fiat currency information list API.
cregis_idstring
Cregis order ID.
order_idstring
Merchant Order Id
statusstring
enum: "new", "paid", "expired", "paid_over", "paid_partial", "canceled"
Order status

newpending payment

paidpaid

expiredorder exceeded the validity period

paid_overpayment exceeds the order amount

paid_partialpayment is less than the order amount

canceledorder canceled, such as when refund is completed

valid_timeinteger<int32>
Order timeout duration, in minutes.
remarkstring
Order remark information.
payer_idstring
Payer ID identifier.
payer_namestring
Payer name.
payer_emailstring
Payer email.
created_timeinteger<int64>
Order creation time, 13-digit timestamp.
cancel_timeinteger<int64>
Order cancellation time, 13-digit timestamp.
payment_addressstring
Deposit address.
receive_amountstring
Order amount after exchange-rate conversion.
receive_currencystring
Order currency unit after exchange-rate conversion.
pay_amountstring
Actual received amount.
pay_currencystring
Received currency unit.
exchange_ratestring
Exchange rate.
tx_idstring
Transaction hash.
transact_timeinteger<int64>
Order payment completion time, 13-digit timestamp.
additional_pay_currencystring
Remaining payment currency unit.
additional_pay_amountstring
Remaining payment amount.
additional_payment_addressstring
Remaining payment address.
additional_payment_tx_idstring
Remaining payment transaction hash.
additional_payment_transact_timeinteger<int64>
Remaining payment order completion time, 13-digit timestamp.

Responses

200Your server must return HTTP 200 and a response body strictly equal to plain text `success` (`text/plain`).

text/plain

string

Request example

application/json

{
  "nonce": "m8jisx",
  "pid": 1382528827416576,
  "sign": "cebd2bfd56766f1143dc40d078b64dac",
  "timestamp": 1687848653294,
  "event_name": "order",
  "event_type": "paid",
  "data": {
    "order_amount": "100",
    "order_currency": "HKD",
    "cregis_id": "po1420761885130752",
    "order_id": "merchant_order_id_123",
    "status": "paid",
    "valid_time": 30,
    "remark": "Product purchase",
    "payer_id": "p_001",
    "payer_name": "John Doe",
    "payer_email": "[email protected]",
    "created_time": 1719993183015,
    "cancel_time": 1719994983015,
    "payment_address": "TMainWalletAddressXXXXXXXXXXXXXXXXXX",
    "receive_amount": "12.86",
    "receive_currency": "USDT",
    "pay_amount": "100",
    "pay_currency": "USDT",
    "exchange_rate": "0.1286",
    "tx_id": "0x0502f2bfd96cd0f55edea3343513940f3af7fe594eae77f08d2f46ea24829b11",
    "transact_time": 1719993183325
  }
}

Response example

200 · text/plain

success