Pular para o conteúdo principal
Use idempotência em todo caminho de escrita que possa ser repetido por usuário, fila, worker ou cliente de rede.

​
Regra recomendada

Use external_ref como identificador estável de uma operação lógica de criação.
  • Reutilize o mesmo valor ao repetir a mesma criação de pagamento ou transferência.
  • Nunca reutilize o mesmo valor para uma intenção financeira diferente.
  • Persista o seu external_ref e o id do recurso na Pagou.

​
Exemplo de requisição

{
  "external_ref": "order_1001",
  "amount": 1500,
  "currency": "BRL",
  "method": "pix"
}

​
Exemplo de resposta com sucesso

{
  "success": true,
  "requestId": "req_1001",
  "data": {
    "id": "tr_1001",
    "status": "pending"
  }
}

​
Erro comum

Status 409 
{
  "type": "https://api.pagou.ai/problems/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "A transaction with external_ref order_1001 already exists."
}
Como corrigir: se a repetição se refere à mesma operação de negócio, reconcilie o recurso existente em vez de enviar uma nova criação com outra intenção.

​
Onde isso mais importa

  • POST /v2/transactions
  • PUT /v2/transactions/{id}/refund
  • POST /v2/transfers
  • POST /v2/transfers/{id}/cancel

​
Padrão de retry

  1. Só repita com segurança quando você puder provar que é a mesma operação lógica.
  2. Se a resposta de uma escrita se perder, reconcilie com GET antes de criar outro recurso.
  3. Mantenha requestId, ID do recurso e external_ref no mesmo registro de auditoria.