Integration
Before you begin
Make sure you have taken care of the following:
- Correct API endpoint
- Authorization header construction mechanism (our API explorer, SDKs, etc.)
- A way to send RESTful API calls (our API explorer, SDKs, etc.)
Using MyCheckout hosted payment pages
The fastest way to start accepting Banco do Brasil payments is to use the MyCheckout hosted payment pages. To implement this option, you only need to make a POST /v1/{merchantId}/hostedcheckouts API call with an order object containing amountOfMoney and customer objects.
The customer object requires at least a billingAddress object with a countryCode property for a basic checkout. Here's an example of a hostedcheckouts payload with the required parameters for a Banco do Brasil payment:
{
"hostedCheckoutSpecificInput": {
"locale": "es_ES",
},
"order": {
"amountOfMoney": {
"amount": "2250",
"currencyCode": "BRL"
},
"customer": {
"billingAddress": {
"city": "Salvador",
"countryCode": "BR",
"houseNumber": "95489732",
"stateCode": "BA",
"street": "River N943 W",
"zip": "41630010"
},
"contactDetails": {
"emailAddress": "steven.banks@worldline.com",
"mobilePhoneNumber": "9998887777"
},
"fiscalNumber": "30228350000",
"locale": "pt_BR",
"personalInformation": {
"name": {
"firstName": "Steven",
"surname": "Banks"
}
}
},
"references": {
"merchantReference": "SBRIT_2023-05-11_18:05:03"
},
"seller": {
"phoneNumber": "9998887777"
}
},
"redirectPaymentMethodSpecificInput": {
"paymentProductId": "6101",
"redirectionData": {
"returnUrl": "http://localhost/co/connectres.php"
}
}
}
This is an example of a hostedcheckouts response:
{
"RETURNMAC" : "afaec9e3-69fd-401e-9ca9-ecd70100b339",
"hostedCheckoutId" : "0645d129-5819-71ff-abb7-d2916ee1e9a2",
"merchantReference" : "SBRIT_2023-05-11_18:05:03",
"partialRedirectUrl" : "pay1.preprod.secured-by-ingenico.com/checkout/1039961335-0ca9da19d67443aba5f8c2df90c6efbc:0645d129-5819-71ff-abb7-d2916ee1e9a2:bb859258e34a4a5ea1c1036ef1e57715"
}From this response, the essential properties are hostedCheckoutId and partialRedirectUrl. The hostedCheckoutId can be used in subsequent API calls such as GET /v1/{merchantId}/hostedcheckouts/{hostedCheckoutId} which will allow you to retrieve the transaction details.
The partialRedirectUrl is used to create a URL you can redirect your customer to. By default, we configure every account with the subdomain payment so you can always link https://payment. with the partialRedirectUrl, which will result in a full URL such as:
When the customer is redirected to this URL, they'll be shown the bank details and the reference they need to provide for the bank transfer. Performing redirect in the pre-production environment will lead the customer to a bank simulator page such as this:
The hostedCheckoutId is only valid for 2 hours. If you want to retrieve data after more than 2 hours, then use the hostedCheckoutId while it's still valid to call the GET /v1/{merchantId}/hostedcheckouts/{hostedCheckoutId} API request and store the createdPaymentOutput.payment.Id value from the response. The paymentId can be used at any time in GET /v1/{merchantId}/payments/{paymentId} API call to request the latest payment status.
We'll also send a Webhooks event containing the paymentId if you have this feature configured for your account.
Using your own checkout page
A second option for accepting Banco do Brasil payments is using your own checkout pages with our Server API — it gives you access to all our functionality if you need more control over the payment process and customization options. We provide our SDKs in multiple programming languages to help you build your integration (or you can integrate our API from scratch).
After the customer has chosen to pay with Banco do Brasil, you need to perform a POST /v1/{merchantId}/payments API call. In this case, the payload requires the same order object as described above in the MyCheckout example and a redirectPaymentMethodSpecificInput object containing paymentProductId property and a redirectionData object. The redirectionData object needs to include a returnUrl property. This will result in the following payload:
{
"order": {
"amountOfMoney": {
"amount": "2250",
"currencyCode": "BRL"
}
"customer": {
"billingAddress": {
"city": "Salvador",
"countryCode": "BR",
"houseNumber": "95489732",
"stateCode": "BA",
"street": "River N943 W",
"zip": "41630010"
}
"contactDetails": {
"emailAddress": "steven.banks@worldline.com",
"mobilePhoneNumber": "9998887777"
}
"fiscalNumber": "30228350000",
"locale": "pt_BR",
"personalInformation": {
"name": {
"firstName": "Steven",
"surname": "Banks"
}
}
}
"references": {
"merchantReference": "SBRIT_2023-05-10_16:55:25"
}
"seller": {
"phoneNumber": "9998887777"
}
}
"redirectPaymentMethodSpecificInput": {
"paymentProductId": "6101",
"redirectionData": {
"returnUrl": "http://localhost/co/connectres.php"
}
}
}
}This will return a response like this:
{
"creationOutput" : {},
"merchantAction" : {
"redirectData" : {
"redirectURL" : "https://sandbox.ebanx.com/ws/directtefredirect/?hash=645bb05fa3b15c218061299ed8c379925e036eebca5a6bc8",
"RETURNMAC" : "e737b3e9-9255-4044-9542-2fd3fe843193"
},
"actionType" : "REDIRECT"
},
"payment" : {
"statusOutput" : {
"isRefundable" : 0,
"isCancellable" : 0
},
"status" : "REDIRECTED",
"paymentOutput" : {
"paymentMethod" : "redirect",
"amountOfMoney" : {
"currencyCode" : "BRL",
"amount" : 2250
},
"redirectPaymentMethodSpecificOutput" : {
"paymentProductId" : 6101
},
"references" : {
"merchantReference" : "SBRIT_2023-05-10_16:55:25"
}
},
"id" : "4401156658"
}
}Customer Bank Redirect
If you use POST /v1/{merchantId}/payments, you'll also need to redirect customers to their bank to confirm the payment (which we automatically handle for you as a part of MyCheckout hosted payment pages).
The response contains a merchantAction object. There are various actionType values, but in the case of Banco do Brasil, we always return the actionType value as REDIRECT. This is accompanied by a redirectData property that contains a redirectURL and RETURNMAC property.
Remember that the merchantAction is only returned in response to POST /v1/{merchantId}/payments.
You'll need to redirect your customer's browser to the URL in redirectURL. In the pre-production environment, the redirect will happen to a bank simulator page, as shown in MyCheckout hosted payment pages example above.
After the customer has completed (or cancelled) the payment, the bank will redirect them back to the URL specified in the returnUrl property in the original payment request, which in the above example is http://localhost/co/connectres.php. The URL will be called with a GET, and at least two parameters will be added:
- paymentId - can be used in a call to GET /v1/{merchantId}/payments/{paymentId} to confirm your payment status and display it to the customer
- RETURNMAC - provided as a security measure to compare this value with the one from the merchantAction in response to your original payment request
Here is an example response for such a payments request:
{
"id": "4401157391",
"paymentOutput": {
"amountOfMoney": {
"amount": "2250",
"currencyCode": "BRL"
}
"paymentMethod": "redirect",
"redirectPaymentMethodSpecificOutput": {
"paymentProductId": "6101"
}
"references": {
"merchantReference": "SBRIT_2023-05-11_17:43:31"
}
}
"status": "CAPTURED",
"statusOutput": {
"isCancellable": "0",
"isRefundable": "1"
}
}Refunds
If you wish to refund a payment, you need to perform a POST /v1/{merchantId}/payments/{paymentId}/refund API call, which is only possible if the status is PAID. You can refund any amount equal to or lower than the captured amount. Also, you can make further refund API calls until the total sum of all refunds equals the captured amount. A basic refund payload only requires the amountOfMoney object specifying the amount and currencyCode:
{
"amountOfMoney": {
"amount": 25,
"currencyCode": "SEK"
}
}If you wish to see the details of your refund, use the GET /v1/{merchantId}/refunds/{refundId} API call.
Next Process flows