Versions Compared

Version Old Version 2 New Version 16
Changes made by

Diego Lopes

PagBrasil

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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

product_name

Product name. See note "d"

Yes

254

customerpayer_name

Customer's full name if an individual, or "razão social" if the customer is a company. See note "e"   

Yes

128

customerpayer_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.
Format: YYYY-MM-DD

No

10

pix_rec_first_recurrence

Estimated date of the first future recurring charge.
Format: YYYY-MM-DD

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

parampix_rec_url

A string that can be concatenated to the URL our server posts the response to. See note "h"   

No

254retry

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.

...

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

...

Anchor
1d
1d
d) The parameter product_name must contain the name of the product or service purchased, and it is required for compliance purposes.

...

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
1g1h1g
1h
g) The parameter address_state must be the official abbreviation used in Brazil. To prevent customer from entering an invalid state, please see table below to create a select object (drop-down list).

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

Anchor1h1hh) The URL our server posts the response to for an "/api/pix/rec/add" call consists of a fixed and a dynamic part. The first part is defined at the PagBrasil Dashboard, menu Account > Settings. The second part is defined using param_url (optional). For example, if you define at the PagBrasil Dashboard the URL as "https://www.test.com/script.asp" and param_url as "?customer_id=12345&newsletter=yes" we will post the authorization response to: "https://www.test.com/script.asp?customer_id=12345&newsletter=yes" 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 IPNwebhook's URL please contact us requesting an exception.

...

Field

Description

Length

secret

Secret phrase as defined in the PagBrasil Dashboard

128

action

Value “consent”.

7

payment_method

X = PagBrasil Pix

1

pix_rec_id

Recurrence identifier to be used when requesting future recurring charges.

64

recurrence_status

A = Authorized
R = Rejected

1

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 IPN webhook, your server needs to acknowledge that it has successfully received it by writing "Received successfully [timestamp]". If your server responds to our IPN with an invalid acknowledgement, the webhook fails our system will e-mail your technical contact a warning notification (subject "Urgent: Error posting IPN - Not Compliantwebhook"). In this case, the IPN will not be resent and you may want to resend the IPN manually at the PagBrasil Dashboard, menu IPN History, after resolving the problem at your end.If we are not able to connect to your server to send an IPN, our system will e-mail your technical contact a warning notification (subject "Urgent: Error posting IPN - Fail") and If you activate the auto resend, our system will then try to resend the IPN 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 IPN webhook fails, our system will e-mail another warning notification (subject "Urgent: Error posting IPN - Failwebhook").

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

...

Anchor
7.c
7.c
c) To authenticate the legitimacy of the webhook, menu IPN History.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.