Versions Compared

Version Old Version 4 New Version 5
Changes made by

PagBrasil

PagBrasil

Saved on

Key

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

...

A) All fields are required except when noted otherwise.

...

AnchorParametersCParametersCB) 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 for the "/api/order/add" call will be an XML with the order details, in exactly the same format as a "/api/order/get" response (see item 5.2).

Anchor
ParametersC
ParametersC

Element "url_boleto" in the XML contains the URL that you will need to inform the customer to view/print the Boleto Bancário. Please refer to item 5.2 for further information on the XML elements of the response. AnchorParametersDParametersD

To increase the conversion rate, we recommend to include the boleto link into the order confirmation e-mail sent to customers.

...

D) The order number must be unique for a specific customer.

Anchor
ParametersD
ParametersD

If you try to submit two different transactions with the same order number but a different customer_taxid, our server will respond with the message "Duplicated order.".

...


Characters allowed in the parameter order (regular expression): [a-zA-Z0-9\.\-\_\/] anchorParametersFParametersF

...

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

Anchor
ParametersE
ParametersE

...

F) You need to let the customer to select if they are a "pessoa física" (individual) or a "pessoa jurídica" (company).

Anchor
ParametersGParametersFParametersG
ParametersF

If they select "pessoa física", you need to ask for their full name and CPF (see note "g").

...

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

Anchor
ParametersG
ParametersG

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

...

Code Block
breakoutModewide
languagejs
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. 
...
H) 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).
 Anchor
ParametersH
ParametersH
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
...
Field
Description
Required
Length
secret
Secret phrase as defined in the PagBrasil Dashboard.
Yes
128
payment_method
Value "B". This value specifies that the data being posted is for paid boletos bancários (either for traditional Boletos Bancários or Boleto Flash®).
Yes
1
content
XML as described. See note "c"   
Yes
Unlimited
signature
HMAC-MD5 hash that authenticates the parameter content.
See note "a"   
See note "d"   
Yes
32
Notes:  AnchorIpnAIpnA
a) To authenticate the legitimacy of the response, the last element of the XML serves as a signature.
 Anchor
IpnA
IpnA
 It is a HMAC-MD5 hash based on the values of all XML elements 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 XML and its total length. The XML examples below describe how the signature is computed.
...
  • 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 fails, our system will e-mail another warning notification (subject "Urgent: Error posting IPN - Fail").
...
Please note that any IPN can be resent manually at any time at the PagBrasil Dashboard, menu IPN History.
...
c) XML parameters for parameter "content":
 Anchor
IpnC
IpnC
Field
Description
order
Order number you informed when requesting the boleto (item 4.1).
payment_date
Date the Boleto Bancário was paid by the customer (not considering holidays, as explained in item 4.3). Format: MM/DD/YYYY.
amount_paid
Amount paid by the customer in Brazilian Real – may not be the exact amount due, so it must be validated and treated according to your policy.
amount_due
Amount printed in the Boleto Bancário (as informed in the parameter amount_brl – item 4.1).
param_url
String (encoded) that was passed to our server when the order was submitted. See item 4.1.
...
...
d) Example of parameters content and signature:
 Anchor
IpnD
IpnD
 Code Block
languagexml
content="<boletos_list>
<boleto>
<order>1234567890</order>
<payment_date>10/15/2010</payment_date>
<amount_paid>29.95</amount_paid>
<amount_due>29.95</amount_due>
</boleto>
<boleto>
<order>1234567891</order>
<payment_date>10/15/2010</payment_date>
<amount_paid>15.50</amount_paid>
<amount_due>16.50</amount_due>
</boleto>
<boleto>
<order>1234567892</order>
<payment_date>10/15/2010</payment_date>
<amount_paid>45.00</amount_paid>
<amount_due>35.00</amount_due>
<param_url>customer_id=12345%26newsletter=yes</param_url>
</boleto>
</boletos_list>"
...