Eventos

Liste os eventos enviados ao seu webhook, veja a situação de cada entrega e peça reenvio.

O objeto evento

Um evento é uma notificação de webhook. Ele tem os mesmos id, type, createdAt e data da entrega, mais a situação da entrega em delivery.

Campos

idstring
Identificador do evento. Use para descartar entregas repetidas.
typeenum
charge.paidpayout.paidpayout.canceledpayout.refunded
createdAtstring · ISO 8601
dataobject
O recurso no estado do evento: uma cobrança ou um saque.
objectstring
sempre "event"
deliveryobject
delivery.statusenum
pendingdeliveredfailedskipped
delivery.attemptsinteger
delivery.lastStatusCodeinteger · pode ser nulo
delivery.lastErrorstring · pode ser nulo
delivery.lastAttemptAtstring · ISO 8601 · pode ser nulo
delivery.nextAttemptAtstring · ISO 8601 · pode ser nulo
delivery.deliveredAtstring · ISO 8601 · pode ser nulo

ExemploJSON

{
  "id": "charge.paid:6f0c1a52-1d7e-4b8a-9f43-2c5e8d9b7a10",
  "type": "charge.paid",
  "createdAt": "2026-11-02T18:13:41.000Z",
  "data": {
    "id": "6f0c1a52-1d7e-4b8a-9f43-2c5e8d9b7a10",
    "object": "charge",
    "status": "paid",
    "amountCents": 4990,
    "feeCents": 99,
    "netCents": 4891,
    "currency": "BRL",
    "description": "Pedido 1042",
    "payerName": "Cliente Exemplo",
    "payerDocument": "52998224725",
    "pixCopyPaste": "00020101021226870014br.gov.bcb.pix2565pix.exemplo.com.br/qr/v2/6f0c1a521d7e4b8a9f432c5e8d9b7a1052040000530398654044.905802BR6304B7C1",
    "pixQrCode": "iVBORw0KGgoAAAANSUhEUgAA…",
    "endToEndId": "E18236120202611021813s0a1b2c3d4e",
    "externalId": "pedido-1042",
    "metadata": {
      "canal": "checkout"
    },
    "failureReason": null,
    "expiresAt": "2026-11-02T19:12:00.000Z",
    "paidAt": "2026-11-02T18:13:41.000Z",
    "createdAt": "2026-11-02T18:12:00.000Z",
    "updatedAt": "2026-11-02T18:13:41.000Z"
  },
  "object": "event",
  "delivery": {
    "status": "delivered",
    "attempts": 1,
    "lastStatusCode": 200,
    "lastError": null,
    "lastAttemptAt": "2026-11-02T18:13:43.000Z",
    "nextAttemptAt": null,
    "deliveredAt": "2026-11-02T18:13:43.000Z"
  }
}

Listar eventos

GET/v1/events

Lista os eventos enviados ao seu webhook, com a situação de cada entrega.

Escopo: charges:read ou payouts:read
Idempotency-Key: Não se aplica
Sucesso: 200

A chave vê os eventos de cobrança se tiver charges:read e os de saque se tiver payouts:read.

Parâmetros de consulta

limitintegeropcional
Quantidade de itens por página, de 1 a 100. Padrão 20.
mínimo 1máximo 100padrão 20
cursorstringopcional
Valor de nextCursor da página anterior. Omita para começar do item mais recente.
1 a 200 caracteres
typeenumopcional
Filtra pelo tipo do evento.
charge.paidpayout.paidpayout.canceledpayout.refunded
deliveryStatusenumopcional
Filtra pela situação da entrega ao seu endpoint.
pendingdeliveredfailedskipped

Resposta

Devolve uma lista paginada de objetos evento.

Erros desta rota

403forbiddenA chave não tem o escopo exigido pela rota.
422invalid_queryUm parâmetro de consulta é inválido. O parâmetro vem em error.field.
422invalid_cursorO cursor não foi gerado pela API.

Exemplo de retorno, pelo contrato da rota. Não cria cobrança nem saque.

const response = await fetch("https://api.maxxipay.com/v1/events?type=charge.paid&deliveryStatus=delivered", {
  headers: {
    Authorization: `Bearer ${process.env.MAXXIPAY_API_KEY}`,
  },
});

const page = await response.json();

RespostaJSON200 OK

