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:

Payout General Onboarding

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	Request a max of 1000 payouts in the same batch. Request a batch of a single payout. Inform your batch in JSON data format. Interact to a REST API.
Currency Conversion	Payout from (BRL, EUR and USD) to BRL. SOON
Accountable Flow	Get notified about status change of every batch. Consult requested batches and payouts.
Payee Support	Provide PagBank accounts in Brazil allowing Payees to claim their money.
Sandbox API	Test common use case scenarios in a safe mock domain, apart from production.

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	Consult	The request has succeeded. Resource is available in the Response Body.
204	Create	The request has succeeded. Body message is not needed.
400	Create Consult	The request could not be read because is malformed.
401	Create Consult	The request has not been applied because it lacks valid authentication credentials for the target resource.
403	Create Consult	The server understood the request but refuses to authorize it.
404	Create Consult	The requested endpoint is invalid or unknown.
409	Create Consult	The request conflicted with current state of the server.
413	Create	The server is refusing to process a request because the request payload is larger than the server is willing or able to process.
429	Create Consult	The user has sent too many requests in a given amount of time ("rate limiting").
500	Create Consult	The server encountered an unexpected condition that prevented it from fulfilling the request.
504	Create	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
  }
}