Boleto Bancario
Boleto Bancario is a voucher-based payment method used in Brazil. Customers can pay for vouchers in various ways, including cash, online and at ATMs.
The Paysafe Payments API supports Boleto Bancario via SafetyPay as a Payment Instrument for iGaming and Crypto merchants in Brazil.
Features
Boleto Bancario:
- Allows you to accept payments from unbanked customers.
-
Has no chargebacks risks.
-
Expires if not paid by the Boleto expiration date - if Boleto is not paid in the appropriate time it expires and the transaction is cancelled.
-
Is one of the most popular payment methods in Brazil.
Setup Requirements
To create accounts in both the sandbox and production environments:
- Send your details to it_integrations@safetypay.com
You will receive access to a Portal where you will be able to access the following keys:- Merchant Secret Key
- Merchant Signature Key
- Share these details with us to create your API Key - you will use this API key in your API calls.
Your account manager will help to guide you through this process.
Certification Requirements
You are required to go through a certification process to support Safetypay Express as a payment method.
The Paysafe integration team will share the certification requirements with you.
Transaction Types
Paysafe supports the following transaction type:
- Payments - used to transfer money from a customer's bank account to your merchant account. After successful payment, you credit the customer's wallet.
Minimum amount: No minimum amount
Maximum amount: BRL 57,000
Processing currency: BRL
Settlement currency: USD
Payments Flow Diagram
Typical Scenarios
To process a payment request using Boleto Bancario as the payment type:
-
Create a Payment Handle with the following parameter settings:
transactionType: PAYMENT
paymentType: BOLETO_BANCARIO -
Redirect the customer to the SafetyPay redirect URL so that they can generate a payment code.
The status of the Payment Handle will change to PAYABLE - you will be notified of this status change via your configured webhooks. -
Use the paymentHandleToken returned in the response to process the Payment request.
The payment will have a status of PROCESSING until the customer has made the payment.
You will receive a Payment Completed notification via webhooks when the customer successfully completes the payment.
If you don't receive webhooks, you can use a GET call to query the transaction status. However, we recommend that you avoid constant polling of the API.
See Webhooks and GET calls for more information.
Return links
- After the customer has been redirected to SafetyPay Express, you will receive a Payment Handle Payable webhook. When you make a /payments call, you will get a payment status of either Processing, Completed or Failed.
- After the customer completes the transaction at Safetypay Express, the customer will be redirected to your return link. You can check the status of the /payments response and redirect the customer to your relevant page depending on the payment status:
| Payment status | Description |
|---|---|
| PROCESSING | The transaction is not complete and is in progress. It does not mean that the transaction has failed. You will get a COMPLETED or FAILED webhook for this transaction at a later stage when you will be able to update the transaction status at your end. |
| COMPLETED | The customer has successfully completed the transaction at the SafetyPay end. |
| FAILED | The payment has expired at the SafetyPay end. |
APIs to use
Code Examples
Payment Handle request
Payment Handle Creation request for a Boleto Bancario payment:
{
"amount": 500,
"currencyCode": "BRL",
"merchantRefNum": "eb3b3cbe-1386-4c38-b967-63a90249e946",
"transactionType": "PAYMENT",
"paymentExpiryMinutes":15,
"accountId": "1002622940",
"paymentType": "BOLETO_BANCARIO",
"profile": {
"email": "brlspcash@gmail.com"
},
"returnLinks": [
{
"rel": "default",
"href": "http://www.amazon.ca"
}
]
}
Payment Handle response
Response to a Payment Handle creation request:
{
"id": "be8b6064-2bf2-4e4b-88e8-ed1b6a37e1fd",
"paymentType": "BOLETO_BANCARIO",
"paymentHandleToken": "PHxTXOEU9AAOErZc",
"merchantRefNum": "6708dd07-088d-4e63-a928-f2971ed07962",
"currencyCode": "BRL",
"txnTime": "2023-03-14T05:22:09Z",
"customerIp": "213.208.158.220",
"status": "INITIATED",
"links": [
{
"rel": "redirect_payment",
"href": "https://api.test.paysafe.com/alternatepayments/v1/redirect?accountId=1002622940&paymentHandleId=be8b6064-2bf2-4e4b-88e8-ed1b6a37e1fd&token=eyJhbGciOiJIUzI1NiJ9.eyJhY2QiOiIxMDAyNjIyOTQwIiwicHlkIjoiYmU4YjYwNjQtMmJmMi00ZTRiLTg4ZTgtZWQxYjZhMzdlMWZkIiwiZXhwIjoxNjc4NzczMTMwfQ.4dVPogQVZR62bhFCeNe5Gu-yRBiGxRKmkfUsgyrWU1k"
}
],
"liveMode": false,
"simulator": "EXTERNAL",
"usage": "SINGLE_USE",
"action": "REDIRECT",
"executionMode": "SYNCHRONOUS",
"amount": 500,
"timeToLiveSeconds": 898,
"gatewayResponse": {
"operationId": "0123073466306406",
"id": "8cf7e476-e5c8-4fa3-bb8e-c1048ae61f36",
"processor": "SAFETYPAY"
},
"returnLinks": [
{
"rel": "default",
"href": "http://www.amazon.ca"
}
],
"transactionType": "PAYMENT",
"gatewayReconciliationId": "8cf7e476-e5c8-4fa3-bb8e-c1048ae61f36",
"updatedTime": "2023-03-14T05:22:10Z",
"statusTime": "2023-03-14T05:22:10Z",
"paymentExpiryMinutes":15,
"profile": {
"email": "brlspcash@gmail.com"
}
}
Payment request
Boleto Bancario payment request using the paymentHandleToken received in the Payment Handle response:
{
"merchantRefNum": "4e3147e3-2bc0-4b9c-a43c-acf8d8b0e121",
"amount": 500,
"currencyCode": "BRL",
"dupCheck": true,
"settleWithAuth": true,
"paymentHandleToken": "PHxTXOEU9AAOErZc"
}
Payment response
Response to a Boleto Bancario payment request:
{
"id": "7d6d80d3-c56d-4dad-bd9c-0b5f88ddb169",
"paymentType": "BOLETO_BANCARIO",
"paymentHandleToken": "PHxTXOEU9AAOErZc",
"merchantRefNum": "3a0a62ed-78d3-44ac-8596-d009e51e7f92",
"currencyCode": "BRL",
"settleWithAuth": true,
"dupCheck": true,
"txnTime": "2023-03-14T05:22:09Z",
"customerIp": "213.208.158.220",
"status": "PROCESSING",
"gatewayReconciliationId": "8cf7e476-e5c8-4fa3-bb8e-c1048ae61f36",
"amount": 500,
"availableToRefund": 0,
"consumerIp": "213.208.158.220",
"liveMode": false,
"simulator": "EXTERNAL",
"updatedTime": "2023-03-14T05:23:18Z",
"statusTime": "2023-03-14T05:23:18Z",
"gatewayResponse": {
"operationId": "0123073466306406",
"id": "8cf7e476-e5c8-4fa3-bb8e-c1048ae61f36",
"processor": "SAFETYPAY",
"status": "101"
},
"availableToSettle": 0,
"profile": {
"email": "brlspcash@gmail.com"
},
"settlements": {
"amount": 500,
"txnTime": "2023-03-14T05:22:09.000+0000",
"availableToRefund": 0,
"merchantRefNum": "3a0a62ed-78d3-44ac-8596-d009e51e7f92",
"id": "7d6d80d3-c56d-4dad-bd9c-0b5f88ddb169",
"status": "PROCESSING"
}
}
Testing Instructions
| Country | currencyCode | countryCode | Instructions |
|---|---|---|---|
| Brazil | BRL | BR | On the SafetyPay Express page:
|