Skip to main content
This page is for engineers implementing create or refund flows that must survive retries safely. Use external_ref as the stable idempotency key for transaction creation and keep it unique per business operation in your own system. 
{
  "external_ref": "order_1001",
  "amount": 1500,
  "method": "pix"
}

​
Rules

  • Generate external_ref from your source-of-truth order or payment attempt.
  • Reuse the same value when retrying the same logical operation.
  • Do not reuse the same value for a different monetary action.
  • Store both your external_ref and the Pagou resource id.

​
Conflict behavior

If you send a duplicated external_ref for a conflicting transaction create request, the API can return a 409 response.

​
Where idempotency matters most

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

​
Retry pattern

  1. Retry safely only if you can prove it is the same logical operation.
  2. If the network outcome is unknown, reconcile with GET before creating a new resource.
  3. Use your persisted external_ref mapping to avoid duplicate money movement.