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 Débito Flash^™ using our API. If you can't meet all the PCI Data Security Standards requirements, we recommend you to refer to our PagBrasil.JS documentation.

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.

You will only use the API to capture a transaction that was previously authenticated using PagBrasil.JS. Please refer to the method doAuthenticate at the PagBrasil.JS documentation.

Request parameters:

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

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 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 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 next "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:

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) By default a transaction is shown on the customer's bank account 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.

i) The parameter address_state must be the official abbreviation used in Brazil. To prevent customer from entering an invalid state, please see the following table to create a select object (drop-down list).

j) Current accepted brands:

k) To test a successful Débito Flash^™ transaction, please use one of the sample debit cards (item 4.1.j) with the following CVV and expiration date:

CVV: 123
Expiration: 12/29

You may use whatever data you wish to complete the other sections (e.g. card holder, amount, etc). Charges to a sample debit 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.

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

4.2. Receiving the IPN with the authorization response

If your PagBrasil merchant account was opened before 2017, it may be configured to receive IPNs for all "/api/order/add" calls, which includes Débito Flash^™ even though it is a newer product. 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.

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