...
6.1. Sending the request
Your POST must be sent to https://sandbox.pagbrasil.com/api/pix/rec/add 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:
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 |
payer_ | |||
name | customer_name | ||
Yes | 254 | ||
Customer's full name if an individual, or "razão social" if the customer is a company. See note "e" | Yes | 128 | |
payer_taxid | CPF if an individual, or CNPJ if the customer is a company. See note "f" | Yes | 14 | customer_email | Customer's e-mail address | Yes
128 | |||
customer_phone | Customer's phone number (including the 2-digit area code) | Yes | 40 |
address_street | Customer's street address | Yes | 200 |
address_zip | Customer's postal code (in Brazil called CEP). Only digits, do not include the dash. | Yes | 8 |
address_city | Customer's city | Yes | 40 |
address_state | Customer's state. See note "g" | Yes | 2 |
pix_rec_description | Text that uniquely identifies the subscription within the customer's banking app. | No | 19 |
pix_rec_cycle | Define the recurrence cycle as one the following values: “weekly”, “monthly”, “quarterly”, “semiannual”, “annually”. | Yes | 10 |
pix_rec_expiration | Recurrence end date. | No | 10 |
pix_rec_first_recurrence | Estimated date of the first future recurring charge. | Yes | 10 |
pix_rec_minimum_amount | Minimum amount for recurring charges. This prevents the customer from setting a lower payment limit, but it may also make the customer hesitant to give their consent. Therefore, it should be used cautiously and aligned with the subscription the customer is signing up for. | No | 7.2 |
pix_rec_ | A string that can be concatenated to the URL our server posts the response to. See note "h" | No | 254|
retry | Set “1” to indicate it’s a recurring charge retry. We strongly recommend setting the parameter “pix_rec_retry” to 1 to enable retry attempts in case of failure. See note “g” | No | 1 |
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) The response will be an XML with the recurrence details, in exactly the same format as a "/api/pix/rec/get" response (see item
...
9.2).
...
| Anchor |
|---|
...
|
...
|
...
| Anchor |
|---|
...
|
...
|
...
| Anchor |
|---|
...
|
...
|
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:
| Code Block | ||||
|---|---|---|---|---|
| ||||
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.
...
| Anchor |
|---|
...
|
...
|
...
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 |
...
If a recurring charge fails, you cannot resend it without clearly identifying it as a retry. Otherwise, the customer’s bank may interpret it as an attempt to dishonor the recurrence cycle consent. A maximum of three charge retries is allowed, spaced on different days, within 7 days of the original charge date, always for the same amount as the original recurring charge.
6.2. Receiving the webhook with the authorization response
You need to login to the PagBrasil Dashboard and specify the URL (webhook) you want PagBrasil to send the notification confirming the recurring was authorized. 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.
PagBrasil's POST:
Field | Description | Length |
|---|---|---|
secret | Secret phrase as defined in the PagBrasil Dashboard | 128 |
action | Value “consent”. | 7 |
payment_method | X = | |
Pix | 1 | |
pix_rec_id | Recurrence identifier to be used when requesting future recurring charges. | 64 |
status | A = Authorized | 1 |
Notes:
...
created, authorized, rejected, canceled | 10 |
Notes:
a) 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.
...
b) 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.
...
| Anchor | ||||
|---|---|---|---|---|
|
...
Account > Settings. The HMAC-MD5 source string is the concatenation of all the elements that are present in the structure and its total length.