Webhooks > Payment

When a payment on an invoice reaches a new status in the Trace AR application, the webhook will be called and the following data format will be POSTED to the provided webhook URL. Each status is sent once per payment, so a payment that is captured and later settled produces two calls, distinguished by the status field. Declined and failed refunds are not sent unless your integration is configured to receive them.

Un reembolso se envía como su propio pago, con is_refund establecido en true y orig_payment establecido con el _id del pago que reembolsó.

Las cargas del webhook usan claves en snake_case, a diferencia del camelCase que usa la propia API 4.0. Los montos son centavos enteros.

Esta estructura 4.0 solo se envía a los sitios cuya versión de webhook está establecida en 4.0, que es la predeterminada para los sitios recién creados. Un sitio que se quede en una versión anterior del webhook sigue recibiendo la carga anterior, donde los montos son dólares decimales.

Muestra de carga útil de webhook - Pago exitoso

			
{
  "action": "payment",
  "data": {
    "_id": "6385807aa90735097a811cf6",
    "display_name": "VISA **** 5123",
    "site": "6201825a0cf5e23261a08646",
    "customer": "649dc5bb468bd5b5d863c7d1",
    "type": "payment_card",
    "sub_type": "visa",
    "amount": 4964,
    "totals": {
      "subtotal": 3000,
      "taxes": 300,
      "total": 3300,
      "extra_fees": 1164,
      "tips": 500
    },
    "paid_on": "2026-05-13T19:29:28Z",
    "status": "captured",
    "is_refund": false,
    "allocations": [
      {
        "ref_type": "Invoice",
        "ref": "649dc5bb468bd5b5d863c7d2",
        "amount": 3300
      }
    ],
    "payment_transaction_events": [
      {
        "type": "sale",
        "amount": 4964,
        "successful": true,
        "created_at": "2026-05-13T19:29:28Z",
        "transaction_id": "32483237915423321"
      }
    ]
  }
}

Tipos de Datos

			
type PaymentType = "payment_card" | "ach" | "eft" | "apple_pay" | "google_pay" | "oxxo" | "spei" | "bnpl" | "dlocal" | "cash" | "check" | "other"

type PaymentSubType = "visa" | "mastercard" | "amex" | "discover" | "diners" | "jcb" | "checking" | "savings" | "oxxo" | "spei" | "bnpl" | "google_pay" | "dlocal" | "cash" | "check" | "other"

type PaymentStatus = "failed" | "declined" | "created" | "expired" | "cancelled" | "authorized" | "captured" | "voided" | "settled" | "returned" | "refundFailed" | "refunded" | "refundSettled" | "chargebacked" | "refundRequested"

type PaymentTransactionEventType = "create" | "verify" | "auth" | "cancel" | "expire" | "decline" | "void" | "capture" | "sale" | "return" | "batch" | "settle" | "refund" | "chargeback" | "misc" | "activatePaymentDevice"