Skip to main content

​
Eventos de Transferência Pix Out

Quando a API envia um webhook de transferência Pix Out, trate o evento de forma idempotente e assíncrona.

​
Exemplo (payout.created)

Disparado quando a transferência é criada e está aguardando processamento. 
{
  "id": "evt_019505a2-7c3e-7000-8a1b-3f9d2e1c4b5a",
  "type": "payout.created",
  "created": 1738958400,
  "api_version": "v2",
  "data": {
    "object": {
      "id": "txf_a1b2c3d4-5678-4e9f-b012-3456789abcde",
      "status": "pending",
      "type": "pix",
      "amount": 10100,
      "fee": 100,
      "net_amount": 10000,
      "description": "Pagamento fornecedor",
      "pix_key_type": "CPF",
      "recipient": {
        "legal_name": "J*** S****",
        "document": "***.***.***-90"
      },
      "transferred_at": null,
      "created_at": "2026-02-07T18:00:00.000Z"
    }
  }
}

​
Exemplo (payout.in_analysis)

Disparado quando a transferência entra em análise pelo provedor. 
{
  "id": "evt_019505b1-2d4f-7000-9c3e-5a8b7d6f1e2c",
  "type": "payout.in_analysis",
  "created": 1738958460,
  "api_version": "v2",
  "data": {
    "object": {
      "id": "txf_a1b2c3d4-5678-4e9f-b012-3456789abcde",
      "status": "in_analysis",
      "type": "pix",
      "amount": 10100,
      "fee": 100,
      "net_amount": 10000,
      "description": "Pagamento fornecedor",
      "pix_key_type": "CPF",
      "recipient": {
        "legal_name": "J*** S****",
        "document": "***.***.***-90"
      },
      "transferred_at": null,
      "created_at": "2026-02-07T18:00:00.000Z"
    }
  }
}

​
Exemplo (payout.processing)

Disparado quando a transferência começa a ser processada. 
{
  "id": "evt_019505c0-8e6a-7000-b4d2-7c9f1a3e5b8d",
  "type": "payout.processing",
  "created": 1738958520,
  "api_version": "v2",
  "data": {
    "object": {
      "id": "txf_a1b2c3d4-5678-4e9f-b012-3456789abcde",
      "status": "processing",
      "type": "pix",
      "amount": 10100,
      "fee": 100,
      "net_amount": 10000,
      "description": "Pagamento fornecedor",
      "pix_key_type": "CPF",
      "recipient": {
        "legal_name": "J*** S****",
        "document": "***.***.***-90"
      },
      "transferred_at": null,
      "created_at": "2026-02-07T18:00:00.000Z"
    }
  }
}

​
Exemplo (payout.transferred)

Disparado quando a transferência é concluída com sucesso. 
{
  "id": "evt_019505d3-4f7b-7000-c5e3-8d0a2b4c6e9f",
  "type": "payout.transferred",
  "created": 1738958580,
  "api_version": "v2",
  "data": {
    "object": {
      "id": "txf_a1b2c3d4-5678-4e9f-b012-3456789abcde",
      "status": "paid",
      "type": "pix",
      "amount": 10100,
      "fee": 100,
      "net_amount": 10000,
      "description": "Pagamento fornecedor",
      "pix_key_type": "CPF",
      "recipient": {
        "legal_name": "J*** S****",
        "document": "***.***.***-90"
      },
      "transferred_at": "2026-02-07T18:01:20.000Z",
      "created_at": "2026-02-07T18:00:00.000Z"
    }
  }
}

​
Exemplo (payout.failed)

Disparado quando a transferência falha no processamento. 
{
  "id": "evt_019505e4-6a8c-7000-d6f4-9e1b3c5d7f0a",
  "type": "payout.failed",
  "created": 1738958640,
  "api_version": "v2",
  "data": {
    "object": {
      "id": "txf_a1b2c3d4-5678-4e9f-b012-3456789abcde",
      "status": "error",
      "type": "pix",
      "amount": 10100,
      "fee": 100,
      "net_amount": 10000,
      "description": "Pagamento fornecedor",
      "pix_key_type": "CPF",
      "recipient": {
        "legal_name": "J*** S****",
        "document": "***.***.***-90"
      },
      "transferred_at": null,
      "created_at": "2026-02-07T18:00:00.000Z"
    }
  }
}

​
Exemplo (payout.rejected)

Disparado quando a transferência é rejeitada pelo provedor. 
{
  "id": "evt_019505f5-7b9d-7000-e7a5-af2c4d6e8a1b",
  "type": "payout.rejected",
  "created": 1738958700,
  "api_version": "v2",
  "data": {
    "object": {
      "id": "txf_a1b2c3d4-5678-4e9f-b012-3456789abcde",
      "status": "rejected",
      "type": "pix",
      "amount": 10100,
      "fee": 100,
      "net_amount": 10000,
      "description": "Pagamento fornecedor",
      "pix_key_type": "CPF",
      "recipient": {
        "legal_name": "J*** S****",
        "document": "***.***.***-90"
      },
      "transferred_at": null,
      "created_at": "2026-02-07T18:00:00.000Z"
    }
  }
}

​
Exemplo (payout.canceled)

Disparado quando a transferência é cancelada ou estornada. 
{
  "id": "evt_01950606-8cae-7000-f8b6-b03d5e7f9b2c",
  "type": "payout.canceled",
  "created": 1738958760,
  "api_version": "v2",
  "data": {
    "object": {
      "id": "txf_a1b2c3d4-5678-4e9f-b012-3456789abcde",
      "status": "cancelled",
      "type": "pix",
      "amount": 10100,
      "fee": 100,
      "net_amount": 10000,
      "description": "Pagamento fornecedor",
      "pix_key_type": "CPF",
      "recipient": {
        "legal_name": "J*** S****",
        "document": "***.***.***-90"
      },
      "transferred_at": null,
      "created_at": "2026-02-07T18:00:00.000Z"
    }
  }
}

​
Processamento recomendado

  1. Deduplicar por id do evento
  2. Atualizar o estado da transferência por data.object.id
  3. Responder 200 OK e processar de forma assíncrona
  4. Tratar status terminais (paid, error, rejected, cancelled) como finais