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

EventWhen it fires
SYNTHETIC_STATUS_UPDATEAny status change on the synthetic (ACTIVE, COMPLETED, CANCELLED)
PAYMENT_REFUNDA full or partial refund has been generated for a completed payment
SYSTEM_NOTICEOperational incident affecting the payment (recommended)

Configure listeners via:


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

Refunds 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), the SYNTHETIC_STATUS_UPDATE webhook alone is not enough to detect them. You must listen to PAYMENT_REFUND and 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

PurposeEndpoint
Get single syntheticGET /v2/synthetics/{syntheticAnyId}
List syntheticsGET /v2/synthetics

Use webhooks as the primary signal and these queries for recovery or replay.


Did this page help you?