WebhooksPago

Webhook de pago

Esta página describe el formato del webhook enviado por la plataforma cada vez que se actualiza el estado de un pago.

Descripción

El webhook de pagos se envía automáticamente cada vez que cambia el estado del pago, permitiendo que el sistema del integrador permanezca sincronizado en tiempo real.

Las notificaciones se envían mediante solicitudes HTTP usando el método POST y el formato JSON.

Estándar de Zona Horaria

Todos los campos de fecha y hora enviados en los webhooks utilizan el estándar ISO 8601 en la zona horaria UTC (UTC+00:00), garantizando consistencia independientemente de la zona horaria del integrador. Para evitar discrepancias causadas por horarios locales o cambios de horario de verano, se recomienda mantener los valores en UTC para almacenamiento y procesamiento, realizando la conversión a la zona horaria local solo a nivel de presentación.

Validación Opcional del Webhook

Para aumentar la seguridad, los webhooks registrados directamente en el panel pueden incluir una firma enviada en el header X-Signature: <firma-en-base64>, permitiendo validar la autenticidad de la notificación recibida. Esta firma es generada por la plataforma utilizando HMAC con SHA-256 sobre el cuerpo del webhook, en formato JSON, usando un secreto compartido WEBHOOK_SECRET y codificada en Base64. El integrador puede reproducir el mismo cálculo en su sistema usando el mismo secreto y el payload recibido. Si la firma generada coincide con la enviada en el header, el webhook se considera legítimo e íntegro. Si son diferentes, la solicitud puede haber sido alterada o no enviada por la plataforma.

Esta validación está disponible solo para webhooks registrados en el panel. Los webhooks enviados a una URL informada dinámicamente mediante notificationUrl no incluyen la firma X-Signature.

La validación por firma es opcional, pero altamente recomendada siempre que el webhook sea configurado desde el panel para garantizar mayor seguridad en la comunicación.

Endpoint de Notificación

La URL de notificación debe informarse al momento de crear el pago mediante el campo notificationUrl.

El endpoint debe ser accesible públicamente y responder con HTTP 200 para confirmar la recepción del webhook.

Además, las notificaciones de pago también pueden realizarse mediante webhooks in-bound, configurados directamente en el panel del gateway. En este modelo, el endpoint se registra previamente y se ejecuta automáticamente en cada cambio de estado del pago.

Estado del Pago

Los valores posibles para el campo status son:

PENDING – Pago creado y pendiente de confirmación.
PROCESSING – Pago en procesamiento o análisis.
PAID – Pago confirmado con éxito.
REFUSED – Pago rechazado por el emisor o sistema antifraude.
REFUNDED – Pago reembolsado total o parcialmente.
MED – Disputa en análisis preliminar, esperando evidencias.
CHARGEDBACK – Disputa confirmada con reversión del pago.

Formato del Payload

A continuación se muestran ejemplos del payload enviado en el webhook según el método de pago.

PIX · JSON

{
  "id": "pay_01HXYZ123ABC456DEF789",
  "amount": 10000,
  "method": "PIX",
  "currency": "BRL",
  "status": "PAID",
  "description": "Pagamento de teste via PIX",
  "installments": 1,
  "payer": {
    "name": "John Doe",
    "taxId": "12345678900",
    "email": "john.doe@example.com",
    "phone": "11999990000"
  },
  "externalRef": "order_123456",
  "notificationUrl": "https://example-webhook.test/notifications",
  "metadata": null,
  "utms": {
    "utmSource": "google",
    "utmMedium": "cpc",
    "utmCampaign": "black-friday-2026",
    "utmContent": "banner-topo",
    "utmTerm": "tenis-de-corrida",
    "src": "blog-artigo-1",
    "sck": "lista-quente"
  },
  "paidAt": "2026-01-15T16:51:42.782Z",
  "refundedAt": null,
  "createdAt": "2026-01-15T13:44:25.838Z",
  "updatedAt": "2026-01-15T16:51:42.782Z",
  "orderId": null,
  "data": {
    "method": "PIX",
    "copypaste": "00020101021226850014br.gov.bcb.pix2563api.gateway.test/pix/123e4567-e89b-12d3-a456-4266141740005204000053039865802BR5920GATEWAY TESTE6009SaoPaulo61080540900062070503***6304ABCD",
    "e2e": "E1234567890123456789012345678901"
  },
  "splits": [
    {
      "amount": 10000,
      "currency": "BRL",
      "percent": 100,
      "storeId": "store_test_001",
      "splitId": null
    }
  ],
  "items": [
    {
      "quantity": 1,
      "name": "Produto Teste",
      "price": 1000,
      "type": "PHYSICAL"
    }
  ],
  "delivery": {
    "fee": 1500,
    "address": {
      "country": "BR",
      "state": "SP",
      "city": "São Paulo",
      "district": "Centro",
      "street": "Rua Exemplo",
      "number": "123",
      "complement": "Apto 45",
      "zipCode": "01001-000",
    }
  },
}

