Versions Compared

Version Old Version 18 New Version 19
Changes made by

PagBrasil

PagBrasil

Saved on

Key

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

Anchor

...

4.1

...

4.1
4.1. Sending the request

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

...

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

...

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

...

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
ParametersDParametersD4.1.d
4.1.d
d) The order number must be unique for a specific customer.

...

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
ParametersEParametersE4.1.e
4.1.e
e) The parameter product_name must contain the name of the product or service purchased, and it is required for compliance purposes.

...

Anchor
ParametersFParametersF4.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").

...

Anchor
ParametersGParametersG4.1.g
4.1.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.

...

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
ParametersHParametersH4.1.h
4.1.h
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).

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

...

4.2

...

4.2
4.2. Receiving the IPN with the paid orders

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.

...

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:

Anchor
IpnAIpnA4.2.a
4.2.a
a) To authenticate the legitimacy of the response, the last element of the XML serves as a signature.

...

Please note that any IPN can be resent manually at any time at the PagBrasil Dashboard, menu IPN History.

...

Anchor
IpnCIpnC4.2.c
4.2.c
c) XML parameters for parameter "content":

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
IpnDIpnD4.2.d
4.2.d
d) Example of parameters content and signature:

...

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

...

4.3

...

4.3
4.3. Processing Schedule

Boletos Bancários are processed in the next day after it was paid (until 10 AM – Brasília time zone).

...