Idempotency

​

Recommended rule

• 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": "0190a2b4-18a7-7de0-9a43-69b7cf261201",
  "data": {
    "id": "018f1f2e-7b42-7c9a-8d3e-1a2b3c4d5e6f",
    "status": "pending"
  }
}

​

Common error

{
  "type": "https://api.pagou.ai/problems/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "A transaction with external_ref order_1001 already exists."
}

​

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.