Reconciliação de transferências

​

APIs de leitura

• GET /v2/transfers
• GET /v2/transfers/{id}

​

Exemplo de requisição

curl --request GET \
  --url https://api.pagou.ai/v2/transfers/018f1f2e-7b45-7c9a-8d3e-1a2b3c4d5e72 \
  --header "Authorization: Bearer SEU_TOKEN"

​

Exemplo de resposta

{
  "success": true,
  "requestId": "0190a2b4-18a7-7de0-9a43-69b7cf261201",
  "data": {
    "id": "018f1f2e-7b45-7c9a-8d3e-1a2b3c4d5e72",
    "status": "paid",
    "amount": "1200",
    "external_ref": "payout_1001",
    "transferred_at": "2026-03-16T14:05:00.000Z"
  }
}

​

Erro comum

{
  "type": "https://api.pagou.ai/problems/not-found",
  "title": "Resource Not Found",
  "status": 404,
  "detail": "The requested transfer does not exist."
}

​

Fluxo de reconciliação

1. Carregue o ID da transferência na Pagou a partir do seu registro de payout ou armazenamento de webhook.
2. Busque o estado mais recente da transferência.
3. Aplique localmente apenas transições seguras para frente.
4. Escale estados repetidos error, rejected ou unknown para operação.
5. Trate rejected como cancelamento no parceiro bancário: o valor não volta automaticamente para o seu saldo, então escale o caso e confirme que o valor voltou ao seu saldo antes de reenviar.