Cancel Order

Cancel a payment order that has not yet been fully paid. This endpoint uses header-based HMAC signing.

Endpoint

POST /v4.0.0/api/orders/cancel

Request Body

Field	Type	Required	Description
payOrderId	string	Yes	HashNut order ID

payOrderId is the only body field — merchant identity comes from the request signature and the order's own ownership record, so there is no accessKeyId to pass.

Request Headers

See Authentication for the required HMAC signing headers:

• hashnut-request-uuid
• hashnut-request-timestamp
• hashnut-request-sign

Example Request

{
  "payOrderId" : "01KWCGJ443GX4SCBQK53CTF04A"
}

Example Response

{
  "code" : 0,
  "msg" : "success",
  "ui" : null,
  "version" : null,
  "count" : 0,
  "data" : null
}

On success data is null — no order object is returned. Call Query Order to confirm the resulting state.

Cancellation Rules

• Orders in state INIT (0) and PAID (1) can be canceled. PAID means one underpayment has arrived and a top-up is pending.
• Orders past PAID — CONFIRMING (2), SUCCESS (3), FINISH (4) — cannot be canceled.
• An order already in CANCELED (-3) cannot be canceled again.
• The order must belong to the merchant that owns the api key.
• Cancellation is irreversible.

WARNING

Canceling an order releases its receipt address back to the address pool. If the customer sends funds to that address afterwards, the payment may be attributed to another order that reused the address, or go undetected. Make sure your frontend stops displaying the payment address as soon as the order is canceled.

Common Errors

Business errors all come back as code = -2 plus a msg carrying the reason (full code list under Create Order):

msg	Meaning
pay order not exist or canceled	No such order, or it is already canceled
pay order already full paid, can not cancel	The order is past PAID and cannot be canceled
can not find api key	The order's api key does not exist or is not an api key
invalid request sign	Header signature mismatch
request timestamp out of allowed window, ...	Timestamp outside the ±5 minute window
duplicate request uuid, replay rejected	hashnut-request-uuid was reused
pay order not created by current merchant	The order does not belong to the merchant behind the signing api key