Skip to main content

​
Visão Geral

O evento PIX_TRANSACTION é disparado quando o status de uma transação PIX recebida diretamente (via chave ou manual) é atualizado na plataforma. O webhook é enviado quando:
  • Uma transação PIX recebida muda de status (ex: PENDING → SETTLED, PENDING → FAILED)
Este evento cobre apenas transações PIX recebidas via chave PIX ou transferência manual. Para cobranças PIX (QR Code), utilize o evento PAYMENT.

​
Headers do Webhook

X-Webhook-Event: PIX_TRANSACTION
X-Webhook-Timestamp: 2024-01-15T10:30:00Z
X-Webhook-Signature: abc123def456...
Content-Type: application/json

​
Estrutura do Payload

{
  "event": "PIX_TRANSACTION",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "uuid": "990e8400-e29b-41d4-a716-446655440002",
    "initiation": {
      "sender": {
        "name": "João Silva",
        "document": "12345678901",
        "account_number": "00123456",
        "account_agency": "0001",
        "bank": {
          "code": "341",
          "name": "ITAÚ UNIBANCO S.A.",
          "ispb": "60701190"
        },
        "account_type": "CHECKING"
      },
      "receiver": {
        "name": "Empresa Demo LTDA",
        "document": "12345678000190",
        "account_number": "9876543",
        "account_agency": "0001",
        "bank": {
          "code": "",
          "name": "PLOWF IP LTDA.",
          "ispb": "00000000"
        },
        "account_type": "CHECKING"
      },
      "txid": null,
      "value": 150.0,
      "type": "KEY",
      "pix_key": "[email protected]",
      "description": "Pagamento de serviço",
      "status": "COMPLETED",
      "expires_at": null,
      "created_at": "2024-01-15T10:28:00.000000Z",
      "updated_at": "2024-01-15T10:30:00.000000Z"
    },
    "value": 150.0,
    "movement_type": "IN",
    "type": "EXTERNAL_TRANSFER",
    "status": "SETTLED",
    "end_to_end": "E6070119020240115103000000000001",
    "settled_at": "2024-01-15T10:30:00.000000Z",
    "created_at": "2024-01-15T10:28:00.000000Z",
    "updated_at": "2024-01-15T10:30:00.000000Z"
  }
}

​
Campos do Payload

​
event
string
Tipo do evento. Sempre "PIX_TRANSACTION" para este webhook.
​
timestamp
datetime
Timestamp ISO 8601 do momento em que o webhook foi enviado.

​
Status Possíveis

Os status possíveis para uma transação PIX são:
  • PENDING - Aguardando liquidação
  • SETTLED - Transação liquidada com sucesso
  • FAILED - Transação falhou
  • REFUNDED - Transação estornada parcialmente ou totalmente
Use o campo uuid para identificar unicamente a transação e implementar idempotência no seu endpoint.