After the payment
After the payment
After payment submission, track final outcome with webhooks and query endpoints.
Prerequisites
- A configured webhook endpoint. See Webhooks for configuration.
- A submitted payment via
POST /v2/synthetics/qr-payment. See Make a payment.
Webhooks to listen
| Event | When it fires |
|---|---|
SYNTHETIC_STATUS_UPDATE | Any status change on the synthetic (ACTIVE, COMPLETED, CANCELLED) |
PAYMENT_REFUND | A full or partial refund has been generated for a completed payment |
SYSTEM_NOTICE | Operational incident affecting the payment (recommended) |
Configure listeners via:
SYNTHETIC_STATUS_UPDATE payload example
SYNTHETIC_STATUS_UPDATE payload example{
"event": "SYNTHETIC_STATUS_UPDATE",
"data": {
"id": "65b2c3d4e5f6a7b8c9d0e1f2",
"numberId": "98765",
"externalId": "my-external-ref-001",
"userId": "64a1b2c3d4e5f6a7b8c9d0e2",
"userNumberId": "12345",
"userExternalId": "ext-001",
"sessionId": "session-abc-123",
"status": "COMPLETED",
"type": "QR3_PAYMENT",
"details": {
"depositAddress": "0x1a2b3c4d5e6f...",
"paymentAssetAmount": "15000.00",
"paymentAsset": "ARS",
"paymentAgainstAmount": "12.00",
"paymentAgainst": "USDT",
"paymentPrice": "1250.50",
"priceExpireAt": "2026-02-21T15:30:00.000Z",
"qrType": "QR3",
"nationalId": "2026022100009876"
},
"currentStage": 2,
"stages": {
"0": {
"stageType": "ORDER",
"asset": "USDT_ARS",
"operation": "SELL",
"amount": "12.00"
},
"1": {
"stageType": "WITHDRAW",
"asset": "ARS",
"network": "QR3",
"amount": "15000.00"
}
},
"creationTime": "2026-02-21T15:25:30.000Z",
"updatedAt": "2026-02-21T15:26:45.000Z"
}
}PAYMENT_REFUND payload example
PAYMENT_REFUND payload exampleRefunds can be full or partial, and multiple partial refunds can be emitted over time.
Since partial refunds do not change the synthetic status (it stays
COMPLETED), theSYNTHETIC_STATUS_UPDATEwebhook alone is not enough to detect them. You must listen toPAYMENT_REFUNDand use the cumulative refund fields.
{
"event": "PAYMENT_REFUND",
"data": {
"refundId": "9b1c8e7a-2f4d-4a6b-8c3e-1d5f7a9b0c2d",
"amount": "5000.00",
"totalAmount": "10000.00",
"asset": "ARS",
"amountToRefund": "4.00",
"totalAmountToRefund": "8.00",
"assetToRefund": "USDT",
"paymentNumberId": "98765",
"paymentExternalId": "my-external-ref-001",
"networkId": "xxx-xxx-xxx-xxx",
"refundReason": "Refund",
"partial": true,
"refundedAt": "2026-02-21T15:35:00.000Z",
"userId": "64a1b2c3d4e5f6a7b8c9d0e2",
"userNumberId": "12345",
"userExternalId": "ext-001"
}
}Refund semantics
Each PAYMENT_REFUND event carries a refundId that uniquely identifies that individual refund. A single payment can produce several refunds over time (full or partial), and all of them share the same paymentNumberId / paymentExternalId.
Deduplicate by refundId. The same event may be delivered more than once, so treat refundId as your idempotency key and skip any event whose refundId you have already processed. Do not deduplicate by paymentNumberId, paymentExternalId, or networkId — those are shared across every refund of the same payment, so deduping by them would incorrectly drop legitimate partial refunds.
To track cumulative state per payment, group refunds by paymentNumberId (or paymentExternalId) and rely on the totalAmount / totalAmountToRefund fields rather than summing the per-event amount yourself. Each refund also appends a REFUND stage to the synthetic, so you can reconstruct the full refund history from GET /v2/synthetics/{syntheticAnyId}.
Always check partial, amountToRefund, and the cumulative totalAmount / totalAmountToRefund fields. A payment stays COMPLETED while refunds are partial, and only moves to CANCELLED once all funds have been returned.
Query endpoints
| Purpose | Endpoint |
|---|---|
| Get single synthetic | GET /v2/synthetics/{syntheticAnyId} |
| List synthetics | GET /v2/synthetics |
Use webhooks as the primary signal and these queries for recovery or replay.
Updated 5 months ago