Pular para o conteúdo principal
Webhooks de transferência usam um envelope de payout. O tipo concreto do evento fica sempre no topo, em type, e o recurso da transferência fica em data.object.

​
Envelope público de transferência

{
  "id": "evt_0195w5n4dc2q2c1sq7k8m5b1x0",
  "type": "payout.created",
  "created": 1773637200,
  "api_version": "v2",
  "data": {
    "object": {
      "id": "po_M8K3R2V9Y1",
      "status": "pending",
      "type": "pix",
      "amount": 10000,
      "fee": 200,
      "net_amount": 9800,
      "description": "Supplier settlement",
      "pix_key_type": "cpf",
      "recipient": {
        "legal_name": "J*** S****",
        "document": "***.***.***-00"
      },
      "transferred_at": null,
      "created_at": "2026-03-16T14:00:00.000Z"
    }
  }
}

​
Campos principais

  • id de topo: deduplicação da entrega
  • type: nome do evento de payout
  • data.object.id: ID da transferência na Pagou
  • data.object.status: status público atual
  • data.object.amount: valor bruto do payout
  • data.object.fee: taxa da plataforma
  • data.object.net_amount: valor líquido enviado ao recebedor
  • data.object.transferred_at: horário de liquidação quando existir

​
Semântica dos valores

A Pagou separa explicitamente os valores:
  • amount: valor bruto solicitado para o payout
  • fee: taxa cobrada pela plataforma
  • net_amount: valor líquido liquidado para o recebedor

​
Mascaramento de PII

Os payloads de transferência mascaram dados do recebedor por padrão.
  • recipient.legal_name vem parcialmente mascarado
  • recipient.document vem parcialmente mascarado
Não espere PII completa no corpo do webhook.

​
Eventos emitidos hoje

  • payout.created
  • payout.in_analysis
  • payout.processing
  • payout.transferred
  • payout.failed
  • payout.rejected
  • payout.canceled

​
Progressão de status e supressão de duplicatas

A Pagou emite eventos de transferência em torno de estados efetivos do payout.
  • payout.processing
  • payout.transferred
  • payout.failed
  • payout.rejected
  • payout.canceled
Use type e data.object.status como contrato estável.

​
Exemplos de payload

​
payout.created

Use para criar o registro de payout no seu sistema. 
{
  "id": "evt_0195w5n4dc2q2c1sq7k8m5b1x0",
  "type": "payout.created",
  "created": 1773637200,
  "api_version": "v2",
  "data": {
    "object": {
      "id": "po_M8K3R2V9Y1",
      "status": "pending",
      "type": "pix",
      "amount": 10000,
      "fee": 200,
      "net_amount": 9800,
      "description": "Supplier settlement",
      "pix_key_type": "cpf",
      "recipient": {
        "legal_name": "J*** S****",
        "document": "***.***.***-00"
      },
      "transferred_at": null,
      "created_at": "2026-03-16T14:00:00.000Z"
    }
  }
}

​
payout.in_analysis

Use quando o payout entra em análise antes do processamento final. 
{
  "id": "evt_0195w5n4dc2q2c1sq7k8m5b1x1",
  "type": "payout.in_analysis",
  "created": 1773637260,
  "api_version": "v2",
  "data": {
    "object": {
      "id": "po_M8K3R2V9Y1",
      "status": "in_analysis",
      "type": "pix",
      "amount": 10000,
      "fee": 200,
      "net_amount": 9800,
      "description": "Supplier settlement",
      "pix_key_type": "cpf",
      "recipient": {
        "legal_name": "J*** S****",
        "document": "***.***.***-00"
      },
      "transferred_at": null,
      "created_at": "2026-03-16T14:00:00.000Z"
    }
  }
}

​
payout.processing

