Skip to main content
Use idempotency on every write path that can be retried by a user, queue, worker, or network client. Use external_ref as the stable identifier for a logical create operation.
  • Reuse the same value when retrying the same payment or transfer create.
  • Never reuse the same value for a different monetary intent.
  • Persist both your external_ref and the Pagou resource id.

​
Example request

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

​
Example success response

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

​
Common error

Status 409 
{
  "type": "https://api.pagou.ai/problems/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "A transaction with external_ref order_1001 already exists."
}
Fix: if the retry refers to the same business operation, reconcile the existing resource instead of sending a new create with different intent.

​
Where it matters most

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

​
Retry pattern

  1. Retry safely only when you can prove it is the same logical operation.
  2. If a write response is lost, reconcile with GET before creating another resource.
  3. Keep requestId, resource ID, and external_ref in the same audit record.