Skip to main content

​
Visão Geral

O evento TRANSFER é disparado quando o status de uma transferência PIX Out é atualizado na plataforma. O webhook é enviado quando:
  • Uma transferência muda de status (ex: PROCESSING → PAID, PROCESSING → FAILED)

​
Headers do Webhook

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

​
Estrutura do Payload

{
  "event": "TRANSFER",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "uuid": "770e8400-e29b-41d4-a716-446655440002",
    "value": 100.5,
    "fees": 2.5,
    "currency": "BRL",
    "status": "PAID",
    "type": "PIX",
    "external_ref": "transfer-456",
    "final_beneficiary": {
      "name": "Maria Santos",
      "document": "98765432100"
    },
    "transfer": {
      "uuid": "880e8400-e29b-41d4-a716-446655440003",
      "initiation": {
        "sender": {
          "name": "Empresa Exemplo Ltda",
          "document": "00000000000100",
          "account_number": "0000001",
          "account_agency": "0001",
          "bank": {
            "code": "",
            "name": "BANCO EXEMPLO IP LTDA.",
            "ispb": "00000000"
          },
          "account_type": "CHECKING"
        },
        "receiver": {
          "name": "Maria Santos",
          "document": "987.***.***-00",
          "account_number": "********************",
          "account_agency": "****",
          "bank": {
            "code": "077",
            "name": "BANCO INTER S.A.",
            "ispb": "00416968"
          },
          "account_type": "CHECKING"
        },
        "txid": null,
        "value": 100.5,
        "type": "KEY",
        "pix_key": "[email protected]",
        "status": "COMPLETED",
        "expires_at": null,
        "created_at": "2024-01-15T10:25:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
      },
      "value": 100.5,
      "movement_type": "OUT",
      "type": "EXTERNAL_TRANSFER",
      "status": "SETTLED",
      "end_to_end": "E123456782024011510300000123456",
      "settled_at": "2024-01-15T10:30:00Z",
      "created_at": "2024-01-15T10:25:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    "history": [
      {
        "status": "PENDING",
        "created_at": "2024-01-01T10:00:00Z"
      },
      {
        "status": "PROCESSING",
        "created_at": "2024-01-01T10:02:00Z"
      },
      {
        "status": "PAID",
        "created_at": "2024-01-01T10:05:00Z"
      }
    ],
    "created_at": "2024-01-15T10:25:00Z"
  }
}

​
Campos do Payload

​
event
string
Tipo do evento. Sempre "TRANSFER" para este webhook.
​
timestamp
datetime
Timestamp ISO 8601 do momento em que o webhook foi enviado.
​
data
object
Dados da transferência atualizada.

​
Status Possíveis

Os status possíveis para uma transferência são:
  • PENDING - Aguardando processamento
  • PROCESSING - Transferência em processamento
  • PAID - Transferência confirmada
  • FAILED - Transferência falhou
  • CANCELLED - Transferência cancelada
  • REFUNDED - Transferência estornada
  • PARTIALLY_REFUNDED - Transferência estornada parcialmente
  • EXPIRED - Transferência expirada
Use o campo uuid para identificar unicamente a transferência e implementar idempotência no seu endpoint.