4. Managing a payee

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.

Please see below the request parameters for specific actions.

4.1. Adding a payee

Field

Description

Required

Length

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 "addpayee".

Yes

11

payee_name

Payee's full name if an individual, or "razão social" if the payee is a company. See note "c"   

Yes

128

payee_taxid

CPF if an individual, or CNPJ if the payee is a company. See note "d"   

Yes

14

payee_bank

Identification of the bank in the Brazilian Central Bank. See note "e"   

Yes

3

payee_branch

Payee's account branch number (do not include the verification digit; for example: 1234).

Yes

12

payee_account

Payee's account number (must include the hyphen and the verification digit; for example: 1234568-0).

Yes

12

payee_account_type

Type of the payee's account. "1" = Checking (conta corrente) or "2" = Savings (poupança).

Yes

1

payee_document_link

URL where the payee's scanned documents are stored. See note "f"   

No

250

payee_description

Description to be registered as the product name when a payout is sent.

Yes

250

payee_email

Payee's e-mail address

Yes

128

payee_phone

Payee's phone number (including the 2-digit area code)

Yes

40

payee_street

Payee's street address

Yes

200

payee_zip

Payee's postal code (in Brazil called CEP). Only digits, do not include the dash.

Yes

8

payee_city

Payee's city

Yes

40

payee_state

Payee's state (official abbreviation). See note "j"   

Yes

2

4.2. Updating a payee

Field

Description

Required

Length

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 "updatepayee".

Yes

11

payee_name

Payee's full name if an individual, or "razão social" if the payee is a company. See note "c"   

No

128

payee_taxid

CPF/CNPJ of the payee being updated. Must be the same as the payee_taxid submitted on "addpayee" action. See note "d"   

Yes

14

payee_bank

Identification of the bank in the Brazilian Central Bank. See note "e"   

No

3

payee_branch

Payee's account branch number (do not include the verification digit; for example: 1234).

No

12

payee_account

Payee's account number (must include the hyphen and the verification digit; for example: 1234568-0).

No

12

payee_account_type

Type of the payee's account. "1" = Checking (conta corrente) or "2" = Savings (poupança).

No

1

payee_document_link

URL where the payee's scanned documents are stored. See note "f"   

No

250

payee_description

Description to be registered as the product name when a payout is sent.

No

250

payee_email

Payee's e-mail address

No

128

payee_phone

Payee's phone number (including the 2-digit area code)

No

40

payee_street

Payee's street address

No

200

payee_zip

Payee's postal code (in Brazil called CEP). Only digits, do not include the dash.

No

8

payee_city

Payee's city

No

40

payee_state

Payee's state (official abbreviation). See note "j"   

No

2

4.3. Deleting a payee

Field

Description

Required

Length

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 "deletepayee".

Yes

11

payee_taxid

CPF/CNPJ of the payee being deleted. Must be the same as the payee_taxid submitted on "addpayee" action. See note "d"   

Yes

14

4.4. Requesting information about a payee

Field

Description

Required

Length

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 "getpayee".

Yes

11

payee_taxid

CPF/CNPJ of the payee you want information about. Must be the same as the payee_taxid submitted on "addpayee" action. See note "d"   

Yes

14

When a payee is successfully registered in our database, PagBrasil's response has the following structure:

Field

Child Field

Description

Length

Field

Child Field

Description

Length

action

 

Value "getpayee".

8

success

 

Value "true" indicates the payee was successfully included in our database. To verify if the payee is active, you need to check the parameter payee->status.

5

payee

taxid

CPF/CNPJ of the payee being updated. Must be the same as the payee_taxid submitted on "addpayee" action. See note "d"   

14

 

bank

Identification of the bank in the Brazilian Central Bank. See note "e"   

4

 

branch

Payee's account branch number (do not include the verification digit; for example: 1234).

12

 

account

Payee's account number (must include the hyphen and the verification digit; for example: 1234568-0).

12

 

account_type

Type of the payee's account. "1" = Checking (conta corrente) or "2" = Savings (poupança).

