Payout

With PagaSul, you can send money directly to your customers' bank accounts or Pix keys.

Here is a step-by-step description of the payout processing flow in PagaSul.

How to integrate

1. Create a pay-out

Send a POST request to /v2/pay-out. Include a signature in the header, and specify the payment method and the beneficiary's account details.

curl -X POST https://api.pagasul.com/v2/pay-out \
  -H "Content-Type: application/json" \
  -H "signature: <calculated>" \
  -d '{
    "client_id": 123,
    "client_payment_id": "payout_42",
    "amount": 150.00,
    "currency": "BRL",
    "payment_method": "BR.PIX",
    "payee": {
      "id": "user_1234",
      "cpf": "231.002.999-00"
    },
    "payee_account": {
      "pix_key": "johndoe@example.com",
      "pix_key_type": "EMAIL"
    },
    "payment_options": {
      "callback_url": "https://your-site.com/webhook"
    }
  }'

client_payment_id must be unique per payment in your system — it is used for idempotency.

The required payee_account fields depend on the payment method. For example, a Colombian bank transfer requires payee_account.number, payee_account.account_type, and payee_account.bank_code. See Payment Methods for the exact requirements per method, and Bank List for valid bank_code values.

For the full parameter list, see Create pay-out in the API Reference.

2. Handle the response

A successful request returns a 200 response with status: "new":

{
  "payment_id": 246001235,
  "status": "new",
  "result_code": "OK",
  "result_message": "payment processing"
}

Store the payment_id — you'll need it to correlate callbacks. For the full response structure, see Response.

3. Handle the callback

When the payout is processed, PagaSul sends a POST to your callback_url. Verify the signature in the header, then check the status field:

Status	Meaning	Action
success	Payout delivered	No action required
decline	Payout declined	Check result_code, notify the customer
failed	Processing error	Contact PagaSul support

For all statuses and result codes, see Statuses & Codes. For the full callback structure, see Callbacks.