WebhooksPayment

Payment webhook

This page describes the webhook payload sent by the platform whenever a payment status is updated.

Description

The payment webhook is automatically sent whenever the payment status changes, allowing the integrator system to stay synchronized in real time.

Notifications are sent via HTTP requests using the POST method and JSON format.

Timezone Standard

All date and time fields sent in webhooks use the standard ISO 8601 in the timezone UTC (UTC+00:00), ensuring consistency regardless of the integrator's timezone. To avoid discrepancies caused by local time or daylight saving time, it is recommended to keep values in UTC for storage and processing, converting to the local timezone only at the presentation layer.

Optional Webhook Validation

To increase security, webhooks registered directly in the dashboard may include a signature sent in the header X-Signature: <base64-signature>, allowing validation of the authenticity of the received notification. This signature is generated by the platform using HMAC with SHA-256 over the webhook body, in JSON format, using a shared secret WEBHOOK_SECRET and encoded in Base64. The integrator can reproduce the same calculation in their system using the same secret and the received payload. If the generated signature matches the one sent in the header, the webhook is considered legitimate and intact. If they differ, the request may have been altered or not sent by the platform.

This validation is available only for webhooks registered in the dashboard. Webhooks sent to a URL provided dynamically through notificationUrl do not include the X-Signature.

Signature validation is optional, but strongly recommended whenever the webhook is configured through the dashboard to ensure greater communication security.

Notification Endpoint

The notification URL must be provided when creating the payment using the notificationUrl field.

The endpoint must be publicly accessible and respond with HTTP 200 to confirm receipt of the webhook.

Additionally, payment notifications may also occur through in-bound webhooks, configured directly in the gateway dashboard. In this model, the endpoint is pre-registered and triggered automatically on every payment status change.

Payment Status

Possible values for the status field are:

PENDING – Payment created and awaiting confirmation.
PROCESSING – Payment under processing or analysis.
PAID – Payment successfully completed.
REFUSED – Payment declined by issuer or antifraud system.
REFUNDED – Payment fully or partially refunded.
MED – Dispute under preliminary review, awaiting evidence.
CHARGEDBACK – Dispute confirmed with payment reversal.

Payload Format

Below are webhook payload examples according to the payment method.

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",
    }
  },
}

Credit Card · 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",
    }
  },
}

Something wrong on this page? Talk to us