> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bukiopay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Eventos

> Catálogo dos eventos de pagamento, reembolso, mediação e transferência, com o payload de cada um.

## Pagamentos

| Evento | Quando é enviado |
| - | - |
| `payment.created` | Cobrança criada, aguardando pagamento |
| `payment.paid` | Pagamento confirmado |
| `payment.failed` | A cobrança não pôde ser gerada ou o pagamento não foi concluído |
| `payment.pix.expired` | O Pix expirou sem pagamento |
| `payment.refunded` | Valor devolvido ao pagador |

### payment.paid

O evento mais importante da integração: é ele que autoriza a liberação do produto.

```json theme={null}
{
  "event": "payment.paid",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "PIX_IN",
    "status": "paid",
    "amount": 49.9,
    "currency": "BRL",
    "hasProducts": false,
    "customer": {
      "name": "João Silva"
    },
    "externalReference": "A1B2C3D4",
    "referenceId": "e19dc9a3-7e3d-4c4a-8e72-9ca5c17540c2",
    "paidAt": "2026-08-15T14:35:00.000Z"
  },
  "requestId": "req_0123456789abcdef",
  "createdAt": "2026-08-15T14:35:01.000Z"
}
```

<ResponseField name="data.id" type="string">
  Em cobrança avulsa, o id da cobrança. Em venda de produtos, o id do **pedido**. Use `hasProducts` para saber qual é o caso.
</ResponseField>

<ResponseField name="data.hasProducts" type="boolean">
  `false` para cobrança Pix avulsa, `true` quando o pagamento é de um pedido com produtos.
</ResponseField>

<ResponseField name="data.customer.name" type="string">
  Nome de quem pagou, quando informado pelo banco.
</ResponseField>

<ResponseField name="data.externalReference" type="string">
  Referência curta da cobrança, útil para conciliação.
</ResponseField>

<ResponseField name="data.paidAt" type="string">
  Momento da confirmação, em ISO 8601.
</ResponseField>

### payment.created

```json theme={null}
{
  "event": "payment.created",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "PIX_IN",
    "status": "pending",
    "amount": 49.9,
    "currency": "BRL",
    "referenceId": "e19dc9a3-7e3d-4c4a-8e72-9ca5c17540c2",
    "externalReference": "A1B2C3D4",
    "createdAt": "2026-08-15T14:30:00.000Z"
  },
  "requestId": "req_0123456789abcdef",
  "createdAt": "2026-08-15T14:30:01.000Z"
}
```

### payment.failed e payment.pix.expired

O `data` traz `id`, `type`, `status` e `occurredAt`. O valor só é incluído quando conhecido.

## Reembolsos

| Evento | Quando é enviado |
| - | - |
| `refund.requested` | Reembolso solicitado |
| `refund.completed` | Reembolso concluído |
| `refund.failed` | O reembolso não pôde ser concluído |

```json theme={null}
{
  "event": "refund.completed",
  "data": {
    "id": "8159fbe2-fd7d-4b28-8028-1257210b32d0",
    "type": "ORDER",
    "status": "refunded",
    "amount": 149.9,
    "currency": "BRL",
    "orderId": "8159fbe2-fd7d-4b28-8028-1257210b32d0",
    "paymentReference": "e19dc9a3-7e3d-4c4a-8e72-9ca5c17540c2",
    "occurredAt": "2026-08-26T13:00:00.000Z",
    "completedAt": "2026-08-26T13:00:00.000Z"
  },
  "requestId": "req_0123456789abcdef",
  "createdAt": "2026-08-26T13:00:01.000Z"
}
```

A data varia com o evento: `requestedAt`, `completedAt` ou `failedAt`.

<Warning>
  Um reembolso concluído dispara **dois** eventos: `refund.completed` e `payment.refunded`. Se você assinar os dois, trate o reembolso uma única vez.
</Warning>

## Mediações

| Evento | Quando é enviado |
| - | - |
| `med.created` | Mediação aberta contra uma cobrança; o valor fica retido |
| `med.updated` | A situação da mediação mudou |
| `med.evidence_sent` | Defesa enviada |

```json theme={null}
{
  "event": "med.created",
  "data": {
    "id": "6f1b2c33-8a4d-4f21-9e77-1b2c3d4e5f60",
    "status": "pending",
    "amount": 149.9,
    "currency": "BRL",
    "transactionId": "e19dc9a3-7e3d-4c4a-8e72-9ca5c17540c2",
    "orderId": "8159fbe2-fd7d-4b28-8028-1257210b32d0",
    "createdAt": "2026-08-26T13:00:00.000Z",
    "updatedAt": "2026-08-26T13:00:00.000Z"
  },
  "requestId": "req_0123456789abcdef",
  "createdAt": "2026-08-26T13:00:01.000Z"
}
```

Em `med.updated`, o `data` também traz `previousStatus`. Em `med.evidence_sent`, traz `evidenceCount` e `evidenceSentAt`.

## Transferências

Referem-se aos seus saques Pix.

| Evento | Quando é enviado |
| - | - |
| `transfer.created` | Saque enviado para processamento |
| `transfer.completed` | Saque concluído |
| `transfer.failed` | Saque não concluído |

Os três eventos enviam os mesmos campos; dados ainda desconhecidos vêm como `null`.

```json theme={null}
{
  "event": "transfer.completed",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "PIX_OUT",
    "status": "approved",
    "amount": 100,
    "feeAmount": 1,
    "totalAmount": 101,
    "currency": "BRL",
    "externalReference": "SAQ-API-6BA7B810",
    "pixKeyType": "email",
    "pixKey": "usuario@exemplo.com",
    "holderName": "Cliente Exemplo",
    "bankName": "Banco Exemplo",
    "receiverName": "Cliente Exemplo",
    "receiverDocument": "12345678900",
    "failureCode": null,
    "failureReason": null,
    "createdAt": "2026-08-06T12:05:00.000Z",
    "processedAt": "2026-08-06T12:05:05.000Z"
  },
  "requestId": "req_0123456789abcdef",
  "createdAt": "2026-08-06T12:05:06.000Z"
}
```

<ResponseField name="data.status" type="string">
  `processing` em `transfer.created`, `approved` em `transfer.completed` e `rejected` em `transfer.failed`.
</ResponseField>

<ResponseField name="data.failureCode" type="string | null">
  Em `transfer.failed`, vem `TRANSFER_REJECTED`. Nos demais eventos, `null`.
</ResponseField>

<ResponseField name="data.receiverName" type="string | null">
  Dados do recebedor confirmados no processamento, quando disponíveis.
</ResponseField>

<Note>
  Os payloads não incluem credenciais, identificadores operacionais nem configuração interna.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.