Overview
BoaCompra Payout Engine is a simple, fast and efficient outbound payment solution for businesses in need of performing mass transfers to multiple payees in Brazil. It’s a convenient way to manage the complexity, conversions, fees and compliance requirements. This documentation is designed to provide clear information about our solution.
Payout General Flow
- Call BoaCompra API requesting payouts.
- The API validates your request and processes the payout.
- The payment is available to the recipient in a PagBank digital bank account and in local currency. The recipient can log in to their PagBank account to claim their money.
Payee Onboarding
The flow below details how to open a PagBank account. It’s easy, fast, and only takes 3 minutes:
- To start, download the app "PagBank - PagSeguro" in your phone’s app store and click on create an account.
- Enter the cell phone number and then receives the token as an SMS.
- Enter your data, create a password and confirm your email.
- Send the photo of your requested document and that’s it, just wait for validation and your account is open.
Features and Capabilities
Once integrated to the Engine. You get full access to its features and capabilities:
Robust API |
|
Currency Conversion |
|
Accountable Flow |
|
Payee Support |
|
Sandbox API |
|
API Reference
This section describes most definitions and patterns that Developers might need for a successful integration to BoaCompra API v1. In the following chart are shown important concept definitions for a fuller comprehension of this section.
Concept | Definition |
API | An application programming interface (API) allows third parties to use its application features. |
cURL | cURL is a computer software tool for transferring data using various network protocols. |
JSON | JSON (JavaScript Object Notation) is a lightweight data-interchange format. |
REST | Representational state transfer (REST) is a software architectural style for API Services. |
BATCH | Various Payouts in the same JSON Payload. |
Exchange Rate | Rate used for currency conversion from USD and EUR to BRL. | Payout | One Payment for one Payee. |
Payee | Person or Company that claims a Payout on PagBank. |
Merchant | How BoaCompra kindly name its integrated business partners. |
On-Boarding | Process that fixes a partnership between BoaCompra and Merchants. |
Sandbox | Safe mock domain, apart from production, proper for a smooth integration experience. |
Use Requirements
To Integrate to BoaCompra API, Merchants must provide some recurrent requirements:
Requirements | Use |
Authentication | A valid (api-key, secret-key) pair must be informed in Request Headers. A valid pair is acquired after a Merchant On-boarding. |
HTTP Connection | HTTP is the default protocol to connect to the API and access all Payout REST endpoints available in the API. |
JSON Payloads | JSON is the default API content-type. |
Unique Code References | Unique code references for every batch and every payout. Code references are further used for queries. |
Notification URL | URL for further notifications about batch status change. |
Payee Data | For each payout (payee Pagbank email, money amount and currency). |
Production Domain and Sandbox Domain
We are providing two domains so developers can have a safe and smooth integration experience to BoaCompra API
Domain | URL | Purpose |
Production | https://api.boacompra.com/payouts | Send payouts. |
Sandbox | https://api.sandbox.boacompra.com/payouts | Test endpoint use case scenarios. |
Every section ahead present definitions or patterns that are valid for both domains. However, you can find few sections describing how to test specific use cases scenarios in Sandbox Do-main. We will call it Sandbox Hint. You can see one below.
Sandbox Hint # 00 - Example
That is just an example of Sandbox Hint title that you will find ahead. Keep reading.
Payout Request Headers
These headers are present in every Request.
Headers (Case-Sensitive) | Value |
Content-Type | application/json |
Authorization | {Authorization} |
X-Api-Version | v1 |
Generating an Authorization Header
BoaCompra Payout’s API uses the Basic Authentication aproach. That means the client has to send the HTTP requests with the Authorization header. The Authorization header must contain the word Basic followed by a space and a base64-encoded string api-key:secret-key. For exemple:
Authorization: Basic YXBpLWtleTpzZWNyZXQta2V5
Because base64 is easily decoded BoaCompra Payout’s API only accepts request through HTTPS/SSL. Once Merchant’s On-boarding is concluded, Merchant’s Developers will have a credential pair (api-key and secret-key) to use in the requests. It is important to notice that once the credential pair is known by someone, it will be possible to create payout transaction with BoaCompra. Be sure that you keep the credential pair (api-key and secret-key) in a safe and private place. Do not share it in client-side application or public repositories. The code snippet below shows an Authorization header’s exemple generated in PHP:
<?php
$key = "3588f0e6653448a5b1c2be1e77bef2d7";
$secret = "041dfc2528904178a3d9a19dff5cb8a0";
$encoded = base64_encode(sprintf("%s:%s", $key, $secret));
$header = sprintf("Authorization: Basic %s", $encoded);
echo $header;
// Authorization: Basic MzU4OGYwZTYtNjUzNC00OGE1LWIxYzItYmUxZTc3YmVmMmQ3OjA0M-WRmYzI1Mjg5MDQxNzhhM2Q5YTE5ZGZmNWNiOGEw
Payout Expected Responses HTTP Codes
HTTP Code | Features | What Happened? |
200 |
|
The request has succeeded. Resource is available in the Response Body. |
204 |
|
The request has succeeded. Body message is not needed. |
400 |
|
The request could not be read because is malformed. |
401 |
|
The request has not been applied because it lacks valid authentication credentials for the target resource. |
403 |
|
The server understood the request but refuses to authorize it. |
404 |
|
The requested endpoint is invalid or unknown. |
409 |
|
The request conflicted with current state of the server. |
413 |
|
The server is refusing to process a request because the request payload is larger than the server is willing or able to process. |
429 |
|
The user has sent too many requests in a given amount of time ("rate limiting"). |
500 |
|
The server encountered an unexpected condition that prevented it from fulfilling the request. |
504 |
|
The server, while acting as a gateway or proxy, did not receive a timely response from an upstream server it needed to access in order to complete the request. |
Payout Paths
Paths | Feature | HTTP Verb |
/payouts | Create Batch | POST |
/payouts/{batch-reference}/items | Consult Items of a Batch | GET |
Create Batch of Payout and Receive Notification
POST/payouts
Below, there is an example of cURL request for batch creation. If this request finish on success, it shall get a Response with HTTP Code 204 (Success with empty body!).
# Create Batch of Payouts cURL Request Sample.
curl --location --request POST 'https://api.boacompra.com/payouts' \
--header 'Content-Type: application/json' \
--header 'Authorization: {Authorization}' \
--header 'X-Api-Version: {X-Api-Version}' \
--data-raw "{
'reference':'17c98da1-4555-44a3-ac34-66c9ccefcfe8',
'notification_url':'https://merchant.com/boacompra',
'items':[
{
'reference':'120c75a5-c2c3-4f43-bac8-22f5432b1969',
'country':'BR',
'method':'PAGBANK',
'amount':{
'value':40.4,
'currency':'BRL'
},
'destination':{
'email':'lara.neves@uolinc.com'
}
}
]
}"
Param type|size |
Description |
reference string|max 64 |
Unique Reference for a Batch. It must be generated and informed by the Merchant. Accepts alphanumeric and hyphen. |
notification_url string|max 200 |
URL for further notifications. |
items string|max 1000 |
Array of items containing every payout of one batch. |
items[].reference string|max 64 |
Unique Reference for one Payout. It must be generated and informed by the Merchant. Accepts alphanumeric and hyphen. |
items[].method string|enum |
Payment Method. Enum Values are (PAGBANK). |
items[].country string|enum |
Payee Payout Destination Country. Enum values are ISO 3166 Standard (BR). |
items[].destination.email string|max 60 |
Email that identifies a Payout to be claimed by its Payee. |
items[].amount.value float|max 5000 BRL |
Money Value for certain Payee. |
items[].amount.currency string|enum |
Merchant Currency of one Payout. Enum values are ISO 4217 Standard (BRL). |
Receive a Notification
A notification_url is informed in the batch creation. It is described below how it is used by the Payout Engine. When every item in the batch reach a final status, FAILED or SUCCESS, the batch status is changed to COMPLETED and Payout Engine makes a maximum of 7 sequential attempts to notify Merchant’s domain in the notification_url. On first success, Payout Engine gets a Response with HTTP Code 204 and doesn’t go for more attempts. Retry intervals are shown below in minutes.
Attempt | Caused By | Retry Interval |
1 | The batch status is changed to COMPLETED and Payout Engine must notify Merchant’s domain. | After 10 minutes. |
2 | Notification Response got HTTP Code different from 204. | After 10 minutes. |
3 | Notification Response got HTTP Code different from 204. | After 10 minutes. |
4 | Notification Response got HTTP Code different from 204. | After 60 minutes. |
5 | Notification Response got HTTP Code different from 204. | After 60 minutes. |
6 | Notification Response got HTTP Code different from 204. | After 60 minutes. |
7 | Notification Response got HTTP Code different from 204. | No more attempts. |
Below, cURL request of one notification attempt.
curl --location --request POST 'https://merchant.com.br/boacompra' \
--header 'Content-Type: application/json' \
--data-raw "{
'notification_type': 'payout',
'reference': '{batch-reference}'
}"
Consult Items of a Batch
GET /payouts/{batch_reference}/items?page={number}&page_size={number}
Param type|size |
Description |
batch_reference string|max 64 | min 1 |
Unique Reference for a Batch. It was generated and informed by the Merchant on creation. Accepts alphanumeric and especial characters. |
page number |
A number from 1 to 1000 selecting a page to be shown. It has a default value of 1 if not informed. |
page_size number |
A number from 1 to 100 describing the number of items in result. It has a default value of 100 if not informed. |
After creating a Batch of Payouts, it is natural to consult.
curl --location --request GET 'https://api.boacompra.com/payouts/{batch_reference}/items?page={number}&page_size={number}' \
--header 'Content-Type: application/json' \
--header 'Authorization: {Authorization}' \
--header 'X-Api-Version: {X-Api-Version}'
Below, you can see how the response payload looks like when consulting items of a batch.
// Response for HTTP code 200
{
"result":[
{
"status":{
"code":"SUCCESS",
"reason":""
},
"reference":"120c75a5-c2c3-4f43-bac8-22f5432b1969",
"country":"BR",
"method":"PAGBANK",
"amount":{
"value":210.5,
"currency":"BRL"
},
"exchange":{
"base":"BRL",
"rate":1
},
"destination":{
"email":"lara.neves@uolinc.com",
"amount":{
"value":210.5,
"currency":"BRL"
}
},
"created_at":"2014-01-27T10:17:00Z",
"updated_at":"2014-01-27T10:17:00Z"
},
{
"status":{
"code":"FAILED",
"reason":"INVALID_DESTINATION"
},
"reference":"220475a5-1dc3-w343-cad9-33D2433b2969",
"country":"BR",
"method":"PAGBANK",
"amount":{
"value":80.76,
"currency":"BRL"
},
"exchange":{
"base":"BRL",
"rate":1
},
"destination":{
"email":"jose.aparecido@uolinc.com",
"amount":{
"value":80.76,
"currency":"BRL"
}
},
"created_at":"2014-01-27T10:17:00Z",
"updated_at":"2014-01-27T10:17:00Z"
}
],
"pagination":{
"total_items":100,
"total_pages":50
}
}
Sandbox Hint # 01 - Item Status Testing
All possible status that can be found in one payout item are listed below.
result[].status.code | result[].status.reason | Description |
FAILED | INVALID_DESTINATION | Item was received and could not be processed. Destination account has a problem. |
FAILED | PROCESSING_ERROR | Item was received and could not be processed. Generic error. |
PENDING | Item was received and will process soon. | |
SUCCESS | Item was received and processed. |
To test for all final possible values of result[].status.code and result[].status.reason.
#01. Step 1. Will be necessary the creation of a batch of payouts in Sandbox Domain using some special emails for each status. If the cURL request is well formed, it shall get a Response with HTTP Code 204 (Success with empty body!).
curl --location --request POST 'https://api.sandbox.boacompra.com/payouts' \
--header 'Content-Type: application/json' \
--header 'Authorization: {Authorization}' \
--header 'X-Api-Version: {X-Api-Version}' \
--data-raw "{
'reference':'17c98da1-4555-44a3-ac34-66c9ccefcfe8',
'notification_url':'https://merchant.com/boacompra',
'items':[
{
'reference':'220475a5-1dc3-w343-cad9-33D2433b2969',
'country':'BR',
'method':'PAGBANK',
'amount':{
'value':33.7,
'currency':'BRL'
},
'destination':{
'email':'payouts-invalid-destination@boacompra.com'
}
},
{
'reference':'120c75a5-c2c3-4f43-bac8-22f5432b1969',
'country':'BR',
'method':'PAGBANK',
'amount':{
'value':40.4,
'currency':'BRL'
},
'destination':{
'email':'payouts-processing-error@boacompra.com
}
}
},
{
'reference':'120475a5-w343-4f43-c2c3-22f533D241969',
'country':'BR',
'method':'PAGBANK',
'amount':{
'value':78.2,
'currency':'BRL'
},
'destination':{
'email':'lara.neves@uolinc.com'
}
}
]
}"
#01. Step 2. Consulting the just created batch
url --location --request GET 'https://api.sandbox.boacompra.com/payouts/17c98da1-4555-44a3-ac34-66c9ccefcfe8/items?page=1&page_size=3' \
--header 'Content-Type: application/json' \
--header 'Authorization: {Authorization}' \
--header 'X-Api-Version: {X-Api-Version}'
It is possible to notice that each one of these special e-mails produces a respective final state for the item following the logic bellow.
result[].destination.email | result[].status.code | result[].status.reason |
payouts-invalid-destination@boacompra.com | FAILED | INVALID_DESTINATION |
payouts-processing-error@boacompra.com | FAILED | PROCESSING_ERROR |
Any common email like lara.neves@uolinc.com | SUCCESS |
Therefore, Consult response payload might be like.
// Response for HTTP code 200
{
"result":[
{
"status":{
"code":"FAILED",
"reason":"INVALID_DESTINATION"
},
"reference":"220475a5-1dc3-w343-cad9-33D2433b2969",
"country":"BR",
"method":"PAGBANK",
"amount":{
"value":33.7,
"currency":"BRL"
},
"exchange":{
"base":"BRL",
"rate":1
},
"destination":{
"email":"payouts-invalid-destination@boacompra.com",
"amount":{
"value":33.7,
"currency":"BRL"
}
},
"created_at":"2014-01-27T10:17:00Z",
"updated_at":"2014-01-27T10:17:00Z"
},
{
"status":{
"code":"FAILED",
"reason":"PROCESSING_ERROR"
},
"reference":"120c75a5-c2c3-4f43-bac8-22f5432b1969",
"country":"BR",
"method":"PAGBANK",
"amount":{
"value":40.4,
"currency":"BRL"
},
"exchange":{
"base":"BRL",
"rate":1
},
"destination":{
"email":"payouts-processing-error@boacompra.com",
"amount":{
"value":40.4,
"currency":"BRL"
}
},
"created_at":"2014-01-27T10:17:00Z",
"updated_at":"2014-01-27T10:17:00Z"
},
{
"status":{
"code":"FAILED",
"reason":"PROCESSING_ERROR"
},
"reference":"120475a5-w343-4f43-c2c3-22f533D241969",
"country":"BR",
"method":"PAGBANK",
"amount":{
"value":78.2,
"currency":"BRL"
},
"destination":{
"email":"lara.neves@uolinc.com",
"amount":{
"value":78.2,
"currency":"BRL"
}
},
"created_at":"2014-01-27T10:17:00Z",
"updated_at":"2014-01-27T10:17:00Z"
}
],
"pagination":{
"total_items":3,
"total_pages":1
}
}
Download Payout CSV Report
GET /payouts/reports/bases/{date}
This endpoint search for a CSV Report of all payouts on status FAILED and SUCCESS for an exact date. Also, it contains columns for invoice data and all date-time columns are UTC+0.
Param Type | Size |
Description |
date string | max 8 | min 8 |
Unique Reference for a Report. It has the format that follows (YYYYMMDD). Examples:
|
curl --location --request GET 'https://api.boacompra.com/payouts/reports/bases/20201010' \
--header 'X-Api-Version: v1' \
--header 'Authorization: {Authorization}'
To use this feature it is necessary to enable the "follow redirect" of the HTTP client.
Sandbox Hint #02 - CSV Report Example
There is an example in sandbox, a mock report for the date 20200511, other might return 404.
curl --location --request GET 'https://api.sandbox.boacompra.com/payouts/reports/bases/20200511' \
--header 'Content-Type: application/json' \
--header 'Authorization: {Authorization}' \
--header 'X-Api-Version: {X-Api-Version}'
The content returned might be this:
CREATED;UPDATED;BATCH REFERENCE;ITEM REFERENCE;COUNTRY;METHOD;STATUS;IOF LIABILITY;SOURCE CURRENCY;SOURCE AMOUNT;PAYOUT AMOUNT BRL;BOACOMPRA FEE;BOACOMPRA FEE BRL;IOF VALUE BRL;TOTAL INVOICED BRL;PAYOUT AMOUNT USD;BOACOMPRA FEE USD;IOF VALUE USD;TOTAL INVOICEED USD;EXCHANGE CURRENCIES;EXCHANGE RATE DATE;BASE EXCHANGE RATE;EXCHANGE COST;FINAL EXCHANGE RATE 2020-05-11T10:31:53Z;2020-05-11T10:32:47Z;24d076b5-411d-4306-8f9c-a374c3ccacff;ABC-4;BR;PAGBANK;SUCCESS;MERCHANT;BRL;0.1;0.1;1%;0.001;0.0004;0.1014;0.002;0;0;0.002;BRL-USD;1;0.02;0;0.02 2020-05-11T10:37:39Z;2020-05-11T10:37:43Z;8d1cfdd9-0e50-4d11-bbb4-e8b3c44d52f0;ABC-4;BR;PAGBANK;FAILED;MERCHANT;BRL;0.1;0;-;0;0;0;0;0;0;0;-;-;0;0;0 2020-05-11T02:44:00Z;2020-05-11T02:45:31Z;c9d00028-5ef4-478b-be5c-c6de1e203782;ABC-6;BR;PAGBANK;SUCCESS;MERCHANT;BRL;0.1;0.1;1%;0.001;0.0004;0.1014;0.002;0;0;0.002;BRL-USD;1;0.02;0;0.02 2020-05-11T02:56:18Z;2020-05-11T02:56:21Z;58856af7-1cdb-4e01-914e-cb1752e8868c;ABC-7;BR;PAGBANK;FAILED;MERCHANT;BRL;0.1;0;-;0;0;0;0;0;0;0;-;-;0;0;0 2020-05-11T04:02:01Z;2020-05-11T04:03:03Z;9e8e48e1-00e4-48f1-8df2-2d9c58b38127;ABC-8;BR;PAGBANK;SUCCESS;MERCHANT;BRL;0.2;0.2;1%;0.002;0.0008;0.2028;0.004;0;0;0.004;BRL-USD;1;0.02;0;0.02 2020-05-11T04:06:03Z;2020-05-11T04:06:06Z;601cbe0d-9d3b-4ac4-a763-410849c0cf50;ABC-10;BR;PAGBANK;FAILED;MERCHANT;BRL;0.3;0;-;0;0;0;0;0;0;0;-;-;0;0;0 2020-05-11T04:35:51Z;2020-05-11T04:36:27Z;c58b790b-b0ad-4731-8777-87811148f0bd;ABC-11;BR;PAGBANK;SUCCESS;MERCHANT;BRL;0.3;0.3;1%;0.003;0.0011;0.3041;0.006;0.0001;0;0.0061;BRL-USD;1;0.02;0;0.02