­4. Requesting a payment

4.1. Sending the request

Important: Your server must be PCI-DSS compliant (pcisecuritystandards.org - SAQ D or AoC) for processing credit card payments. If you can't meet the PCI Data Security Standards, you will need to embed our iframe within your order form instead of just transmitting the credit card details to PagBrasil's API. Please refer to item 8 to learn more about this feature. Under no circumstances should the end customer's credit card details be stored in any database (including logs). Should you need to charge the same credit card in the future, please use PagBrasil's recurring payment feature (see item 4.1, note "j"). When using that feature, you should always clearly inform your end customer with a corresponding alert on the order form that their credit card details will be securely stored for future charges, and that they may request the removal from the database at anytime (see item 7).

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:

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). From the response's parameter "order_status" you will be able to determine if the order was authorized or not. Please refer to item 5.2 for further information on the XML elements of the response.

In case you don't receive any response from our server, do not resubmit the POST before requesting information about it using function "getorder", to prevent duplicated charges.

In case of delays caused by bank servers or connectivity problems and when an order is submitted for manual review, the response will contain the payment status "WP", which indicates that the order was queued for later processing. After that "/api/order/add" response your server will receive asynchronously an IPN (Instant Payment Notification via a webhook) with the payment response.

If your server is receiving a synchronous IPN for all "/api/order/add" calls, your PagBrasil merchant account was opened before the integration manual version 7.30 and has not yet been updated. To switch to asynchronous IPNs, please confirm your script is reading our XML response with the order details, and contact us to request the legacy synchronous IPNs to be turned off. Once the switch is done, you will notice significant speed improvements with the "/api/order/add" responses. IPNs will continue to be sent asynchronously when the instant XML response indicates a "WP" payment status (cases described above).

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 submitted to a new approval attempt.
Characters allowed in the parameter order (regular expression): [a-zA-Z0-9\.\-\_\/]

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

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

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

h) 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:

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.

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

j) 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 refer to "/api/order/add" parameter cc_prevsaved. To delete a previously saved credit card please refer to 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.

k) Parameter cc_prevsaved may be used to charge a previously saved credit card (see "/api/order/add" parameter cc_save). Its value must be 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 our server will respond with "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 our server will respond with "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.

l) 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 secret, 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

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

n) To test a successful credit card charge, please use one of the sample credit cards below with the following CVV and expiration date:

CVV: 123
Expiration: 12/29

Current accepted brands:

You may use whatever data you wish to complete the other sections (e.g. credit card holder, installments, etc). Charges to a sample credit card with the above CVV and expiration date will always be authorized. To test a failed payment, you just need to change the CVV or expiration date.

Please note that you must be using a test account to use a sample card.

IMPORTANT:

You must inform the customer on both the confirmation page and by e-mail that their credit card statement will show "PB*XXXXXXX" as payee (XXXXXXX will be replaced with soft descriptor you're going to use). Such advice is crucial, since most chargebacks occur because the card holder doesn't know the exact payee name. For example, if you have set your soft descriptor as "MYSTORE", the customer's credit card statement will show "PB*MYSTORE". See note "i" on how to define the soft descriptor.

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

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

4.2. Receiving the IPN with the authorization response

In case of delays caused by bank servers or connectivity problems and when an order is submitted for manual review, the response will contain the payment status "WP", which indicates that the order was queued for later processing. After that "/api/order/add" response your server will receive asynchronously an IPN with the payment response.

If your server is receiving a synchronous IPN for all "/api/order/add" calls, your PagBrasil merchant account was opened before the integration manual version 7.30 and has not yet been updated. To switch to asynchronous IPNs, please confirm your script is reading our XML response with the order details, and contact us to request the legacy synchronous IPNs to be turned off. Once the switch is done, you will notice significant speed improvements with the "/api/order/add" responses. IPNs will continue to be sent asynchronously when the instant XML response indicates a "WP" payment status (cases described above).

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.

PagBrasil's POST:

Notes:
a) After processing our IPN your server needs to acknowledge it has successfully received it by writing "Received successfully [timestamp]". If your server responds to our IPN with an invalid acknowledgement, our system will e-mail your technical contact a warning notification (subject "Urgent: Error posting IPN - Not Compliant"). In this case, the IPN will not be resent and you may want to resend the IPN manually at the PagBrasil Dashboard, menu IPN History, after resolving the problem at your end.

If we are not able to connect to your server to send an IPN, our system will e-mail your technical contact a warning notification (subject "Urgent: Error posting IPN - Fail") and will then try to resend the IPN as follows:

• The next 7 attempts will take place every 7 minutes.

• The next 23 attempts will take place every 60 minutes. If the last attempt of sending the IPN fails, our system will e-mail another warning notification (subject "Urgent: Error posting IPN - Fail").

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

b) In case of delays caused by a bank or connectivity and when the order is submitted for manual review, PagBrasil's IPN may not be provided synchronously.

c) The payment status is returned as "R" (Rejected) in one of the three scenarios below:

• Our fraud screening denied the transaction for security reasons – without submitting it to the bank for authorization.
  or

• An order was submitted using cc_auth=2 and the pre-authorization is older than 14 days. See item 4.1, note "l".
  or

• An order was submitted using cc_auth=2 with amount_brl greater than the pre-authorized amount. See item 4.1, note "l" for further details. Please note that in this case the order_status will remain "PA" (see item 5.2 for all order_status values). Therefore the capture request can be resubmitted for the same order.

d) To authenticate the legitimacy of the IPN, you may check the parameter secret and/or the parameter signature, which is a HMAC-MD5 hash based on three parameters and a key defined at the PagBrasil Dashboard, menu Account > Settings. The HMAC-MD5 source string is the concatenation of the values of the parameters order, amount_brl and payment_status and the total length for these three parameters. For example, if parameter order="1234567890", amount_brl="39.50" and payment_status="P", the parameter signature would be "3093a7dffa0c04e74e827d1b52ef514e".

In this example, the hash for the signature was computed using the string "123456789039.50P16" with the key "36d5f7184574caf84f5b48530ac0d690".