NAV
  • Overview
  • API Reference
  • 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

    Payout General Flow

    1. Call BoaCompra API requesting payouts.
    2. The API validates your request and processes the payout.
    3. 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

    1. To start, download the app "PagBank - PagSeguro" in your phone’s app store and click on create an account.
    2. Enter the cell phone number and then receives the token as an SMS.
    3. Enter your data, create a password and confirm your email.
    4. 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
      }
    }