1

 

status

0 = Pending
1 = Approved
2 = Rejected

1

 

name

Payee's full name if an individual, or "razão social" if the payee is a company. See note "c"   

128

 

email

Payee's e-mail address

128

 

phone

Payee's phone number

40

 

street

Payee's street address

200

 

zip

Payee's postal code (in Brazil called CEP). Only digits, do not include the dash.

8

 

city

Payee's city

40

 

state

Payee's state (official abbreviation). See note "j"   

2

 

document_link

URL where the payee's scanned documents are stored. See note "f"   

250

When a payee failed to be registered in our database, PagBrasil's response has the following structure:

Field

Description

Length

Field

Description

Length

action

Value "getpayee".

8

success

Value "false" indicates the payee 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

4.5. Receiving the webhook

PagBrasil will send a webhook to your server whenever a payee's status is changed. 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

Field

Description

Length

secret

Secret phrase as defined in the PagBrasil Dashboard

128

action

Action performed ("addpayee", "updatepayee" or "deletepayee").

11

taxid

CPF if an individual, or CNPJ if the payee is a company. See note "d"   

14

bank

Identification of the bank in the Brazilian Central Bank. See note "e"   

4

branch

Payee's account branch number (do not include the verification digit; for example: 1234).

12

account

Payee's account number (must include the hyphen and the verification digit; for example: 1234568-0).

12

account_type

Type of the payee's account. "1" = Checking (conta corrente) or "2" = Savings (poupança).

1

status

0 = Pending
1 = Approved
2 = Rejected

1

name

Payee's full name if an individual, or "razão social" if the payee is a company. See note "c"   

128

email

Payee's e-mail address

128

phone

Payee's phone number

40

street

Payee's street address

200

zip

Payee's postal code (in Brazil called CEP). Only digits, do not include the dash.

8

city

Payee's city

40

state

Payee's state (official abbreviation). See note "j"   

2

document_link

URL where the payee's scanned documents are stored. See note "f"   

250

signature

HMAC-MD5 hash that authenticates the webhook.
See note "h"   

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) If the payee is an individual ("pessoa física"), you need to ask for their full name and CPF (see note "d"). If they are a company ("pessoa jurídica"), you need to ask for the "razão social" (official company name registered at the local tax authority) and CNPJ (see note "d").

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.


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) Please find the bank numbers here (column "COD COMPENSAÇÃO").


f) URL where the payee scanned documents are stored. These documents should be hosted in a safe storage that can be accessed by PagBrasil. The URL to access each document individually must be submitted along with the payee data.


g) After processing our webhook, your server needs to acknowledge that it has successfully received it by writing "Received successfully [timestamp]". If the webhook fails our system will e-mail your technical contact a warning notification (subject "Urgent: Error posting webhook"). If you activate the auto resend, our system will then try to resend failed webhook as follows:

  • The next 7 attempts will take place every 7 minutes.

  • The next 23 attempts will take place every 60 minutes. If the last attempt of sending the webhook fails, our system will e-mail another warning notification (subject "Urgent: Error posting webhook").

Please note that any webhook can be resent manually at any time at the PagBrasil Dashboard.


h) 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.


i) 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.


j) Official abbreviation for Brazilian states:

State

Abbreviation

State

Abbreviation

Acre

AC

Alagoas

AL

Amapá

AP

Amazonas

AM

Bahia

BA

Ceará

CE

Distrito Federal

DF

Espírito Santo

ES

Goias

GO

Maranhão

MA

Mato Grosso

MT

Mato Grosso do Sul

MS

Minas Gerais

MG

Pará

PA

Paraíba

PB

Paraná

PR

Pernambuco

PE

Piauí

PI

Rio de Janeiro

RJ

Rio Grande do Norte

RN

Rio Grande do Sul

RS

Rondônia

RO

Roraima

RR

Santa Catarina

SC

São Paulo

SP

Sergipe

SE

Tocantins

TO

CONFIDENTIAL