Callback notification interface (customized by the merchant)
POST
notifyUrl
⚠️ [Security Requirement · Mandatory] Query the order before crediting#
A callback only means "the order status may have changed". It must NOT be used on its own as the basis for crediting balances, delivering goods or releasing funds. After receiving a callback, the merchant MUST:
1.
IP allowlist: accept callbacks only from TarsPay's callback egress IPs and reject all other sources. The IP list is not published in this document — please obtain it from your TarsPay account manager.
2.
Verify the signature: verify the X-RESP-SIGNATURE header with the TarsPay public key; discard the callback if verification fails (see below).
3.
Query the order: call "Get deposit order status" /api/payInInfo or "Get withdraw order" /api/payOutInfo, and treat the query result as the source of truth.
4.
Reconcile: mchOrderNo, payOrderId, amount, currency and state in the query result must match your local order. If anything differs, do not credit and raise an alert.
5.
Idempotency: credit only when the query result is a final success state, and credit each order only once.
6.
Acknowledge: always reply with plain text OK once the callback is received. If the query fails (e.g. timeout), retry the query later — never credit based on the callback content alone.
Read the raw request body string. ⚠️ Do not parse it into an object and re-serialize it: any change in field order, whitespace or null fields will break verification.
2.
Compute digest = SHA256(SHA256(raw bytes)).
3.
Verify X-RESP-SIGNATURE (hex-decoded DER r, s) with the TarsPay public key on curve secp256k1.
4.
If verification fails, discard the callback. If it passes, still query the order as required above before crediting.
The interface is implemented by the merchant themselves. After receiving our callback, regardless of the business status, as soon as you receive our notification, please return the string OK and no need to return JSON formatted data. The merchant is responsible for ensuring the idempotence of the business, and the notification is processed only once regardless of the number of times it is received.
