NAV Navbar
java php ruby python
  • Introduction
  • Sequence Flow
  • Test Environment
  • Sales Report Web Service
  • Technical Support
  • Introduction

    This manual aims to explain how UOL BoaCompra billing integration process works. Thus, an overview of the process will be presented, followed by its detailed technical explanation.

    This manual covers the checkout generation. For notification and payment confirmation, please refer to the transactions-api manual.

    Participants

    There are 3 participants in the billing process: The website of the partner (which will be referred hereafter as Merchant), the End User and UOL BoaCompra.


    Sequence Flow

    This is the sequence flow of the billing process among the participants. Each one of these steps will be further detailed.

    BoaCompra Payment Flow

    1- End User → Merchant: End User purchases products on the Virtual Store;

    2- Merchant → UOL BoaCompra: Virtual Store sends a payment request to UOL BoaCompra;

    3- UOL BoaCompra → End User: UOL BoaCompra offers the payment options to the End User;

    4- End User → UOL BoaCompra: End User chooses the payment method and finishes the purchase;

    Once the end user finishes the purchase, for every modification in the transaction status, UOL BoaCompra will notify the Merchant. Merchant must check the transaction status in order to deliver the product to the End User, according to the transaction status.

    Please refer to the transactions-api manual for full details.

    1. End User → Virtual Store

    End User purchases products on the Merchant, which stores the information of the order in its database, like: order number, items, total, currency, etc...

    2. Virtual Store → UOL BoaCompra

    Merchant sends a payment request to UOL BoaCompra. This request must be sent through a POST method to the URL:

    HTTP Method: POST

    Host: https://billing.boacompra.com/payment.php

    To accomplish PCI standards, UOL BoaCompra checkout protocol TLS 1.2. So all navigation in the checkout and request to BoaCompra APIs must be made using such protocol.

    The following parameters are required:

    Parameter Size Type Description
    store_id 6 Int Merchant Identification on UOL BoaCompra
    return 200 String URL used to redirect end users in successful transactions
    notify_url 200 String URL used to notify the Virtual Store. This URL must bind ports 80 or 443.
    currency_code 3 String Order currency ISO code
    order_id 30 String Order Identification on Merchant (This must be an unique value)
    order_description 200 String Short description of the order
    amount 7 Int Order's total amount. Separating cents by dot, with two decimal places
    client_email 60 String End user email
    hash_key - String HMAC_SHA256 between important parameters of the form and a Key defined by Merchant.


    Below is a source code sample in HTML that the Merchant can use to send the request to UOL BoaCompra.

    <body onload="document.billing.submit();">
          <form method="POST" name="billing" action="https://billing.boacompra.com/payment.php" >
            <input type="hidden" name="store_id" id="store_id" value="10">
            <input type="hidden" name="return" value="http://www.virtualstore.com/return.php">
            <input type="hidden" name="notify_url" value="http://www.virtualstore.com/notify.php">
            <input type="hidden" name="currency_code" id="currency_code" value="BRL">
            <input type="hidden" name="order_id" id="order_id" value="16598">
            <input type="hidden" name="order_description" value="Premium Account 3 months ">
            <input type="hidden" name="amount" id="amount" value="100.00">
            <input type="hidden" name="client_email" id="client_email" value="test@boacompra.com">
            <input type="hidden" name="hash_key" id="hash_key" value="ac87ffee901a1af2b24a6d05f617f152">
          </form>
    </body>
    
    

    store_id

    The “store_id” parameter is the Merchant identifier, registered in UOL BoaCompra system.

    return

    The “return” parameter must contain the complete URL that will be accessed by the End User after the purchase is completed.

    notify_url

    The “notify_url” parameter must contain the complete URL in which UOL BoaCompra will notify the Merchant about the order payment. It is the most important parameter in the payment request, once all the information exchanged between UOL BoaCompra and the Merchant about the order status will be made through this URL.

    currency_code

    The “currency_code” parameter must contain the order currency ISO code. For example: in case the total amount of the order made by the End User is R$ 10,00 (Brazilian reais), the “currency_code” parameter must contain the value “BRL”.

    The system accepts orders in the following currencies:

    ISO Code Currency
    ARS Peso (Argentina)
    BRL Real (Brazil)
    CLP Peso (Chile)
    COP Peso (Colombia)
    CRC Colón (Costa Rica)
    EUR Euro
    MXN Peso (Mexico)
    PEN Nuevos Soles (Peru)
    TRY Liras (Turkey)
    USD Dolar
    UYU Peso (Uruguai)


    “currency_code” sent in the request may not be related with the country of payment. The Merchant can start a transaction in a specific currency and the End User choose another one for the payment. Or the Merchant can choose a default currency, such as EUR or USD. In this case, the order total amount will be converted to the currency chosen by the End User. This conversion is transparent to the Merchant, and the value of the “currency_code” parameter will be listed in the sales report.

    order_id

    The “order_id” parameter must contain the order identifier on the Merchant system.

    order_description

    The “order_description” parameter must contain a brief description of the order. This description will be displayed to the End User.

    amount

    The “amount” parameter must contain the order total amount without commas. For example: considering a R$ 17,40 order (in Brazilian reais), the “amount” parameter must contain the value “1740” or “17.40”. The last two digits correspond to the decimal part of the value.

    client_email

    The “client_email” parameter must contain the email address of the End User. The communication between UOL BoaCompra and the End User will be made through this email address, so a valid email is required. If the Merchant can't send this parameter, the End User will have to fill it in UOL BoaCompra.

    hash_key

    The “hash_key” parameter is generated using the HMAC_SHA256 algorithm on the concatenation of the values of the following parameters (the order of parameters must be followed):

    order parameter
    1st store_id
    2nd notify_url
    3rd order_id
    4th amount
    5th currency_code
    6th key


    The “key” parameter is sent to the Merchant by UOL BoaCompra in the beginning of the integration. If you don’t have this key, please reach your Account Manager.

    To calculate the parameter “hash_key“, use this code

    final String data = "10" + "http://www.lojavirtual.com/notify.php" + "16598" + "1740" + "BRL";
    final String secretKey = "secret";
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(secretKey.getBytes("UTF8"), "HmacSHA256"));
    Hex.encodeHexString(mac.doFinal(data.getBytes("UTF-8")));
    
    $data = '10' . 'http://www.virtualstore.com/notify.php' . '16598' . '1740' . 'BRL';
    hash_hmac('sha256', $data, 'secret');
    
    data = '10' + 'http://www.virtualstore.com/notify.php' + '16598' + '1740' + 'BRL'
    secretKey = 'secret'
    digest = OpenSSL::Digest.new('sha256')
    hmac = OpenSSL::HMAC.digest(digest, secretKey, data)
    securityToken = Base64.encode64(hmac)
    
    # python v.2.7.13
    import hashlib
    import hmac
    import base64
    
    data = '10' + 'http://www.virtualstore.com/notify.php' + '16598' + '1740' + 'BRL'
    secret = 'secret'
    
    hash = hmac.new(secret, data, hashlib.sha256).hexdigest()
    
    # python v3
    import hashlib
    import hmac
    import base64
    
    data = b'10' + b'http://www.virtualstore.com/notify.php' + b'16598' + b'1740' + b'BRL'
    secret = b'secret'
    
    hash = hmac.new(secret, data, hashlib.sha256).hexdigest()
    

    Optional Parameters

    The following parameters are optional in the payment request:

    Parameter Size Type Description
    client_name 60 String End User name
    client_zip_code 8 Int End User postal code
    client_street 60 String End User address
    client_suburb 60 String End User suburb
    client_number 10 Int End User address number
    client_city 60 String End User city
    client_state 30 String End User state
    client_country 20 String End User country
    client_telephone 20 Int End User phone number
    language 5 String Default Language. Possible values are: - “pt_BR” for Brazilian Portuguese - “es_ES” for Spanish - “en_US” for English - “pt_PT” for Portugal Portuguese - “tr_TR” for Turkish
    country_payment 2 String ISO Code of the country from which the payment methods must be displayed without showing the country selection page to the End User. Accepted countries are available on Available Payments List
    project_id 6 Int Project Identifier. This parameter can be used to group checkouts by product, so the partner can check them separately.
    payment_id 6 Int Payment Identifier. This parameter is used to show a specific payment method to the final user.
    payment_group 20 String Payment group name. This parameter is used to show a specific group of payment methods to the End User.
    character 100 String Player/user login used in anti-fraud analysis (for gaming companies)
    test_mode 1 Int Parameter used to indicate that a transaction will be processed in test mode. Can be used the value “1” to test integration and “0” to production environment.
    mobile 1 Int Parameter used to indicate that a transaction will be processed in checkout web or mobile. Can be used the value “1” to mobile or “0” to web. Default is 0. Must be sent together with country_payment=BR.
    metadata - String Parameter used in anti-fraud analysis for gaming companies to collect player level, account id and gifting.


    If the “language” parameter is not sent, the language served in return will be selected according to the End User IP.

    If the “project_id” parameter is not sent, the default value will be “1”. If the parameter is sent, the project must be previously registered in the administrative panel and set to “active”. In the “Projects” menu is possible to create and edit projects. Project #1 is the default and can’t be set to “inactive”.

    If the parameter “payment_id” is not sent, all payment available to the Merchant will be displayed to the End User. This parameter must be sent along with the “country_payment” parameter. To use this parameter, see the identifier of each payment method on Available Payments List.

    As UOL BoaCompra provides anti-fraud analysis, extra information is required for some payment options, such as Credit Card or PayPal. This information can be pre-filled by sending the extra parameters described in the following table:

    Parameter Size Format Description
    client_name 60 String End User name
    client_city 60 String End User City
    client_state 30 String End User State
    client_country 20 String End User Country
    client_telephone 20 Int End User Phone Number
    client_cpf 20 String End User CPF (For Brazil only)


    The “metadata” parameter is optional. The values should be sent in JSON format

    {
      “player-level”: 1,
      “account-id”: 14525,
      “gifting”: true
    }
    


    “metadata” is specific for gaming companies and the possible values are:

    Parameter Size Type Description
    player-level 11 Int Player Level Number
    account-id 255 String End User Account ID
    gifting - Boolean If is Gift (true or false)

    If the parameter “payment_group” is not sent, all payments available to the Merchant will be displayed to the End User. This parameter must be sent along with the “country_payment” parameter. It is possible to send more than one group of payments by using commas (“,”) to separate them.

    To use this parameter, see the name of each group of payment methods in the following table:


    Group of Payments
    card
    transfer
    online wallet
    cash
    sms (Turkey only)


    The “test_mode” parameter is used to simulate the production environment during integration development.

    The “mobile” parameter is used to adapt checkout experience to mobile devices. Mobile checkout support only BRL currency, with payment methods credit card and PagSeguro E-wallet. This parameter must be send together with country_payment=BR.

    3. UOL BoaCompra → End User

    UOL BoaCompra processes the payment request sent by the Merchant and displays the available payment methods to the End User.

    4. End User → UOL BoaCompra

    The End User chooses the payment method, fills the required data and completes the purchase on UOL BoaCompra. In this step, UOL BoaCompra displays a confirmation screen and sends an email to the End User with all the order information and instructions to complete the payment, when necessary.

    The URL informed on the “return” parameter is then accessed by the End User, so he or she can see its order was completed on the Merchant.

    Important: After completing the payment integration, please refer to the Transaction API manual to be able to handle notifications and deliver the products properly.

    Test Environment

    A test environment is available to ease payment integration. To use it, please set the parameter “test_mode” to 1

    Transactions will be available in, under menu “Transactions Test” on http://billing-partner.boacompra.com

    To access partner’s area, a login and password are necessary.

    Sales Report Web Service

    Service provided by UOL BoaCompra to partners automatically download the daily and monthly reports. The reports contain the transactions delivered or refunded in a day or month. The monthly reports are available automatically by the system on first day of each month, but to get the daily reports, please contact your account manager. To download the report, some parameters need to be sent:

    Parameter Description
    year Year in YYYY format. Ex: 2014
    month Month in MM format. Ex: 08
    day Day in DD format. This parameter is optional. If it is sent, the daily report is returned. If it isn’t sent, the monthly report is returned. Ex: 21
    store_id Partner id. Ex: 123
    time Hour in timestamp format. Ex: 10:46:44 = 1412617604 time() function in php.
    hash HMAC_SHA256 cryptography of the following values concatenated: store_id, time e des_key. Ex: hash_hmac(‘sha256’, store_id+time+des_key, des_key)


    The “des_key” value is the key shared between partner and UOL BoaCompra.

    Those parameters should be sent using GET method to the url https://billing-partner.boacompra.com/salereport.php

    Example of requisition for daily report: https://billing-partner.boacompra.com/salereport.php?year=2014&month=09&day=12&store_id=123&time=1412603297&hash=DASD98F7F098ASFD0909FE90AF98SDFQW

    Example of requisition for monthly report: https://billing-partner.boacompra.com/salereport.php?year=2014&month=09&store_id=123&time=1412603297&hash=DASD98F7F098ASFD0909FE90AF98SDFQW

    Technical Support

    UOL BoaCompra has a technical team to support Merchant's developers during the billing system integration process.

    Before contact the support, please make sure to read all the manuals that refers to system integration and administration.

    Questions and suggestions can be sent to your account manager.