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 |
|---|---|---|---|
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 "c" | Yes | 64 |
payment_link | Set "1" to create the Payment Link. | Yes | 1 |
payment_option | Defines the payment methods to be included in the Payment Link. If not present all payment methods available will be included. C = Credit card Separate multiple payment methods by comma (e.g. "C,B,P"). | No | Unlimited |
payment_link_expiration | Number of days (0 - 999) the Payment Link 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. | No | 3.0 |
url_return | URL you want the customer to be redirected to after they complete the payment. You may include any parameters in the URL (i.e. order number) so that you can display the proper page when the customer is redirected to "url_return". | No | 254 |
product_name | Product name. See note "d" | Yes | 254 |
customer_name | Customer's full name if an individual, or "razão social" if the customer is a company. See note "e" | Yes | 128 |
customer_taxid | CPF if an individual, or CNPJ if the customer is a company. See note "f" | 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_number | Customer's street address number | No | 10 |
address_number_complement | Customer's street address complement (e.g. suite) | No | 40 |
address_neighborhood | Customer's neighborhood | No | 40 |
address_zip | Customer's postal code (in Brazil called CEP). | Yes | 8 |
address_city | Customer's city | Yes | 40 |
address_state | Customer's state. See note "g" | Yes | 2 |
amount_brl | Amount in Brazilian Real | Yes | 5.2 |
param_url | A string that can be concatenated to the URL our server posts the response to. See note "h" | No | 254 |
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 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 that you will need to redirect the customer to (see item 4.2).
Characters allowed in the parameter order (regular expression): [a-zA-Z0-9\.\-\_\/]
d) The parameter product_name must contain the name of the product or service purchased, and it is required for compliance purposes.
e) You need to let the customer selects 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").
f) 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.
g) 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 |
h) The URL our server posts the response to for an "/api/order/add" call consists of a fixed and a dynamic part. The first part is defined at the PagBrasil Dashboard, menu Account > Settings. The second part is defined using param_url (optional). For example, if you define at the PagBrasil Dashboard the URL as "https://www.test.com/script.asp" and param_url as "?customer_id=12345&newsletter=yes" we will post the authorization response to: "https://www.test.com/script.asp?customer_id=12345&newsletter=yes".
i) To emulate a successful payment, please refer to the documentation of each specific payment method available at the Payment Link.
j) If you send all the customer information with correct values, Payment Link will only contain a brief summary of the order and prompt the customer to select the payment method. If you leave empty an optional parameter, or its value is incorrected formatted, Payment Link will display a checkout form to give the customer the chance to inform/correct such field.
4.2. Reading the response
Response will be the URL that you will need to redirect the customer to. You may validate the response by simply checking if it starts with "http". If it doesn't start with "http" then the response is an error message. The URL length will be up to 80 characters.
4.3. Receiving the IPN with the authorization response
When the customer completes the payment, we will post to your server the information whether payment was authorized or declined. You need to login to the PagBrasil Dashboard and specify the URL (webhook) you want PagBrasil to send the IPN (Instant Payment Notification) to for your payment request. 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.
Each payment method has a different IPN flow and structure. Please refer to the documentation of each specific payment method available at the Payment Link.
Please note that you may always search for an order status at the PagBrasil Dashboard, and don't use the IPN feature.