Use quando a transferência já entrou em execução. 
{
  "id": "evt_0195w5n4dc2q2c1sq7k8m5b1x2",
  "type": "payout.processing",
  "created": 1773637320,
  "api_version": "v2",
  "data": {
    "object": {
      "id": "po_M8K3R2V9Y1",
      "status": "processing",
      "type": "pix",
      "amount": 10000,
      "fee": 200,
      "net_amount": 9800,
      "description": "Supplier settlement",
      "pix_key_type": "cpf",
      "recipient": {
        "legal_name": "J*** S****",
        "document": "***.***.***-00"
      },
      "transferred_at": null,
      "created_at": "2026-03-16T14:00:00.000Z"
    }
  }
}

​
payout.transferred

Use para marcar o payout como liquidado. 
{
  "id": "evt_0195w5n4dc2q2c1sq7k8m5b1x3",
  "type": "payout.transferred",
  "created": 1773637500,
  "api_version": "v2",
  "data": {
    "object": {
      "id": "po_M8K3R2V9Y1",
      "status": "paid",
      "type": "pix",
      "amount": 10000,
      "fee": 200,
      "net_amount": 9800,
      "description": "Supplier settlement",
      "pix_key_type": "cpf",
      "recipient": {
        "legal_name": "J*** S****",
        "document": "***.***.***-00"
      },
      "transferred_at": "2026-03-16T14:05:00.000Z",
      "created_at": "2026-03-16T14:00:00.000Z"
    }
  }
}

​
payout.failed

Use para interromper o fluxo e avaliar retry ou ação manual. 
{
  "id": "evt_0195w5n4dc2q2c1sq7k8m5b1x4",
  "type": "payout.failed",
  "created": 1773637560,
  "api_version": "v2",
  "data": {
    "object": {
      "id": "po_M8K3R2V9Y1",
      "status": "error",
      "type": "pix",
      "amount": 10000,
      "fee": 200,
      "net_amount": 9800,
      "description": "Supplier settlement",
      "pix_key_type": "cpf",
      "recipient": {
        "legal_name": "J*** S****",
        "document": "***.***.***-00"
      },
      "transferred_at": null,
      "created_at": "2026-03-16T14:00:00.000Z"
    }
  }
}

​
payout.rejected

Use quando a transferência foi rejeitada e não deve continuar automaticamente. 
{
  "id": "evt_0195w5n4dc2q2c1sq7k8m5b1x5",
  "type": "payout.rejected",
  "created": 1773637620,
  "api_version": "v2",
  "data": {
    "object": {
      "id": "po_M8K3R2V9Y1",
      "status": "rejected",
      "type": "pix",
      "amount": 10000,
      "fee": 200,
      "net_amount": 9800,
      "description": "Supplier settlement",
      "pix_key_type": "cpf",
      "recipient": {
        "legal_name": "J*** S****",
        "document": "***.***.***-00"
      },
      "transferred_at": null,
      "created_at": "2026-03-16T14:00:00.000Z"
    }
  }
}

​
payout.canceled

Use quando o payout foi cancelado e deve ser encerrado sem liquidação. 
{
  "id": "evt_0195w5n4dc2q2c1sq7k8m5b1x6",
  "type": "payout.canceled",
  "created": 1773637680,
  "api_version": "v2",
  "data": {
    "object": {
      "id": "po_M8K3R2V9Y1",
      "status": "cancelled",
      "type": "pix",
      "amount": 10000,
      "fee": 200,
      "net_amount": 9800,
      "description": "Supplier settlement",
      "pix_key_type": "cpf",
      "recipient": {
        "legal_name": "J*** S****",
        "document": "***.***.***-00"
      },
      "transferred_at": null,
      "created_at": "2026-03-16T14:00:00.000Z"
    }
  }
}

​
Padrão mínimo de roteamento

async function handleTransferWebhook(payload: any) {
	const eventType = payload?.type;
	const transfer = payload?.data?.object;

	switch (eventType) {
		case "payout.transferred":
			await markPayoutSettled(transfer.id, transfer.transferred_at);
			return;
		case "payout.failed":
		case "payout.rejected":
		case "payout.canceled":
			await flagPayoutForReview(transfer.id, eventType);
			return;
		default:
			await saveForAudit(payload);
	}
}

​
Próximas páginas