POSTINBOUND EVENT

Payin Callback

Sent to the callbackUri you provided when creating the payment, every time the payin transitions to a new state (completed, canceled, expired, or dispute). The payload is a JSON object signed with HMAC-SHA256 in the lowercase `signature` header (computed over the compact JSON body using your secret key). Respond with HTTP 2xx within 10 seconds to acknowledge — any non-2xx response or timeout triggers automatic retries with exponential backoff for up to 24 hours.

{your callbackUri}

Verify the event signature

Validate the HMAC-SHA256 signature before processing the payload. Authentication guide →

Payload fields#

Required only

statusbooleanrequired

Top-level success flag. Always true for successfully delivered callbacks — the actual payment outcome is in result.state.

Example true

result.idstring (uuid)required

Payment UUID — same value as payment_id from the create-payment response. Use this to look up the payment in your system.

Example f96aafed-144f-4b7d-90f2-43d79c220

result.orderIdstringrequired

Your original orderId passed at creation, echoed back for reconciliation.

Example 1bf846dc-7a17-417e-a22e-5a2d0414

result.statestringrequired

Payin lifecycle state at the moment of the callback. One of: pending, expired, canceled, dispute, completed. Only completed credits funds to your balance. See the Lifecycle States section in Get Payment Status for the full semantics. Treat the same (id, state) pair as idempotent.

Example completed

result.amountstring (decimal)required

Final amount actually settled, as a decimal string. May differ from init_amount when the customer transferred a slightly different amount that was still accepted.

Example 2000.00

result.init_amountstring (decimal)required

Original amount you requested at payment creation. Compare against amount to detect partial/over-payments.

Example 2000.00

result.currencystringrequired

ISO-4217 currency code (e.g. ARS, BRL, CLP).

Example ARS

result.methodstringrequired

Payment method used: cbu or qr.

Example cbu

result.ratestring (decimal)required

Exchange rate (local currency → USDT) locked at the moment of settlement.

Example 1471.52

result.datetimenumber (unix)required

Unix timestamp (seconds) of the state transition.

Example 1780064003

result.created_atstring (ISO 8601)required

ISO 8601 UTC timestamp of when the payment was originally created.

Example 2026-05-29T14:13:23.624Z

result.messagestring | nulloptional

Free-form message — populated when state is canceled, expired, or dispute to describe the reason. null on success.

Example null

result.file_urlstring | nulloptional

URL to the bank receipt / proof-of-transfer image when available. null for most QR payments.

Example null

Need help with your integration?Contact the team