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.

Full parameter list

Parameter	Type	Required	Description
client_id	integer	Yes	Your account identifier, provided upon integration
client_payment_id	string	Yes	Your payment ID, must be unique to the client_id used
payment_method	string	Yes	Selected payment method code (see Supported payment methods section)
currency	string	Yes	Payment currency (see Supported payment methods section)
amount	decimal	Yes	Requested payment amount (for example: pass 12.34 for 12 dollars 34 cents amount)
payee	object	Yes	Customer data section
payee.id	string	Yes	A unique identifier for a customer or customer account on your side. It is used to accumulate customer data and for anti-fraud protection
payee.is_trusted	boolean	Optional	If passed and "true" customer marked as trusted (for use please consult Pagasul representative)
payee.name	string	Optional	Customer name
payee.email	string	Optional	Customer email
payee.country	string	Optional	Customer country (alpha-2 code)
payee.state	string	Optional	Customer state
payee.city	string	Optional	Customer city
payee.address	string	Optional	Customer address
payee.phone	string	Optional	Customer phone
payee.language	string	Optional	Preferred language for customer
payee.cpf	string	Optional	Customer CPF (Cadastro de Pessoas Físicas) for Brazil payment methods. Can be passed in following formats: "231.002.999-00" or "23100299900"
payee.cuit	string	Optional	Customer CUIT (Unique Tax Identification Code) for Argentina payment methods. Can be passed in following formats: "30-69330706-2" or "30693307062"
payee.citizenship_card	string	Conditional	Number of the Citizenship Card (Cédula de Ciudadanía) for Colombian/Ecuadorian payment methods
payee.nit	string	Conditional	Unique Taxpayer Number (Número de Identificación Tributaria) for Colombian/Bolivian payment methods
payee.pas	string	Optional	Passport needed for Bolivian/Ecuadorian payment methods
payee.ce	string	Optional	Customer Identity card of Foreigners (Cédula de Extranjería) for Colombian payment methods
payee.ti	string	Optional	Customer identity document (Tarjeta de Identidad) for Colombian payment methods
payee.ci	string	Optional	Customer identity document (Cédula de Identidad) for Bolivia/Venezuela payment methods. For Venezuela it must start with letter V or E
payee.ruc	string	Optional	Ecuadorian taxpayer number (Registro Único de Contribuyente)
payee.rif	string	Optional	Venezuela's tax number (Registro de Información Fiscal). It must start with letter V, E, P, J, G, or C
payee_account	object	Yes	Customer account data for payment
payee_account.pix_key	string	Conditional	Required for Pix method. Key for Pix account. One of the following: CPF, CNPJ, E-mail, Phone, EVP
payee_account.pix_key_type	string	Conditional	Required for Pix method. Type of pix key value. One of: CPF, CNPJ, EMAIL, PHONE, EVP
payee_account.breb_key	string	Conditional	Required for Bre-b method. Key for Bre-b account. One of the following: E-mail, Phone, ID (Cédula), Alpha-Numeric Code (user-generated alias)
payee_account.account_type	string	Conditional	Type of account number passed in number parameter. (Mandatoriness see in section Supported payment methods). One of: CACC, SVGS
payee_account.number	string	Conditional	Bank account number or mobile phone number that links to bank account (Mandatoriness see in section Supported payment methods)
payee_account.bank_code	string	Conditional	Payee bank code (Mandatoriness see in section Supported payment methods). One of bank code from list (see Bank Codes section)
payee_account.holder_name	string	Conditional	Bank account holder name. Required for Argentina bank transfers (Mercado Pago) method
payment_options	object	Optional	Optional section for extra parameters used for payment flow adjustment
payment_options.callback_url	string	Optional	If passed, the notification on payment status change will be sent to the specified URL
payment_extra_param	string	Optional	Please, contact to your manager for possible parameter values and purpose

Also 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.