Skip to main content
Use this page for the write path that starts a payout.

​
Example request

curl --request POST \
  --url https://api.pagou.ai/v2/transfers \
  --header "Authorization: Bearer YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "pix_key_type": "EMAIL",
    "pix_key_value": "supplier@example.com",
    "amount": 1200,
    "description": "Supplier payout",
    "external_ref": "payout_1001",
    "notify_url": "https://merchant.example/webhooks/pagou/transfers"
  }'

​
Example response

{
  "success": true,
  "requestId": "req_2001",
  "data": {
    "id": "po_1001",
    "status": "pending",
    "amount": 1200,
    "pix_key_type": "EMAIL",
    "external_ref": "payout_1001",
    "created_at": "2026-03-16T14:00:00.000Z"
  }
}

​
Common error

Status 422 
{
  "type": "https://api.pagou.ai/problems/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The request contains invalid data.",
  "errors": [
    {
      "field": "pix_key_value",
      "message": "Invalid PIX key value",
      "code": "invalid_string"
    }
  ]
}
Fix: send the correct pix_key_type and a matching pix_key_value. Do not document or depend on unsupported fields such as recipient_name.

​
What to persist

  • your payout request ID or external_ref
  • Pagou transfer id
  • current transfer status
  • Pagou requestId

​
Production note

Treat the create response as an acknowledgement, not final settlement. Final operational state belongs to webhook delivery and reconciliation.

​
Next steps