Accept Boleto payments in your online store.
Boleto Bancário, commonly known as Boleto, is a payment method used in Brazil. It allows customers to pay for goods and services by generating a bank slip, which can be paid at a bank, post office, or online banking. Boleto is popular among customers who do not have a credit card or prefer to pay with cash. Use the emerchantpay API to accept Boleto as a payment method across the supported emerchantpay’s payment integrations.
To proceed with this solution, you must have an emerchantpay merchant account. Apply for a merchant account by filling out and submitting this contact form.You will be assigned an emerchantpay Account Manager, who will provide you with credentials and assist you with any of emerchantpay’s payment solutions.
To submit a payment using Boleto, create a payment request to the emerchantpay Genesis payment gateway. Specify boleto as the
Example of passing a Boleto transaction request:
<?xml version=”1.0″ encoding=”UTF-8″?> <payment_transaction> <transaction_type>boleto</transaction_type> <transaction_id>119643250547501c79d8295</transaction_id> <usage>40208 concert tickets</usage> <remote_ip>245.253.2.12</remote_ip> <return_success_url>http://www.example.com/success</return_success_url> <return_failure_url>http://www.example.com/failure</return_failure_url> <amount>100</amount> <currency>USD</currency> <consumer_reference>barney_rubble</consumer_reference> <national_id>8812128812</national_id> <birth_date>30-12-1992</birth_date> <customer_email>firstname.lastname@example.org</customer_email> <billing_address> <first_name>Barney</first_name> <last_name>Rubble</last_name> <address1>14, Nerazdelni str</address1> <zip_code>1407</zip_code> <city>Rio de Janeiro</city> <country>BR</country> </billing_address> <risk_params> <user_id>123456</user_id> </risk_params> </payment_transaction>’
You will receive a Success or Error response to your payment request.
Example of a Success response:
<?xml version=”1.0″ encoding=”UTF-8″?> <payment_response> <transaction_type>boleto</transaction_type> <status>pending_async</status> <mode>live</mode> <transaction_id>119643250547501c79d8295</transaction_id> <unique_id>44177a21403427eb96664a6d7e5d5d48</unique_id> <technical_message>Transaction successful!</technical_message> <message>Transaction successful!</message> <redirect_url>https://staging.gate.emerchantpay.net/redirect/to_acquirer/649e1ff35c61</redirect_url> <timestamp>2023-03-06T16:33:10Z</timestamp> <descriptor>Descriptor one</descriptor> <amount>100</amount> <currency>USD</currency> <sent_to_acquirer>true</sent_to_acquirer> <barcode>03395929800000015009008773800000000000270101</barcode> <ticket_expiry_date>04052022</ticket_expiry_date> <digitable_line>03399008707380000000900004301016489750000019000</digitable_line> </payment_response> <
redirect_urlto redirect your customer to authorise the payment with Boleto. See the emerchantpay API for the complete list of Boleto response parameters and code samples.
Because the Boleto payment transaction is asynchronous, the result of your customer’s payment is sent as a separate HTTP POST notification from the gateway to the
notification_url that you supplied with the transaction request.
“transaction_id”: “f44f2856b5d933c04f42d1e922e30cbf” “terminal_token”: “871bbbd2f9ce1d58dead9848ef5a24ab59a8ee94” “unique_id”: “832eb553eba838f79113167cbc1002a1” “transaction_type”: “boleto” “status”: “approved” “signature”: “b74ed54d95589fce6f9d7a229b225fd4a925e9bc” “amount”: “1200” “funds_status”: “NOT_EXPECTED” “account_holder”: “John Smith” “bank_account_number”: “NL18ABNA0484869868” “bank_identifier_code”: “ABNANL2A”
statusfield provides you with information on the outcome of the transaction. See Transaction States for more information about transaction statuses.
signature field to verify that the notification has been sent by the Genesis gateway. Each session signature is generated by combining the
unique_id of the transaction and your API password, and generating a SHA-1 hash function of the combined string.
Notification signature examples:
signature = SHA-1 hash value of
After you have verified the notification state and validity, render an XML page containing the transaction’s unique id to acknowledge that you have received the notification.Example of a notification reply you use to confirm a notification:
<?xml version=”1.0″ encoding=”UTF-8″?> <notification_echo> <unique_id>3f760162ef57a829011e5e2379b3fa17</unique_id> </notification_echo>
Before you can accept live payments, you must test your integration in the emerchantpay staging environment.
- Add an item to your cart in your online store.
- Proceed to the checkout page and check out using Boleto.
- Follow the redirect link in the response.
- In the payment simulator, follow the instructions to simulate a transaction.
- Complete the order and verify that you are redirected to the order confirmation page.
- Log in to Genesis.
- In the navigation menu, go to Payment transactions.
- Verify that the transaction appears at the top of the list and is successful.
After you have successfully tested your Boleto integration, you are ready to move to the production environment and accept live payments. Contact your emerchantpay Account Manager to get your login credentials for the Genesis production environment.
You are now ready to accept live payments using Boleto.