Versions Compared

Version Old Version 24 New Version 25
Changes made by

PagBrasil

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

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

...

Anchor
4.1.c
4.1.c
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). 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.

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
4.1.d
4.1.d
d) The order number must be unique for a specific customer. 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.". Our server will also respond with "Duplicated order." if you try to re-submit an order that is already paid. If parameters order and customer_taxid are equal to a previously submitted unpaid order, the previous order will be updated with the new information provided and the response will be the URL to view/print the Boleto Bancário (see note "c"). Characters allowed in the parameter order (regular expression): [a-zA-Z0-9\.\-\_\/]

...

Anchor
4.1.f
4.1.f
f) You need to let the customer to select if they are a "pessoa física" (individual) or a "pessoa jurídica" (company). If they select "pessoa física", you need to ask for their full name and CPF (see note "g"). If they select "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 "g").

...

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.

...

Anchor
4.2.a
4.2.a
a) To authenticate the legitimacy of the response, the last element of the XML serves as a signature. 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.

...

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.

...

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.

...