4. Informing the parameters

There are two different ways of providing the information required to process the payment: setting the data in the object used by each method or including specific attributes to HTML inputs in your checkout. Below we list the methods, their parameters and the equivalent attributes if you prefer to set the values using HTML inputs.

All methods return "this" to allow chaining of methods together.

4.1. setMerchant

Notes:

To connect to the sandbox account, ensure to modify the setMerchant()method by adding the parameter "homolog": true. Please find the sample below.
Sandbox environment:

$PB.setMerchant({
            "pbtoken": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
            "homolog": true
        });

Production environment:

$PB.setMerchant({
            "pbtoken": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
        });

4.2. setCustomer

4.3. setOrder

4.4. setPayment

4.5. setCard

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

d) There are two types of tax IDs in Brazil: CPF (used by individuals, having 11 digits) and CNPJ (used by companies, having 14 digits). PagBrasil.JS will automatically remove the separators (e.g. "123.123.123-34" to "12312312334").

You must validate the tax ID to prevent sending to PagBrasil invalid values. 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.

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

f) 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, PagBrasil.JS calls back with error "Duplicated order.". Our server will also respond with "Duplicated order." if you try to re-submit an order that ir 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.
Characters allowed in the parameter order (regular expression): [a-zA-Z0-9\.\-\_\/]

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

h) The minimum amount of a credit card 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.

i) Parameter cc_prevsaved may be used to charge a previously saved credit card. You may use it to refer to a credit card used in a previous order, or a token created using the method doAddToken (see item 5.1).

To be able to charge in the future a credit card linked to an order, set the parameter cc_save=1, and in the future order just set cc_prevsaved with the the original order number. For example, if order 123456 was submitted in the past with the parameter cc_save=1, you may charge the same customer again in the future by setting the parameter cc_prevsaved as "123456". Please note that:

• If the original order number was not submitted using cc_save=1 then PagBrasil.JS will call back with error "Order not found".

• If you use parameter cc_prevsaved you have to leave in blank the parameters cc_holder, cc_number, cc_expiration and cc_cvv. All other parameters must be populated as usual because information such as the customer's address and e-mail address may have changed.

• Parameter cc_save is ignored when cc_prevsaved is not blank

• To prevent the wrong customer from being charged, we will check if the parameter customer_taxid matches the one provided in the original order. If it doesn't match then PagBrasil.JS will call back with error "Parameter customer_taxid doesn't match the information previously saved".

• IMPORTANT: The merchant using PagBrasil is contractually obliged to inform the end customer by email between 5 - 15 days before an upcoming recurring payment charge. Therefore the implementation of such an automated email must be an integral part of the recurring payment implementation.

j) Current accepted brands:

k) To process a Samsung Pay payment, please set parameter wallet_type="SP". You will also need to send us the parameter wallet_payload with the payload returned by Samsung Pay (entire JSON response). Credit card details will be decrypted from the wallet_payload, thus you will not submit parameters cc_holder, cc_number, cc_expiration and cc_cvv.

Please contact us to enable Samsung Pay in your account.

l) By default a transaction is shown on the customer's credit card statement as "PB*XXXXXXX".

• "PB" is what is called the hard descriptor (cannot be changed).

• "XXXXXXX" is the soft descriptor (customizable).

The soft_descriptor parameter accepts letters, digits and spaces (regular expression [a-zA-Z0-9\s]). The string is truncated to the maximum allowable length of 13 characters. When receiving the parameter soft_descriptor with invalid characters, we will accept it but remove those characters from the string. When this parameter is blank, it is replaced by the default soft descriptor defined in the PagBrasil Dashboard. If there's no default soft descriptor defined in the dashboard, this parameter is replaced by the merchant commercial name.

m) When parameter cc_save is set to "1" our server will allow the merchant to charge the same credit card again in the future without needing to inform parameters cc_holder, cc_number, cc_expiration and cc_cvv. To define cc_save=1 you need to have the customer explicitly authorized you to process recurring payments using their credit card. To charge a previously saved credit card please use the parameter cc_prevsaved. To delete a previously saved credit card please refer to the credit card documentation, item 7. Recurring payments are disabled by default. If you want to use the parameter cc_save for recurring payments, please contact PagBrasil for further information. Please note that when the order is not successfully authorized cc_save will not be applied. That prevents invalid credit card information from being stored.

n) Please find below information on each cc_auth value.

• cc_auth=0 (or blank) - Authorize and capture a transaction immediately.

• cc_auth=1 - Authorize a transaction, but don't capture it now. The amount set at amount_brl will be held on the customer's credit card for later confirmation. Pre-authorizations will be held for 14 days.

• cc_auth=2 - Capture a previously authorized transaction. When this option is used the parameter order needs to be populated with the order number of the transaction that was pre-authorized beforehand using cc_auth=1. The order can't be older than 14 days. The amount to be captured defined at parameter amount_brl needs to be lower than or equal to the amount previously authorized. When setting cc_auth=2 the only parameters that you should submit are pbtoken, order, payment_method, amount_brl and cc_auth.

Examples of parameters order, amount_brl and cc_auth for 3 types of scenarios:

• Charge BRL 100 to a credit card:

  order=test1
  amount_brl=100
  cc_auth=0

• Pre-authorize BRL 100 and then later capture (charge) the full amount:

  Step 1:
  order=test2
  amount_brl=100
  cc_auth=1

  Step 2: (up to 14 days later than Step 1)
  order=test2
  amount_brl=100
  cc_auth=2

• Pre-authorize BRL 100 and then later charge only BRL 75 (partial capture):

  Step 1:
  order=test3
  amount_brl=100
  cc_auth=1

  Step 2: (up to 14 days later than Step 1)
  order=test3
  amount_brl=75
  cc_auth=2

p) To emulate a successful payment, please refer to the documentation of each specific payment method available.