Tarjeta de Crédito · JSON

{
  "id": "pay_test_cc_01HZ9ABCDEF123456",
  "amount": 1000,
  "method": "CREDIT_CARD",
  "currency": "BRL",
  "status": "PAID",
  "description": "Compra de produto de teste",
  "installments": 3,
  "payer": {
    "name": "John Doe",
    "taxId": "12345678900",
    "email": "john.doe@example.com",
    "phone": "11999990000"
  },
  "externalRef": "order_test_456789",
  "notificationUrl": "https://example-webhook.test/notifications",
  "metadata": null,
  "utms": {
    "utmSource": "google",
    "utmMedium": "cpc",
    "utmCampaign": "black-friday-2026",
    "utmContent": "banner-topo",
    "utmTerm": "tenis-de-corrida",
    "src": "blog-artigo-1",
    "sck": "lista-quente"
  },
  "paidAt": null,
  "refundedAt": null,
  "createdAt": "2026-01-19T17:34:23.491Z",
  "updatedAt": "2026-01-19T17:34:23.491Z",
  "orderId": null,
  "data": {
    "method": "CREDIT_CARD",
    "message": "Pagamento aprovado com sucesso",
    "cardHolder": "JOHN DOE",
    "cardNumber": "411111******1111",
    "cardExpMonth": "12",
    "cardExpYear": "2028"
  },
  "splits": [
    {
      "amount": 1000,
      "currency": "BRL",
      "percent": 100,
      "storeId": "store_test_001",
      "splitId": null
    }
  ],
  "items": [
    {
      "quantity": 1,
      "name": "Produto Teste",
      "price": 1000,
      "type": "PHYSICAL"
    }
  ],
  "delivery": {
    "fee": 1500,
    "address": {
      "country": "BR",
      "state": "SP",
      "city": "São Paulo",
      "district": "Centro",
      "street": "Rua Exemplo",
      "number": "123",
      "complement": "Apto 45",
      "zipCode": "01001-000",
    }
  },
}

Boleto · JSON

{
  "id": "pay_test_boleto_01HZABC123456789",
  "amount": 1000,
  "method": "BOLETO",
  "currency": "BRL",
  "status": "PENDING",
  "description": "Compra de produto de teste",
  "installments": 1,
  "payer": {
    "name": "John Doe",
    "taxId": "12345678900",
    "email": "john.doe@example.com",
    "phone": "11999990000"
  },
  "externalRef": "order_test_789456",
  "notificationUrl": "https://example-webhook.test/notifications",
  "metadata": null,
  "utms": {
    "utmSource": "google",
    "utmMedium": "cpc",
    "utmCampaign": "black-friday-2026",
    "utmContent": "banner-topo",
    "utmTerm": "tenis-de-corrida",
    "src": "blog-artigo-1",
    "sck": "lista-quente"
  },
  "paidAt": null,
  "refundedAt": null,
  "createdAt": "2026-01-19T17:38:39.973Z",
  "updatedAt": "2026-01-19T17:38:39.973Z",
  "orderId": null,
  "data": {
    "method": "BOLETO",
    "barcode": "34191.79001 01043.510047 91020.150008 4 12340000001000"
  },
  "splits": [
    {
      "amount": 1000,
      "currency": "BRL",
      "percent": 100,
      "storeId": "store_test_001",
      "splitId": null
    }
  ],
  "items": [
    {
      "quantity": 1,
      "name": "Produto Teste",
      "price": 1000,
      "type": "PHYSICAL"
    }
  ],
  "delivery": {
    "fee": 1500,
    "address": {
      "country": "BR",
      "state": "SP",
      "city": "São Paulo",
      "district": "Centro",
      "street": "Rua Exemplo",
      "number": "123",
      "complement": "Apto 45",
      "zipCode": "01001-000",
    }
  },
}

¿Algo mal en esta página? Habla con nosotros