{
  "object": "list",
  "data": [
    {
      "id": "charge.paid:6f0c1a52-1d7e-4b8a-9f43-2c5e8d9b7a10",
      "type": "charge.paid",
      "createdAt": "2026-11-02T18:13:41.000Z",
      "data": {
        "id": "6f0c1a52-1d7e-4b8a-9f43-2c5e8d9b7a10",
        "object": "charge",
        "status": "paid",
        "amountCents": 4990,
        "feeCents": 99,
        "netCents": 4891,
        "currency": "BRL",
        "description": "Pedido 1042",
        "payerName": "Cliente Exemplo",
        "payerDocument": "52998224725",
        "pixCopyPaste": "00020101021226870014br.gov.bcb.pix2565pix.exemplo.com.br/qr/v2/6f0c1a521d7e4b8a9f432c5e8d9b7a1052040000530398654044.905802BR6304B7C1",
        "pixQrCode": "iVBORw0KGgoAAAANSUhEUgAA…",
        "endToEndId": "E18236120202611021813s0a1b2c3d4e",
        "externalId": "pedido-1042",
        "metadata": {
          "canal": "checkout"
        },
        "failureReason": null,
        "expiresAt": "2026-11-02T19:12:00.000Z",
        "paidAt": "2026-11-02T18:13:41.000Z",
        "createdAt": "2026-11-02T18:12:00.000Z",
        "updatedAt": "2026-11-02T18:13:41.000Z"
      },
      "object": "event",
      "delivery": {
        "status": "delivered",
        "attempts": 1,
        "lastStatusCode": 200,
        "lastError": null,
        "lastAttemptAt": "2026-11-02T18:13:43.000Z",
        "nextAttemptAt": null,
        "deliveredAt": "2026-11-02T18:13:43.000Z"
      }
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

Consultar um evento

GET/v1/events/{id}

Busca um evento pelo identificador, o mesmo enviado no campo id do webhook.

Escopo: charges:read ou payouts:read
Idempotency-Key: Não se aplica
Sucesso: 200

Parâmetros de caminho

idstringobrigatório
Identificador do evento.

Resposta

Devolve o objeto evento.

Erros desta rota

404not_foundO recurso não existe ou pertence a outra empresa.

Exemplo de retorno, pelo contrato da rota. Não cria cobrança nem saque.

const response = await fetch("https://api.maxxipay.com/v1/events/charge.paid:6f0c1a52-1d7e-4b8a-9f43-2c5e8d9b7a10", {
  headers: {
    Authorization: `Bearer ${process.env.MAXXIPAY_API_KEY}`,
  },
});

const event = await response.json();

RespostaJSON200 OK

{
  "id": "charge.paid:6f0c1a52-1d7e-4b8a-9f43-2c5e8d9b7a10",
  "type": "charge.paid",
  "createdAt": "2026-11-02T18:13:41.000Z",
  "data": {
    "id": "6f0c1a52-1d7e-4b8a-9f43-2c5e8d9b7a10",
    "object": "charge",
    "status": "paid",
    "amountCents": 4990,
    "feeCents": 99,
    "netCents": 4891,
    "currency": "BRL",
    "description": "Pedido 1042",
    "payerName": "Cliente Exemplo",
    "payerDocument": "52998224725",
    "pixCopyPaste": "00020101021226870014br.gov.bcb.pix2565pix.exemplo.com.br/qr/v2/6f0c1a521d7e4b8a9f432c5e8d9b7a1052040000530398654044.905802BR6304B7C1",
    "pixQrCode": "iVBORw0KGgoAAAANSUhEUgAA…",
    "endToEndId": "E18236120202611021813s0a1b2c3d4e",
    "externalId": "pedido-1042",
    "metadata": {
      "canal": "checkout"
    },
    "failureReason": null,
    "expiresAt": "2026-11-02T19:12:00.000Z",
    "paidAt": "2026-11-02T18:13:41.000Z",
    "createdAt": "2026-11-02T18:12:00.000Z",
    "updatedAt": "2026-11-02T18:13:41.000Z"
  },
  "object": "event",
  "delivery": {
    "status": "delivered",
    "attempts": 1,
    "lastStatusCode": 200,
    "lastError": null,
    "lastAttemptAt": "2026-11-02T18:13:43.000Z",
    "nextAttemptAt": null,
    "deliveredAt": "2026-11-02T18:13:43.000Z"
  }
}

Reenviar um evento

POST/v1/events/{id}/resend

Coloca o evento de volta na fila de entrega. Serve para eventos com falha, ignorados por falta de endpoint ou já entregues que você quer receber de novo.

Escopo: charges:read ou payouts:read
Idempotency-Key: Não se aplica
Sucesso: 202

A entrega acontece em poucos segundos para a URL configurada agora no painel, com o mesmo id e o mesmo corpo, assinado com o segredo atual.

Parâmetros de caminho

idstringobrigatório
Identificador do evento.

Resposta

Devolve o objeto evento com a entrega em pending.

Erros desta rota

404not_foundO recurso não existe ou pertence a outra empresa.
409event_delivery_pendingO evento já está na fila de entrega.

Exemplo de retorno, pelo contrato da rota. Não cria cobrança nem saque.

const response = await fetch("https://api.maxxipay.com/v1/events/charge.paid:6f0c1a52-1d7e-4b8a-9f43-2c5e8d9b7a10/resend", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MAXXIPAY_API_KEY}`,
  },
});

const event = await response.json();

RespostaJSON202 Accepted

{
  "id": "charge.paid:6f0c1a52-1d7e-4b8a-9f43-2c5e8d9b7a10",
  "type": "charge.paid",
  "createdAt": "2026-11-02T18:13:41.000Z",
  "data": {
    "id": "6f0c1a52-1d7e-4b8a-9f43-2c5e8d9b7a10",
    "object": "charge",
    "status": "paid",
    "amountCents": 4990,
    "feeCents": 99,
    "netCents": 4891,
    "currency": "BRL",
    "description": "Pedido 1042",
    "payerName": "Cliente Exemplo",
    "payerDocument": "52998224725",
    "pixCopyPaste": "00020101021226870014br.gov.bcb.pix2565pix.exemplo.com.br/qr/v2/6f0c1a521d7e4b8a9f432c5e8d9b7a1052040000530398654044.905802BR6304B7C1",
    "pixQrCode": "iVBORw0KGgoAAAANSUhEUgAA…",
    "endToEndId": "E18236120202611021813s0a1b2c3d4e",
    "externalId": "pedido-1042",
    "metadata": {
      "canal": "checkout"
    },
    "failureReason": null,
    "expiresAt": "2026-11-02T19:12:00.000Z",
    "paidAt": "2026-11-02T18:13:41.000Z",
    "createdAt": "2026-11-02T18:12:00.000Z",
    "updatedAt": "2026-11-02T18:13:41.000Z"
  },
  "object": "event",
  "delivery": {
    "status": "pending",
    "attempts": 1,
    "lastStatusCode": 200,
    "lastError": null,
    "lastAttemptAt": "2026-11-02T18:13:43.000Z",
    "nextAttemptAt": "2026-11-02T18:40:00.000Z",
    "deliveredAt": "2026-11-02T18:13:43.000Z"
  }
}