NAV Navbar
java php ruby python
  • Credit Card
  • Boleto
  • EWallet
  • Transaction API
  • Status Change
  • Sandbox
  • Errors
  • Credit Card

    Direct Checkout Credit Card Workflow

    Direct Checkout Workflow

    How it Works

    1. The merchant loads BoaCompra script in clients browser.

    2. If desired, the merchant get installments options to show to the customer.

    3. Customer fill and submit payment info, then a method is called in BoaCompra script.

    4. After receiving the direct-token customer submit all the necessary information to merchant server.

    5. The Merchant submits to /transactions to create the transaction.

    6. BoaCompra creates an order and returns the status transaction and ID to merchant.

    7. The Merchant returns the transation status to customer.

    Including Direct Checkout Script

    This script is minified and doesn’t inject any dependency on your page, just the Boacompra.PaymentMethod object that will be used for the integration and can be added before the tag avoiding loading problems in the current page. It is very important to use this script from our CDN, to maintain the compatibility with UOL BoaCompra Payment API.

    To include the Direct Checkout JS in your payment page is required the insertion of a script tag with the JS file URL:

    <script src="http://stc.boacompra.com/payment.boacompra.min.js"></script>
    

    Direct Payment Token

    To start the payment flow is necessary to create the direct-token provided by the Direct Checkout JS API. This method returns the Direct Token required in the Direct Payment API integration. The credit card data must be informed and will be stored according to PCI-DSS Compliance standards. We highly recommend not to store or traffic this data in your system unless you have PCI certification. The getDirectToken method expects two parameters: Credit card data object and a callback function.

    Creating the direct-token in javascript

    //credit card data
    var data = {
        creditCard: '5555666677778884',
        cvv: '123',
        expiration: {
            month: '02',
            year: '2026'
        }
    };
    
    //callback function for payment.getDirectToken function
    var callback = function(err, directToken) {
        if (err) {
            //Error in token generation
            return false;
        }
        console.log('Token generated with success');
        console.log(directToken);
    };
    
    //note: the payment object must be previously instantiated before call this function (see full example on the next section).
    //calling the getDirectToken function to generate the credit-card token
    payment.getDirectToken(data, callback);
    

    Credit card object

    Property Type Value
    creditCard string Credit card number
    cvv string Credit card CVV
    expiration object Object with expiration data
    expiration.month string Credit card expiration month (2 characters)
    expiration.year string Credit card expiration year (4 characters)


    Example of credit card object:

    var creditCard = {
        creditCard: '5555666677778884',
        cvv: '123',
        expiration: {
            month: '02',
            year: '2020'
        }
    };
    

    Callback function

    The callback function expects two parameters: an error and a string token.

    Example of callback function:

    var callback = function(err, directToken) {
        if (err) {
            //Error in token generation
            return false;
        }
        console.log('Token generated with success');
        console.log(directToken);
    };
    

    Full Example

    Here you will find a detailed and explained example of a HTML file implementing our javascript file.

    <!DOCTYPE html>
    
    <!-- This html script must be used into a configured virtual host in your Web Server -->
    
    <html>
        <head>
            <meta charset="utf-8">
    
            <title>Boacompra Direct Checkout Test</title>
    
            <!-- Script loaded with a dynamic parameter (?p=999999) value to invalidate the browser cache. -->
            <script type="text/javascript" src="https://stc.boacompra.com/payment.boacompra.min.js?p=999999"></script>
    
            <script type="text/javascript">
                // You MUST instance the payment object ASAP after add the javascript on page, 
                // it will prevent loading time issues in the flow.
                var payment = new Boacompra.PaymentMethod();
            </script>
        </head>
    
        <body>
            <a href="javascript:charge()" target="_self">Click here to Generate the DirectToken</a>
    
            <script type="text/javascript">
                // Example: https://developers.boacompra.com/direct-checkout-v1/#direct-payment-token
    
                function charge() {
                    // User's credit card data should be collected in a html form
                    var cardData = {
                        creditCard: '5555666677778884',
                        cvv: '123',
                        expiration: {
                            month: '02',
                            year: '2026'
                        }
                    };
    
                    //callback function will contain errors or a directToken
                    var callback = function(err, directToken) {
                        if (err) {
                            // Check all errors in:
                            // https://developers.boacompra.com/direct-checkout-v1/#direct-payment-js
                            alert('Error: ' + err);
    
                            return false;
                        }
    
                        alert('Success!\ndirect-token: ' + directToken + '\n\nUse them to create your transaction.');
    
                        // Post [directToken + user data, previously collected from html forms] to your server (Ajax request)
    
                        // The directToken parameter will be used to create your transaction
                        // on the endpoint https://api.boacompra.com/transactions
    
                        // The directToken parameter and others are descibed in our Manual:
                        // https://developers.boacompra.com/direct-checkout-v1/#transaction-api
                    };
    
                    payment.getDirectToken(cardData, callback);
                }
            </script>
        </body>
    </html>
    

    Credit Card Installments

    Installment allows customers to split up a full payment into smaller amounts. In order to get the credit card installments, you need to do the following steps:

    Or

    Get brand

    The request to get brand is used to check the flag of the card being typed. This route receives the credit card BIN (first six digits of the card) and returns data such as the credit card brand name, CVV size, if it has an expiration date and which validation algorithm.

    Method: GET Host: https://api.boacompra.com/card/bin/{credit_card_bin}

    Example to get the brand via cURL

    curl -X GET \
        'https://api.boacompra.com/card/bin/123456' \
        -H 'content-type: application/json' \
        -H 'accept: application/vnd.boacompra.com.v1+json; charset=UTF-8' \
        -H 'authorization: 123:ba567109f868df40c7cda9c5563bf2a9cdcb8b6b654654165'
    
    // Response headers:
    HTTP/1.1 200 OK
    Content-type: application/vnd.boacompra.com.v1+json; charset=UTF-8
    
    // Response Body:
    {
        "bin": {
            "number": 123456,
            "brand": "visa",
            "cvvSize": 3,
            "expirable": true,
            "validationAlgorithm": "LUHN",
            "installment": true
        }
    }
    


    Obtain the installment options

    To show the installment options for the customer, you must make a request to the Installments API.

    Method: GET

    Host: https://api.boacompra.com/card/installments?brand={brand_name}&country={country_iso2}&amount={amount_value}&currency={currency_value}

    List of Parameters:

    Parameter Description Type Mandatory
    brand Name of Brand String Yes
    country Country of Payment String (Limit 2) Yes
    amount Value of order Double Yes
    currency Currency of order String (Limit 3) Yes


    Example to get the credit card installments via cURL

    curl -X GET \
        'https://api.boacompra.com/card/installments?brand=visa&country=BR&amount=16.00&currency=BRL' \
        -H 'accept: application/vnd.boacompra.com.v1+json; charset=UTF-8' \
        -H 'authorization: 123:ba567109f868df40c7cda9c5563bf2a9cdcb8b6b654654165'
    
    // Response headers:
    HTTP/1.1 200 OK
    Content-type: application/vnd.boacompra.com.v1+json; charset=UTF-8
    
    // Response Body:
    {
      "installments": [
        {
          "quantity": 1,
          "totalAmount": 16,
          "installmentAmount": 16,
          "interestFree": true
        },
        {
          "quantity": 2,
          "totalAmount": 16.48,
          "installmentAmount": 8.24,
          "interestFree": false
        }
      ]
    }
    


    Get brand and installments in the same request

    The request to get the installment options receives the credit card BIN, country, amount, and currency and returns two objects such as bin and installments (which represents the installment options).

    Method: GET

    Host: https://api.boacompra.com/card?bin={credit_card_bin}&country={country_iso2}&amount={amount_value}&currency={currency_value}

    List of Parameters:

    Parameter Description Type Mandatory
    bin Credit Card BIN (first six digits of the card) Integer Number Yes
    country Country of Payment String (Limit 2) Yes
    amount Value of order Double Yes
    currency Currency of order String (Limit 3) Yes


    Example to get the brand and credit card installments via cURL

    curl -X GET \
        'https://api.boacompra.com/card?bin=123456&country=BR&amount=16.00&currency=BRL' \
        -H 'accept: application/vnd.boacompra.com.v1+json; charset=UTF-8' \
        -H 'authorization: 123:ba567109f868df40c7cda9c5563bf2a9cdcb8b6b654654165'
    
    // Response headers:
    HTTP/1.1 200 OK
    Content-type: application/vnd.boacompra.com.v1+json; charset=UTF-8
    
    // Response Body:
    {
      "bin": {
        "number": 123456,
        "brand": "visa",
        "cvvSize": 3,
        "expirable": true,
        "validationAlgorithm": "LUHN",
        "installment": true
      },
      "installments": [
        {
          "quantity": 1,
          "totalAmount": 16,
          "installmentAmount": 16,
          "interestFree": true
        },
        {
          "quantity": 2,
          "totalAmount": 16.48,
          "installmentAmount": 8.24,
          "interestFree": false
        }
      ]
    }
    

    Tokenization

    When applied to data security, is the process of substituting a sensitive data element with a non-sensitive equivalent, referred as a token. The sensitive credit card data used during the transaction will be converted into a token which can be used in future transactions. This technique allows the merchants to offer features such as one-click buying, retry sending transaction, and also allows the merchant to create its own service of recurring payment.

    How it Works?

    1 - Merchant submits the payment info to /transactions using the parameter transaction.save-payment-method as true.

    2 - BoaCompra creates a unique token (payment-method.code) and maps onto the payment-method object reponse.

    3 - BoaCompra returns the transaction object and payment-method object.

    4 - Merchant stores the payment-method object.

    5 - The transaction status is changed to COMPLETE.

    6 - Merchant can now use payment-method.code as transaction.payment-method-code instead of direct-token to create future transactions for the same customer.

    Available Brands

    Boleto

    Direct Checkout Boleto Workflow

    Direct Checkout Workflow

    How it Works

    1. Customer fills and submits all necessary payment information to merchant server.

    2. The Merchant submits to /transactions to create the transaction.

    3. BoaCompra creates an order and returns the transaction code, Boleto URL and barcode number to merchant.

    4. Merchant displays the Boleto to customer using the Boacompra Boleto URL or provides the barcode number to customer.

    EWallet

    Wallets are card repositories and online consumer payment data. Digital wallets allow a consumer to register their payment data, reducing the purchase process by having only one registration.

    Digital wallets available
    PagSeguro
    PayPal

    How it Works

    1. Customer fills and submits all necessary payment information to merchant server.

    2. The Merchant submits to /transactions to create the transaction.

    3. BoaCompra creates an order and returns the Transaction Code and Payment URL to merchant.

    4. Merchant redirects the customer to BoaCompra's Payment URL.

    5. The customer accesses the Payment URL and pays the transaction through the payment method website.

    6. After the success in the payment flow, the customer will be redirected to Merchant's Success URL. If the customer cancels the process, he will be redirected to Merchant's Fail URL.

    Transaction API

    Header Specification

    Field Description Mandatory
    Accept API version, data type and encoding Yes
    Authorization Authorization Yes
    Content-MD5 MD5 of body request Yes*
    Content-Type Only Application/json is accepted Yes

    Example headers

    Accept: application/vnd.boacompra.com.v1+json; charset=UTF-8
    Authorization: 123:ba567109f868df40c7cda9c5563bf2a9cdcb8b6b654654165
    Content-MD5: e0a84d86a1dc5fb29dabafff83623a7d
    Content-Type: application/json
    

    How to Generate the Authorization Header

    The authorization is generated by merchant-id, secret-key, HTTP-Verb and ContentMD5.

    The authorization header is formed by merchant-id, secret-key , HTTP-Verb and ContentMD5 of the body request previously generated. Generate hmac-sha256 of HTTP-Verb concatenated with Content-MD5 using secret key. The format is merchant-id:hmac-sha256((HTTP-Verb + Content-MD5), secrect-key)

    Example authorization for POST requests

    final String data = this.httpVerb+this.contentMD5;
      Mac mac = Mac.getInstance("HmacSHA256");
      mac.init(new SecretKeySpec(this.secretKey.getBytes("UTF8"), "HmacSHA256"));
      return Hex.encodeHexString(mac.doFinal(data.getBytes("UTF-8")));
    
    <php
    
    $hashHmac = hash_hmac(
        'sha256',
        '/transactions' . $contentMD5,
        $secretKey
    );
    
    $authorizationHash = $merchantId . ':' . $hashHmac;
    
    //python v.2.7.13
    import hashlib
    import hmac
    
    key = 'bc123'
    contentMd5 = '123';
    
    signature = hmac.new(
        key,
        '/transactions'+contentMd5,
        hashlib.sha256
    ).hexdigest()
    
    --------------------------------
    
    //python v3
    import hashlib
    import hmac
    import base64
    
    message = bytes('/transactions', 'utf-8') +  bytes('123', 'utf-8') //contentmd5
    secret = bytes('bc123', 'utf-8')
    
    hash = hmac.new(secret, message, hashlib.sha256).hexdigest()
    
    require 'openssl'
    
    puts OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), SECRET_KEY, '/transactions' + @contentMD5)
    

    Authorization header for GET requests is formed by merchant-id, secret-key and HTTP-Verb. Generated hmac-sha256 of HTTP-Verb using secret key. The format is merchant-id:hmac-sha256(HTTP-Verb, scret-key)

    Merchant-id and Secret-key will be provided by BoaCompra before integration start.

    This API responsibility is to create transactions using direct payment integration.

    Example authorization for GET requests

    final String data = this.httpVerb;
      Mac mac = Mac.getInstance("HmacSHA256");
      mac.init(new SecretKeySpec(this.secretKey.getBytes("UTF8"), "HmacSHA256"));
      return Hex.encodeHexString(mac.doFinal(data.getBytes("UTF-8")));
    
    <php
    $hashHmac = hash_hmac(
        'sha256',
        '/transactions',
        $secretKey
    );
    $authorizationHash = $merchantId . ':' . $hashHmac;
    
    //python v.2.7.13
    import hashlib
    import hmac
    
    key = 'bc123'
    
    signature = hmac.new(
        key,
        '/transactions',
        hashlib.sha256
    ).hexdigest()
    
    --------------------------------
    
    //python v3
    import hashlib
    import hmac
    import base64
    
    message = bytes('/transactions', 'utf-8')
    secret = bytes('bc123', 'utf-8')
    
    hash = hmac.new(secret, message, hashlib.sha256).hexdigest()
    
    require 'openssl'
    
    puts OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), SECRET_KEY, '/transactions')
    

    Creating Transactions

    Production URL: https://api.boacompra.com/transactions

    Sandbox URL: https://api.sandbox.boacompra.com/transactions

    HTTP Method: POST

    Request Data

    Parameter Description Type Mandatory
    transaction.direct-token Token containing credit card encrypted data, generated by Direct Checkout JavaScript API String No [1]
    transaction.payment-method-code Token which represents a payment method previously saved and already activated. Alphanumeric of 32 characters String No
    transaction.project-number Merchant Project Identifier. Default value is 1 Integer Number No
    transaction.type Type of the transaction. Accepts only direct String Yes
    transaction.description Description of the transaction. Limit of 200 characteres. String Yes
    transaction.payment-type Type of the payment. Accepts credit_card, boleto, pagseguro and paypal String Yes
    transaction.country Country of the payment. Accepts only BR String Yes
    transaction.currency Currency of the transaction. Accepts only BRL String Yes
    transaction.amount Amount of the transaction. Separating cents by dot, with two decimal places Integer Number Yes
    transaction.reference Merchant Transaction Identifier. Limit of 64 characters String Yes
    transaction.notify-url URL (must bind ports 80 or 443) used to send transaction statuses changes notifications by HTTP String Yes
    transaction.language Language used. Accepts pt-BR, en-US, es-ES, pt-PT and tr-TR String Yes
    transaction.installments Installments quantity Integer Number No [2]
    transaction.save-payment-method Used to save payment method for future transactions. See more Boolean No
    transaction.redirect-success-url URL used to redirect the payer after making payment by PagSeguro or PayPal, must be a valid URL String No [3]
    transaction.redirect-fail-url URL used to redirect the payer when the payment flow (by PagSeguro or PayPal) fails String No [3]
    payer.name Payer Full Name. Limit of 50 characters, mininum of 2 words. See more String Yes
    payer.email Payer Email. Limit of 60 characters. See more String Yes
    payer.ip Payer Address IP. Accepts Ipv4 String No [4]
    payer.phone-area-code Payer Area code phone. Limit 2 characters Number Yes
    payer.phone-number Payer Phone number. Limit 8 to 9 characters Number Yes
    payer.document.type Payer Document type. Accepts: CPF and CNPJ String Yes
    payer.document.number Payer Document number. Remove special characters String Yes
    payer.birth-date Payer Birth date. ISO-8601 Pattern (YYYY-MM-DD) String Date Yes

    Body example of a request using credit card

    // Request body:
    {
      "transaction": {
        "direct-token": "eyJkbmEiOiJjOTg2NzAyMDQwN2Q0OGJhYTAxMmM4N2Y1ZjUzMjA1YyIsImlwIjoiMTcyLjE5LjAuMyIsImRmIjoiNDUzM2Q0NjQzNTczNDQxMGI0YmUxN2IxZmVkNjcwNWIifQ==",
        "reference": "REF-XXX-1512751104",
        "project-number": 1,
        "type": "direct",
        "description": "Test transaction",
        "payment-type" : "credit_card",
        "country" : "BR",
        "currency": "BRL",
        "amount": 100.00,
        "notify-url": "https://virtual-store.com/notifications/",
        "language": "pt-BR",
        "installments" : 1
      },
      "payer": {
        "name": "Payer Name",
        "email": "payer@uolinc.com",
        "birth-date": "1982-12-20",
        "phone": {
            "area-code": "11",
            "number": "988881234"
        },
        "document": {
          "type": "CPF",
          "number": "00000000191"
        }
      }
    }
    
    // Response body:
    {
      "transaction": {
        "transaction-code": "110122345",
        "reference": "REF-XXX-1512751104",
        "amount": 100,
        "status": "PENDING",
        "currency": "BRL",
        "country": "BR",
        "customer-email": "payer@boacompra.com",
        "date-created": "2017-12-08T14:38:48.907609673-02:00"
      }
    }
    


    Body example of a transaction using boleto

    // Request body:
    {
      "transaction": {
        "reference": "REF-XXX-1526654410082",
        "type": "direct",
        "project-number": 1,
        "description": "Test transaction",
        "payment-type": "boleto",
        "country": "BR",
        "currency": "BRL",
        "amount": 100.00,
        "notify-url": "https://virtual-store.com/notifications/",
        "language": "pt-BR"
      },
      "payer": {
        "name": "Payer Pagador",
        "email": "payer@uolinc.com",
        "birth-date": "1986-10-06",
        "ip": "172.217.29.195",
        "phone": {
          "area-code": "11",
          "number": "988881234"
        },
        "document": {
          "type": "CPF",
          "number": "12345678909"
        }
      }
    }
    
    // Response body:
    {
        "transaction": {
            "transaction-code": "110122345",
            "reference": "1526654410082",
            "amount": 100,
            "tariff": 1.5,
            "status": "PENDING",
            "currency": "BRL",
            "country": "BR",
            "customer-email": "payer@uolinc.com",
            "date-created": "2018-05-18T11:37:22.733638734-03:00",
            "barcode-number": "03391749800000002509557354800007024959560102",
            "digitable-line": "03399557345480000702049595601029174980000000250",
            "payment-url": "https://payment.boacompra.com/178de8419370475cb154cc46ee3d6d94"
        }
    }
    


    Body example of a transaction using EWallet: PagSeguro

    {
        "transaction": {
            "reference": "REF-XXX-1526582903184",
            "type": "direct",
            "project-number": 1,
            "description": "Test transaction",
            "payment-type": "pagseguro",
            "country": "BR",
            "currency": "BRL",
            "amount": 200.00,
            "notify-url": "https://virtual-store.com/notifications/",
            "redirect-success-url": "https://virtual-store.com/home/",
            "redirect-fail-url": "https://virtual-store.com/retry/",
            "language": "pt-BR"
        },
        "payer": {
            "name": "Payer Pagador",
            "email": "payer@uolinc.com",
            "birth-date": "1986-10-06",
            "ip": "172.217.29.195",
            "phone": {
                "area-code": "11",
                "number": "988881234"
            },
            "document": {
                "type": "CPF",
                "number": "12345678909"
            }
        }
    }
    


    Body example of a transaction using EWallet: PayPal

    {
        "transaction": {
            "reference": "REF-XXX-1526582903184",
            "type": "direct",
            "project-number": 1,
            "description": "Test transaction",
            "payment-type": "paypal",
            "country": "BR",
            "currency": "BRL",
            "amount": 200.00,
            "notify-url": "https://virtual-store.com/notifications/",
            "redirect-success-url": "https://virtual-store.com/home/",
            "redirect-fail-url": "https://virtual-store.com/retry/",
            "language": "pt-BR"
        },
        "payer": {
            "name": "Payer Pagador",
            "email": "payer@uolinc.com",
            "birth-date": "1986-10-06",
            "ip": "172.217.29.195",
            "phone": {
                "area-code": "11",
                "number": "988881234"
            },
            "document": {
                "type": "CPF",
                "number": "12345678909"
            }
        }
    }
    


    Transaction response using EWallet: PagSeguro or PayPal

    {
        "transaction": {
            "transaction-code": "110122345",
            "reference": "REF-XXX-1531253099616",
            "amount": 200,
            "status": "PENDING",
            "currency": "BRL",
            "country": "BR",
            "customer-email": "payer@uolinc.com",
            "date-created": "2018-07-10T17:05:03.625961818-03:00",
            "payment-url": "https://sandbox.gateway.boacompra.com/payment/paypal/aHR0cHM6Ly92aXJ0dWFsLXN0b3JlLmNvbS9ob21lLw=="
        }
    }
    


    Body example of a transaction request using tokenization feature

    // Request body:
    {
      "transaction": {
        "reference": "REF-XXX-1512751104",
        "direct-token": "eyJkbmEiOiJjOTg2NzAyMDQwN2Q0OGJhYTAxMmM4N2Y1ZjUzMjA1YyIsImlwIjoiMTcyLjE5LjAuMyIsImRmIjoiNDUzM2Q0NjQzNTczNDQxMGI0YmUxN2IxZmVkNjcwNWIifQ==",
        "project-number": 1,
        "type": "direct",
        "description": "Test transaction",
        "payment-type" : "credit_card",
        "country" : "BR",
        "currency": "BRL",
        "amount": 100.00,
        "notify-url": "https://virtual-store.com/notifications/",
        "language": "pt-BR",
        "installments" : 1,
        "save-payment-method": true
      },
      "payer": {
        "name": "Payer Name",
        "email": "payer@uolinc.com",
        "birth-date": "1982-12-20"
        "phone": {
            "area-code": "11",
            "number": "988881234"
        },
        "document": {
          "type": "CPF",
          "number": "00000000191"
        }
      }
    }
    
    //Response body:
    {
      "transaction": {
        "transaction-code": "110122345",
        "reference": "REF-XXX-1512751104",
        "amount": 100,
        "status": "PENDING",
        "currency": "BRL",
        "country": "BR",
        "customer-email": "payer@boacompra.com",
        "date-created": "2018-04-06T13:27:57.041488635-03:00"
      },
      "payment-method": {
        "code": "123E4567E89B12D3A456426655440000",
        "credit-card": {
          "brand": "visa",
          "masked-number": "************0002",
          "expiration-date": "2026-12"
        }
        "date-created": "2018-04-06T13:27:57.098349625-03:00"
      }
    }
    


    Body example of a transaction using a credit card token (payment-method-code)

    // Request body:
    {
      "transaction": {
        "reference": "REF-XXX-1499348616123",
        "payment-method-code": "123E4567E89B12D3A456426655440000",
        "project-number": 1,
        "type": "direct",
        "description": "Test transaction",
        "payment-type" : "credit_card",
        "country" : "BR",
        "currency": "BRL",
        "amount": 100.00,
        "notify-url": "https://virtual-store.com/notifications/",
        "language": "pt-BR",
        "installments" : 1,
        "birth-date": "1982-12-20"
      },
      "payer": {
        "name": "Payer Name",
        "email": "payer@uolinc.com",
        "phone": {
            "area-code": "11",
            "number": "988881234"
        },
        "document": {
          "type": "CPF",
          "number": "00000000191"
        }
      }
    }
    
    //Response body:
    {
        "transaction": {
            "transaction-code": "110122345",
            "reference": "REF-XXX-1499348616123",
            "amount": 100,
            "status": "PENDING",
            "currency": "BRL",
            "country": "BR",
            "customer-email": "payer@uolinc.com",
            "date-created": "2018-05-18T11:49:09.015317883-03:00"
        }
    }
    


    Expected Response Headers

    HTTP/1.1 201 Created
    Content-type: application/vnd.boacompra.com.v1+json; charset=UTF-8
    

    Status Change

    BoaCompra will send HTTP notifications to inform about transactions statuses changes. Please refer to the Transaction Notification Manual.

    Sandbox

    The sandbox allow you to test and integrate with our API without creating a real charge in a credit card. To use it, you must send requests to our sandbox URL https://api.sandbox.boacompra.com when creating or querying a transaction.

    Transactions created in the sandbox, will be available at our partner's area within the “Transactions Test” option.

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

    Tokenization Feature

    When using direct-token and save-payment-method on sandbox environment, the transaction response will always have the same payment method object which is pre-configured independently of the credit card informed.

    In order to use payment-method-code instead of direct-token on sandbox environment, use the parameter payment-method-code as 123E4567E89B12D3A456426655440000 which is the same payment-method.code returned in the payment-method object response. Any other payment-method-code will return an error 20987:payment_method_not_found.

    Payment method object pre-configured

    /* payment method object */
    {
        "code": "123E4567E89B12D3A456426655440000",
        "credit-card": {
            "brand": "visa",
            "masked-number": "************0002",
            "expiration-date": "2026-12"
        },
        "date-created": "2018-04-11T11:31:11.571488493-03:00"
    }
    


    Error response when using a wrong payment-method-code

    {
        "errors": [
            "code": 20987,
            "description": "payment_method_not_found"
        ]
    }
    

    Errors

    Headers

    Authorization Header

    Code Key Description
    10001 header_authorization_missing Missing header Authorization in request
    10002 header_authorization_bad_format Authorization header bad formation
    10003 header_authorization_invalid Authorization header error

    Content-MD5 Header

    Code Key Description
    10101 header_contentmd5_missing Missing header Content-MD5
    10102 header_contentmd5_failed Content-MD5 doesn't match with the request MD5

    Accept Header

    Code Key Description
    10201 header_accept_missing Missing header Accept in request
    10202 header_accept_application_missing Missing Application on header Accept
    10203 header_accept_bad_format Header Accept with bad format
    10204 header_accept_format_missing Missing Format on header Accept
    10205 header_accept_charset_missing Missing Charset on header Accept
    10206 header_accept_application_invalid Invalid Application on Accept Header
    10207 header_accept_format_invalid Invalid Format on Accept Header
    10208 header_accept_charset_invalid Invalid Charset on Accept Header
    10209 header_accept_version_invalid Invalid Version on Accept Header

    Content-Type Header

    Code Key Description
    10301 header_contenttype_missing Missing header Content-Type in request
    10302 header_contenttype_not_accepted Content-Type is not accepted

    Accept Language

    Code Key Description
    10401 header_language_not_accepted Language not accepted

    Credit Card Installments API

    Code Key Description
    30301 bin_missing Missing Bin
    30302 bin_invalid Invalid Bin
    30303 brand_missing Missing Brand
    30304 brand_invalid Invalid Brand
    30305 country_missing Missing Country
    30306 country_invalid Invalid Country
    30307 amount_missing Missing Amount
    30308 amount_invalid Invalid Amount
    30309 currency_missing Missing Currency
    30310 currency_invalid Invalid Currency

    Direct Payment JS

    Only for credit_card payment-type.

    Error Description Critical
    callback_must_be_a_function The callback parameter in the getDirectToken method is not a function Yes*
    creditcard_object_malformed Credit card object is not a javascript object Yes*
    credit_card_internal_error Error on save credit card on PCI environment No
    creditcard_invalid_fields Data from credit card object is not valid No
    creditcard_invalid_object Credit card object has an invalid structure Yes*
    session_create_error The object cannot retrive a session from BoaCompra No
    session_creating_in_progress The Process of retrieving a session from BoaCompra was not yet finished No
    session_network_error The object receives a network error on a attempt to create a session Yes

    Transaction API

    Code Key Description
    10102 header_contentmd5_invalid Content-MD5 header doesn’t match with the expected
    10203 header_accept_bad_format Header Accept with bad format
    10204 header_accept_format_missing Missing Format on header Accept
    10205 header_accept_charset_missing Missing Charset on header Accept
    10206 header_accept_application_invalid Invalid Application on Accept Header
    10207 header_accept_format_invalid Invalid Format on Accept Header
    10208 header_accept_charset_invalid Invalid Charset on Accept Header
    10209 header_accept_version_invalid Invalid Version on Accept Header
    20900 transaction_missing Transaction is missing
    20901 transaction_amount_missing Missing Transaction Amount
    20902 transaction_amount_invalid Invalid Transaction Amount
    20904 payer_email_missing Payer email is missing
    20905 payer_email_invalid Payer email is not valid
    20908 transaction_reference_missing Transaction Reference missing
    20909 transaction_reference_exceed_limit Transaction Reference Exceed Limit
    20910 transaction_directtoken_missing* Transaction Direct Token Missing
    20911 transaction_directtoken_invalid* Issue generating Direct Token or not accepted card brand See more
    20912 transaction_notifyurl_missing Transaction Notify URL Missing
    20913 transaction_notifyurl_invalid Transaction Notify URL Invalid
    20914 transaction_notifyurl_length_invalid Transaction Notify URL Invalid Length
    20915 payer_missing Payer is missing
    20919 payer_phone_number_missing Payer phone number is missing
    20920 payer_phone_number_invalid Payer phone number is not valid
    20921 payer_phone_areacode_missing Payer phone area code is missing
    20922 payer_phone_areacode_invalid Payer phone area code is not valid
    20926 payer_document_number_missing Payer document number is missing
    20927 payer_document_number_invalid Payer document number is not valid
    20928 payer_name_missing Payer name is missing
    20929 payer_name_invalid Payer name is not valid
    20930 transaction_language_missing Transaction Language missing
    20931 transaction_reference_invalid Transaction Reference has special chars
    20932 transaction_testmode_invalid Transaction Test Mode value is not accepted
    20934 payer_birthdate_invalid Payer birth date is not valid
    20935 payer_birthdate_missing Payer birth date is missing
    20936 transaction_description_missing Transaction Description Missing
    20937 transaction_description invalid Transaction Description is not valid
    20938 transaction_country_missing Transaction Country is missing
    20941 transaction_currency_missing Transaction Currency is missing
    20942 transaction_save_payment_method_invalid Transaction Save Payment Method is not valid
    20943 transaction_currency_length_invalid Transaction Currency Invalid Length
    20951 transaction_installments_missing Transaction Installments is missing
    20952 transaction_installments_invalid Transaction Installments are not valid
    20954 transaction_currency_invalid Transaction Currency is invalid
    20955 transaction_country_invalid Transaction Country is not valid
    20958 transaction_reference_invalid Transaction Reference is not unique
    20959 transaction_project_number_invalid Transaction Project Number is invalid
    20965 payer_ip_missing Payer IP is missing
    20966 payer_ip_invalid Payer IP is invalid
    20977 transaction_type_missing Transaction Type is missing
    20978 transaction_type_invalid Transaction Type is not valid
    20979 payment_type_missing Payment type is missing
    20980 payment_type_invalid Payment type invalid (must be credit_card or boleto)
    20981 payer_document_type_missing Payer document type is missing
    20982 payer_document_type_invalid Payer document type is not valid
    20984 payment_exceed_limits Payment exceed the limit purchase (only for Brazil, R$ 10000) by Payer Document
    20985 transaction_language_invalid Transaction Language invalid
    20986 unavailable_payment_method The choosen payment method is not avaliable
    20987 payment_method_not_found Payment method was not found for the payment method code given or is not active
    20989 payment_method_code_invalid Payment method code format doesn't match (alphanum, 32 chars)
    209100 payer_blacklisted Payer is blacklisted by our risk analysis and must contact Boacompra's Customer Support
    209101 payer_blacklisted_by_psp Payer is blacklisted by our PSP and must contact Boacompra's Customer Support
    209102 transaction_returnurl_missing Transaction return URL is missing
    209103 transaction_returnurl_invalid Transaction return URL is invalid
    209104 transaction_returnurl_length_invalid Transaction return URL has an invalid length
    209105 transaction_redirectsuccessurl_missing Transaction redirect success URL is missing
    209106 transaction_redirectsuccessurl_invalid Transaction redirect success URL is invalid
    209107 transaction_redirectsuccessurl_length_invalid Transaction redirect success URL has an invalid length
    209108 transaction_redirectfailurl_missing Transaction redirect fail URL is missing
    209109 transaction_redirectfailurl_invalid Transaction redirect fail URL is invalid
    209110 transaction_redirectfailurl_length_invalid Transaction redirect fail URL has an invalid length