4. Requesting a payment

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

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

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
products	JSON structure with the list of products or service in the subscription. See note “i“	Yes	Unlimited
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	7.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.

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.

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\.\-\_\/]

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

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

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.

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:

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.

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

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