Creating a pay-out request

This section provides the instructions on how to build a pay-out request.

URL	https://api.pagasul.com
API endpoint	/v2/pay-out
HTTP request method	POST
Request body format	JSON

Header	Value	Description
Signature	calculated	Signature string. For the information on how to generate the signature, see Signature generation.
Content-Type	json	HTTP header indicating the media type of the resource sent in the request body.

Parameters of a pay-out request:

In PagaSul, there are the following types of parameters depending on whether they are required in the pay-out request:

• Strictly required—the parameter is always required in the pay-out request
• Optional—the parameter is optional
• Required conditionally—the parameter may be sometimes required depending on the payment method you initiate the payment with. See the Payment methods section to check whether it is required in the request

Object/Parameter	Type	Required	Description
client_id	integer	Strictly required	Account ID you obtained from PagaSul when integrating.
client_payment_id	string	Strictly required	Payment ID unique within your system.
currency	string	Strictly required	Code of the pay-out currency in the ISO-4217 alpha-3 format.
amount	number	Strictly required	Pay-out amount in major currency units, e.g., pass 12.34 for the 12 dollars 34 cents amount.
payment_method	string	Strictly required	Payment method's code. For the values that can be passed in this parameter, see the Payment methods section.
payee	object
payee.id	string	Strictly required	Unique ID of the customer within your system.
payee.name	string	Optional	Customer's full name.
payee.email	string	Optional	Customer's email.
payee.country	string	Optional	Customer's country in the ISO 3166-1 alpha-2 format.
payee.state	string	Optional	Customer's state.
payee.city	string	Optional	Customer's city.
payee.address	string	Optional	Customer's address.
payee.phone	string	Optional	Customer's phone number.
payee.language	string	Optional	Customer's preferred language.
payee.cpf	string	Optional	Customer's CPF (Cadastro de Pessoas Físicas) for Brazilian payment methods. Can be passed in the following formats: 231.002.999-00, 23100299900
payee.cuit	string	Optional	Customer's CUIT (Clave Única de Identificación Tributaria) for Argentinian payment methods. Can be passed in the following formats: 30-69330706-2, 30693307062
payee.citizenship_card	string	Required conditionally	Customer's citizenship card (Cédula de Ciudadanía) for Colombian payment methods.
payee.nit	string	Required conditionally	Customer's NIT (Número de Identificación Tributaria) for Colombian payment methods.
payee_account	object
payee_account.pix_key	string	Required conditionally	Customer's key for the Pix account. It may be the cusomer's CPF, CNPJ, email, phone, or EVP.
payee_account.pix_key_type	string	Required conditionally	Type of the customer's Pix key. Possible values: CPF, CNPJ, EMAIL, PHONE, EVP.
payee_account.account_type	string	Required conditionally	Customer's bank account type. Possible values: CACC—for the current account, SVGS—for the savings account.
payee_account.number	string	Required conditionally	Customer's bank account number.
payee_account.bank_code	string	Required conditionally	Customer's bank code. For the values that can be passed in this parameter, see the Bank list section.
payee_account.holder_name	string	Required conditionally	Bank account's holder name.
payment_options	object
payment_options.callback_url	string	Optional	The URL to send callbacks to. If not passed, callbacks will be sent to the URL you provided PagaSul with when integrating.

Here is an example of a pay-out request to the PagaSul payment platform.

curl --request POST 
  --url https://api.pagasul.com/v2/pay-out 
  --header 'Content-Type: application/json' 
  --header 'Signature: NTU1YjUwY2M1MTU3ZjE2ZmY5MjMDI1lZNDQ2NDQ=' 

  --data '{
  "client_id": 123,
  "client_payment_id": "payment_35",
  "payment_method": "BR.PIX",
  "currency": "BRL",
  "amount": 192.21,
  "payee": {
      "id": "customer_1234"
  },
  "payee_account": {
      "pix_key": "johndoe@example.com",
      "pix_key_type": "EMAIL"
  },
  "payment_options": {
      "callback_url": "https://example.com/callback/"
  }
}'

After receiving your request, the PagaSul payment platform will send a response to your system. To see what a response may look like, check out the Response section.

PagaSul returns you the final payment status in a separate callback. For the information about callbacks, see the Callback section.