5. Sending a payout
- PagBrasil
Your POST must be sent to https://sandbox.pagbrasil.com/api/payout/ setting the content-type of the request header and body as "x-www-form-urlencoded".
Please note that this URL shall only be used for integration and testing procedures. Once the Payment Service Agreement is signed, you will receive the production environment's URL when you request your account to go live.
Request parameters (see notes below):
5.1. Sending a payout
Field | Description | Required | Length |
|---|---|---|---|
secret | Secret phrase as defined in the PagBrasil Dashboard | Yes | 128 |
pbtoken | Token assigned to your merchant account. Your token is displayed at the PagBrasil Dashboard, menu Account > Settings. | Yes | 32 |
action | Action to be performed. Value "addpayout". | Yes | 9 |
payee_id | CPF/CNPJ of the recipient of the payout amount (payee_taxid submitted on "addpayee" action). When transferring between PagBrasil merchant accounts, please use the pbtoken assigned to the recipient's account. | Yes | 32 |
payout_amount | Amount to be paid to recipient in Brazilian Real. Format: 99999.99 | Yes | 7.2 |
payout_description | Description to be saved as the product name preceded by "Payout - " (e.g. considering payout_description = "XYZ", product name is set as "Payout - XYZ"). When not informed, product name is simply set as "Payout". | No | 254 |
When a payout is successfully registered in our database, PagBrasil's response has the following structure:
Field | Description | Length |
|---|---|---|
action | Value "addpayout". | 9 |
success | Value "true" indicates the payout was successfully included in our database. | 5 |
id | Unique number that identifies the payout. | Unlimited |
When a payout failed to be registered in our database, PagBrasil's response has the following structure:
Field | Description | Length |
|---|---|---|
action | Value "addpayout". | 9 |
success | Value "false" indicates the payout failed to be included in our database. | 5 |
error_message | Error message(s), separated by semicolons. | Unlimited |
internal_message | PagBrasil's internal use information. | Unlimited |
5.2. Receiving the webhook
PagBrasil will send a webhook to your server whenever a payout is requested or processed (except when transferring between PagBrasil merchant accounts). See note "g"
You need to login to the PagBrasil Dashboard and specify the URL you want PagBrasil to send the webhook. By default we only allow outgoing connections to HTTPS URLs at standard port 443. If you plan to use a different port number in the webhook's URL please contact us requesting an exception.
Webhook content has the following structure:
Field | Description | Length |
|---|---|---|
secret | Secret phrase as defined in the PagBrasil Dashboard | 128 |
action | addpayout = Payout requested | 13 |
taxid | CPF/CNPJ of the recipient of the payout amount. | 14 |
id | Unique number that identifies the payout. | Unlimited |
amount | Payout amount in Brazilian Real | 7.2 |
date | Timestamp. Format: YYYY-MM-DD HH:MM:SS | 19 |
signature | HMAC-MD5 hash that authenticates the webhook. | 32 |
Notes:
a) All fields are required except when noted otherwise.
b) If a parameter is sent with a size greater than the maximum allowed, process will not be aborted but the value will be truncated.
c) Response format is defined at the PagBrasil Dashboard. API's response format may be defined as XML or JSON, and the webhook may be sent as an XML, a JSON or a POST.
d) There are two types of tax IDs in Brazil: CPF (used by individuals) and CNPJ (used by companies). You must validate the tax ID to prevent sending to PagBrasil invalid values. Please find below the format for each type of tax ID.
CPF: 11 digits, with no separator. Customers use to write CPFs with separators (example: 123.123.123-12), but you must allow to enter only digits from 0 to 9 (example: 12312312312).
CNPJ: 14 digits, with no separator. Companies use to write CNPJs with separators (example: 12.345.678/0001-23, but you must allow to enter only digits from 0 to 9 (example: 12345678000123).
Example of javascript to prevent other characters than digits:
onKeyPress='if (window.event.keyCode<48 || window.event.keyCode>57) event.returnValue = false;'The last 2 digits of the CPF/CNPJ are check digits, and you will need to use them to validate the tax ID entered by the customer. You will find examples of CPF/CNPJ validation routines in different languages at the PagBrasil Dashboard, menu Resources. For testing purposes, please use CPF 91051605962 and CNPJ 78797547000157.
Due to validation security reasons, this field cannot be changed after insertion. In order to change this information you must delete the old payee and then add a new one.
e) To authenticate the legitimacy of the webhook, you may check the parameter secret and/or the parameter signature, which is a HMAC-MD5 hash based on the values of all elements (except the secret) and a key defined at the PagBrasil Dashboard, menu Account > Settings. The HMAC-MD5 source string is the concatenation of all the elements that are present in the structure and its total length.
CONFIDENTIAL