Confirm Payment

Manually confirm a payment by supplying its on-chain transaction hash. This endpoint uses body-level accessSign authentication.

TIP

HashNut detects on-chain payments automatically in most cases, so you usually do not need this endpoint. Use it when automatic detection is taking too long, or when you want to hand HashNut the transaction hash to speed up confirmation.

Endpoint

POST /v4.0.0/pay/orders/confirm

Request Body

Field	Type	Required	Description
payOrderId	string	Yes	HashNut order ID (26-character ULID)
merchantOrderId	string	Yes	Your order identifier
payTxId	string	Yes	On-chain transaction hash proving payment; must match that chain's format
accessSign	string	Yes	The accessSign returned by Create Order, echoed verbatim

NOTE

For Tron orders, a 0x prefix on payTxId is stripped server-side — both forms are accepted.

Example Request

{
  "payOrderId": "01KWCGJ443GX4SCBQK53CTF04A",
  "merchantOrderId": "8b7eb554-b847-4450-9",
  "payTxId": "9f3c1d7e5a2b48c0913f6ed4a7b25c8e1049fba3762d5e08c41b9a6f3d072e21a",
  "accessSign": "BE333D8F1A561EFFCA7C0DCB88BC60C1EE67A00E6FBE02333270B8C68564679E"
}

Example Response

{
  "code": 0,
  "msg": "success",
  "data": null
}

A successful call means the transaction hash was accepted, not that the order is paid:

• If HashNut had already observed that transaction, the order moves to CONFIRMING (2) immediately, then to SUCCESS (3) once it reaches the required confirmation count.
• If it has not been observed yet, the hash is recorded and the order stays at INIT (0) until the chain listener picks it up.

Either way, read the real state with Query Order — do not treat a successful call as a successful payment. State changes also fire a notification.

When the Order Is Partially Paid

If the order is currently PAID (1) — meaning it was underpaid once and is awaiting a top-up — this endpoint attaches payTxId to the most recent supplement record rather than to the order itself. A pending supplement record must already exist, otherwise the call returns no supplement found.

Common Errors

msg	Meaning
malformed pay order id	payOrderId is not a valid 26-character ULID
pay order not exist	No such order
invalid tx id	payTxId does not match that chain's transaction hash format
access sign verify failed	accessSign mismatch — use the value returned by Create Order
order already failed	The order is failed / expired / canceled (state < 0)
transaction already paid other order	That transaction was already used for a different order
transaction already paid for this order	That transaction was already submitted once
no supplement found	The order is PAID but has no pending supplement record
order already paid or confirmed	The order is already paid and the submitted hash differs from the recorded one

WARNING

payTxId must be a real transaction that actually paid the order's receiptAddress with a matching chain and token. On a token or receipt-address mismatch the call errors out and the order state is left unchanged.

Automatic Detection vs. Manual Confirmation

Aspect	Automatic detection	Manual confirmation
Trigger	HashNut watches the blockchain	The merchant calls this endpoint
Transaction hash	Discovered automatically	Supplied by the merchant
When to use	The default flow	A fallback when detection lags
State after the call	N/A	Already observed → CONFIRMING (2); not yet → still INIT (0)