3.1. Sending the request
Your POST must be sent to https://sandbox.pagbrasil.com/api/pagstream/subscription/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 |
product_name | Product name. See note "c". | Yes | 254 |
customer_name | Customer's full name if an individual, or "razão social" if the customer is a company. See note "d" | Yes | 128 |
customer_taxid | CPF if an individual, or CNPJ if the customer is a company. See note "e" | 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). | Yes | 8 |
address_city | Customer's city | Yes | 40 |
address_state | Customer's state. See note "f" | Yes | 2 |
amount_brl | Amount in Brazilian Real of the recurring charge. | Yes | 7.2 |
limit | Maximum subscription renewals (0 or empty is unlimited). | No | 3 |
next_billing_date | Start date for the first recurring charge. | Yes | 10 |
frequency | Interval between the subscription renewals. Customized intervals may be defined at the PagBrasil Dashboard. | Yes | 1 |
response_type | XML (default) or JSON. | No | 4 |
cc_installments | Number of installments (1 to 12). See note "g". | No* | 2 |
cc_holder | Credit card holder's name | No* | 30 |
cc_number | Credit card number | No* | 14 - 19 |
cc_expiration | Credit card expiration date. | No* | 5 |
cc_cvv | Card verification value (security code). | No* | 3 - 4 |
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 parameter product_name must contain the name of the product or service purchased, and it is required for compliance purposes.
d) 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 "h"). 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 "e").
e) 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.
f) 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 |
Goiás | 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 |
g) The minimum amount of an installment is BRL 5. For example, a purchase amount of BRL 20 can be paid to a maximum of 4 installments. If e.g. an amount of BRL 20 is submitted to be charged in 5 installments, the transaction will always be declined by the credit card company.
3.2. Reading the response
PagBrasil's response will be an XML or JSON with the following structure:
Field | Description | Length |
|---|---|---|
subscription | Subscription identification | 9 |
status | 0 = Waiting for first payment | 1 |
amount_brl | Amount in Brazilian Real of the recurring charge | 7.2 |
next_billing_date | Start date for the first recurring charge. | 10 |