Anchor | ||||
---|---|---|---|---|
|
Your POST must be sent to https://sandbox.pagbrasil.com/api/order/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 |
order | Order number. See note "d" | Yes | 64 |
payment_method | B = Boleto Bancário | Yes | 1 |
product_name | Product name. See note "e" | Yes | 254 |
customer_name | Customer's full name if an individual, or "razão social" if the customer is a company. See note "f" | Yes | 128 |
customer_taxid | CPF if an individual, or CNPJ if the customer is a company. See note "g" | 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 "h" | Yes | 2 |
amount_brl | Amount in Brazilian Real | Yes | 5.2 |
bol_expiration | Number of days (0 - 999) the Boleto Bancário is valid for. If you don't use this parameter, our system will use the default value set at the PagBrasil Dashboard, menu Account > Settings. You may extend the expiration date of an already issued boleto using the API function "/api/order/extend" (see item 7). | No | 3.0 |
param_url | A string that will be included in the XML with the list of the orders paid (See item 4.2). It may contain any information the merchant wants to. | No | 254 |
store_code | Code defined by the merchant per store to identify a set consisting of a customized message and a logo that will be displayed on each boleto. Shall not be used when the merchant has only one store associated to the supplied merchant account credentials (pbtoken and secret). | No | 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.
Anchor | ||||
---|---|---|---|---|
|
To increase the conversion rate, we recommend to include the boleto link into the order confirmation e-mail sent to customers. That allows them to view/print the boleto at a later time. PagBrasil offers a service that automatically sends confirmation e-mails and SMS' to the customers, and a payment reminder before the boleto expires. Please contact us for further information on this service.
Anchor | ||||
---|---|---|---|---|
|
Characters allowed in the parameter order (regular expression): [a-zA-Z0-9\.\-\_\/]
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 |
Anchor | ||||
---|---|---|---|---|
|
You need to login to the PagBrasil Dashboard and specify the URL (webhook) you want PagBrasil to send the IPN (Instant Payment Notification) to with the list of Boletos Bancários paid. 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 IPN's URL please contact us requesting an exception.
PagBrasil's POST:
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. | Yes | 32 |
Notes:
Anchor | ||||
---|---|---|---|---|
|
b) After processing our IPN, your server needs to acknowledge that it has successfully received the list by writing "Received successfully [timestamp]". Your server may only confirm the receipt after validating the parameter "content" by checking if it has a closing tag </boletos_list>. If your server responds to our IPN with an invalid acknowledgement, our system will e-mail your technical contact a warning notification (subject "Urgent: Error posting IPN - Not Compliant"). In this case, the IPN will not be resent and you may want to resend it 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 will then try to resend the IPN 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 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.
Anchor | ||||
---|---|---|---|---|
|
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. |
Anchor | ||||
---|---|---|---|---|
|
Code Block | ||
---|---|---|
| ||
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>" |
Code Block | ||
---|---|---|
| ||
signature="7bea7c5d998a4cebda5738d59458858e" |
In this example, the hash for the signature was computed using the concatenation of the parameter content and its total length (555) with the key "36d5f7184574caf84f5b48530ac0d690".
Anchor | ||||
---|---|---|---|---|
|
Boletos Bancários are processed in the next day after it was paid (until 10 AM – Brasília time zone). Although customers may pay a Boleto Bancário on a bank holiday, banks will consider the transaction to be complete on the next business day. The next table shows when a Boleto Bancário will be processed considering the day it was paid. This table is important when answering a customer's inquiry about their order status.
Payment Day | Processing Day |
---|---|
Monday | Tuesday |
Tuesday | Wednesday |
Wednesday | Thursday |
Thursday | Friday |
Friday | Saturday |
Saturday (considered as Monday) | Tuesday |
Sunday (considered as Monday) | Tuesday |
Example for payment on a holiday: If the holiday is on a Wednesday, banks will consider the payment date as Thursday, hence the Boleto Bancário will be processed on Friday.
If the merchant has activated Boleto Flash®, any Boleto Bancário is automatically generated with the Flash feature. Boleto Flash® is compatible with traditional Boletos Bancários, so that one can pay a Boleto Bancário as Boleto Flash® and vice-versa – as long as the merchant has activated this exclusive feature. Payment confirmations for Boleto Flash® are sent within the same day. For more information about this product please read the Merchant Guide for Boleto Flash®, available at the PagBrasil Dashboard, menu Resources.