⚠️ [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.
This path is only used to show the callback message structure. The actual request URL is the notifyUrl passed in when the merchant places the order, and TarsPay actively sends a POST application/json request to it.TarsPay only sends notifications for orders in a final state. After verifying the signature and completing idempotent processing, the merchant must return plain text OK (case-insensitive).
