NAV Navbar
php java ruby python
  • Transaction API
  • Credit Card
  • PostPay/Cash/ATM
  • e-Wallet
  • Status Change
  • Sandbox
  • Errors
  • 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 [1]
    Content-Type Only Application/json is accepted Yes
    X-Processing-Mode Processing mode (see more) Yes [2]

    Example headers

    Accept: application/vnd.boacompra.com.v2+json; charset=UTF-8
    Authorization: 123:ba567109f868df40c7cda9c5563bf2a9cdcb8b6b654654165
    Content-MD5: e0a84d86a1dc5fb29dabafff83623a7d
    Content-Type: application/json
    X-Processing-Mode: sync
    

    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 starts.

    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

    After creating all the necessary headers, use them to create a payment request with these avaible payment methods:

    For all payment request is expected a response with the following headers:

    Expected Response Headers

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

    Transaction Status

    Each transaction has a transaction.status that represent its current state, as well as any action you should take:

    STATUS DESCRIPTION ACTION TO TAKE
    PAID The payment was succesfully authorised. Inform the customer that the payment was succcesful.
    PENDING It´s not posible to obtain the final status of the payment at this time. Inform the customer that hat you've received their order, and are waiting for the payment to be completed. When the payment has a status change, our service will send a notification.
    REJECTED The payment was refused. Inform the customer that their payment was refused. The API returns a transaction.status-reason in the same response that indicates why it was refused. We do not recommend disclosing this refusal to the customer . Ask to customer to try the payment again using a different payment method or card.

    Possible refusal reason messages:
    • CREDIT_CARD_IS_BLOCKED
    • CREDIT_CARD_WITHOUT_FUNDS
    • CREDIT_CARD_SUSPECTED_FRAUD
    • CREDIT_CARD_CANCELED
    • INVALID_CREDIT_CARD
    • CANCELED_BY_OPERATOR
    • REFUSED_BY_OPERATOR
    • PROVIDER_UNAVAILABLE
    • OPERATION_DEADLINE_EXCEEDED

    Credit Card

    Cards are a dominant payment method worldwide. Credit cards are issued by banks and allow customers to borrow money with a promise to pay it back within a grace period to avoid extra fees. Consumers can accrue a continuing balance of debt, subject to being charged interest on the amount.

    To take advantage of the features available in our API, it is important to first understand the concepts involved in processing a credit card transaction.

    Concept Description
    PCI/DSS Payment Card Industry Data Security Standards
    Client-side Encryption Programming technique to encrypt sensitive cardholder data on the client side and securely transfer this data to the payment gateway to process a payment.
    Anti fraud It is a fraud prevention platform that provides a detailed risk analysis of online purchases. Transactions are subject to a large number of rules, besides the specific rules for each segment. According to the pre-established criteria, the request can be automatically accepted, refused or sent for manual analysis.
    Tokenization It´s a process that allows secure storage of sensitive credit card data. The data is transformed into an encrypted code named “token”, which can be stored in a database. This allows merchants to make recurring payments.
    Installments Installment payments are a way to spread out a payable amount. A customer can split up a full payment into smaller chunks, which they pay off at a regular intervals over a set period.

    Workflow

    Direct Checkout Workflow

    1. The merchant loads BoaCompra script in the client's browser.

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

    3. The customer fills and submits payment info, then a method is called in BoaCompra's script.

    4. After receiving the direct-token, the customer submits all the necessary information to the merchant's server.

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

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

    7. The Merchant returns the transation status to the customer.

    Creating a Credit Card Payment

    Step 1: Collect Payer Details

    For most payment methods, you can collect the payment details directly from the customer. For credit cards, however, you will need to encrypt any sensitive credit card details.

    Encrypt credit card details

    BoaCompra provides a JavaScript library so you can use it to securely collect your customer's credit card details without sensitive credit card data reaching your server. When the customer enters the details of the card on your site, the script collects the sensitive data and creates an encrypted version that you can securely transmit to BoaCompra.

    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 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 token method

    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. It's highly recommended not to store or traffic this data in your system unless you have PCI certification. The getDirectToken method expects two parameters: Credit card 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/#creating-a-credit-card-payment
    
                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/#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/#transaction-api
                    };
    
                    payment.getDirectToken(cardData, callback);
                }
            </script>
        </body>
    </html>
    

    Step 2 (optional): Get Credit Card Installments

    Credit card Installment payments are a way to spread out a payable amount. A customer can choose to split up a full payment into smaller chunks, which they pay off at regular intervals over a set period.

    Brazil

    Credit Card Installments available in Brazil by brand:

    To get the payment installments, you need to do the following:

    Get brand and installments

    To show the installment options for the customer, you must make a request to the Installments API. The installments options will change according to the credit card brand.

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

    Method: GET

    Property Description Type Size Required
    bin Credit Card BIN (first six digits of the card) Integer 6 Yes
    country Country of Payment String 2 Yes
    amount Value of order Double Min of 0.01 Yes
    currency Currency of order String 3 Yes

    Example to get the brand and credit card installments with 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
        }
      ]
    }
    

    Check brand name (optional)

    If you want to show the credit card brand name, this service offers this possibility.

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

    Method: GET

    Property Description Type Size Required
    bin Credit Card BIN (first six digits of the card) Integer 6 Yes

    Example with 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
        }
    }
    

    Bin Object

    Property Type
    number Integer
    brand String
    cvvSize Integer
    expirable Boolean
    validationAlgorithm String
    installment Boolean

    Check installment options (optional)

    If you want to show the installments amount according to the brand for the customer, this service offers this possibility.

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

    Method: GET

    Property Description Type Size Required
    brand Name of Brand String Yes
    country Country of Payment String 2 Yes
    amount Value of order Double Min of 0.01 Yes
    currency Currency of order String 3 Yes

    Example with 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
        }
      ]
    }
    

    Installment Object

    Property Type
    quantity Integer
    totalAmount Integer
    totalinstallmentAmount Float
    interestFree Boolean

    Step 3: Request a Credit Card Payment

    After collecting the payment details from the customer, make a request to the Transaction API using the information given by the customer and specifying the chosen payment method by using the payment method type parameter.

    Request

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

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

    Method: POST

    Example of a request using credit card payment

    {
      "transaction": {
        "reference": "REF-XXX-1234567890",
        "project-number": 1,
        "country": "BR",
        "currency": "BRL",
        "checkout-type": "direct",
        "notification-url": "https://billing.checkout.com/processing",
        "language": "pt-BR"
      },
      "charge": [
        {
          "amount": 100.00,
          "payment-method": {
            "type": "credit-card",
            "sub-type": "mastercard"
          },
          "payment-info": {
            "installments": 3,
            "token": "eyJkbmEiOiI2NzY3YzAxNDEzNGM0NTc4ODg0ZjU2MjdmYTI0ZGVhZiIsImlwIjoiMjAwLjIyMS4xMzAuNDkiLCJkZiI6ImNmYWI3MDcxMDJlZDQ4MjU4MzJhNmY2MDBhNWZjZjc2In0="
          }
        }
      ],
      "payer": {
        "name": "John Doe",
        "email": "johndoe@email.com",
        "birth-date": "1988-12-25",
        "phone-number": "+5511991234556",
        "document": {
          "type": "CPF",
          "number": "31192071280"
        },
        "address": {
          "street": "Rua Teste",
          "number": "1102",
          "complement": "AP 10",
          "district": "Bairro Teste",
          "state": "PR",
          "city": "Maringá",
          "country": "BR",
          "zip-code": "87030010"
        },
        "ip": "200.221.118.80"
      },
      "shipping": {
        "cost": 0,
        "address": {
          "street": "Rua dos Bobos",
          "number": "1102",
          "complement": "AP 0",
          "district": "Vinicius de Moraes",
          "state": "PR",
          "city": "Maringá",
          "country": "BR",
          "zip-code": "87030010"
        }
      },
      "cart": [
        {
          "quantity": 1,
          "description": "Calça Jeans",
          "category": "Collectibles",
          "type": "physical",
          "unit-price": 1
        }
      ]
    }
    

    Request Parameter List

    Parameter Description Type Size Mandatory
    transaction Set of general transaction's information Object - Yes
    transaction.reference Merchant transaction identifier String Up to 64 Yes
    transaction.project-number Merchant project identifier. Default value is 1 Integer - No
    transaction.country Country of the payment. Accepts only BR String 2 Yes
    transaction.checkout-type Checkout type of the transaction. Accepts only direct String - Yes
    transaction.notification-url URL (must bind ports 80 or 443) used to send transaction status changes notifications by HTTP String Up to 200 Yes
    transaction.language Language used. Accepts pt-BR, en-US, es-ES, pt-PT and tr-TR String 5 Yes
    charge[] Set of payments. Currently accepting just one (1) payment Array 1 Yes
    charge[].amount Amount of the transaction. Separating cents by point, with two decimal places Double Min of 0.20 Yes
    charge[].payment-method.type Payment Method type (credit-card, postpay or e-wallet) String - Yes
    charge[].payment-method.sub-type Payment Method sub-type. Available brands (see more) String - No
    charge[].payment-info.installments Installments quantity (see more) String Min of 1 Yes
    charge[].payment-info.token Token containing credit card encrypted data (see more) String - Yes [1]
    charge[].payment-info.code Token which represents a payment method previously saved and already activated (see more) String 32 No
    charge[].payment-info.save Used to save payment method for future transactions (see more) Boolean - No
    payer Set of customer's information Object - Yes
    payer.name Customer name String Up to 50 Yes
    payer.email Customer e-mail address String Up to 60 Yes
    payer.birth-date Customer birth date. ISO-8601 Pattern (YYYY-MM-DD) String - Yes [3]
    payer.phone-number Customer phone number. e.g (+5544999884455) String - Yes
    payer.document.type Customer document Type. accepts: cpf and cnpj String - Yes
    payer.document.number Customer identification document. No special characters allowed. String - Yes
    payer.ip Customer IP. accepts Ipv4 String - No
    payer.address Customer address object Object - No [2]
    payer.address.street Customer address street String 3-160 Yes
    payer.address.number Customer address number String 1-20 Yes
    payer.address.complement Customer address complement String 5-40 No
    payer.address.district Customer address district String 4-60 Yes
    payer.address.state Customer address state or province String 2 Yes
    payer.address.city Customer address city String 3-60 Yes
    payer.address.country Customer address country (country iso 2) String 2 Yes
    payer.address.zip-code Customer address zip code String 8 Yes
    shipping Set of information that will be used to deliver the items in cart (see more) Object - No [2]
    shipping.cost Shipping cost Number - Yes
    shipping.address.street Shipping address street String 3-160 Yes
    shipping.address.number Shipping address number String 1-20 Yes
    shipping.address.complement Shipping address complement String 5-40 No
    shipping.address.district Shipping address district String 4-60 Yes
    shipping.address.state Shipping address state or province String 2 Yes
    shipping.address.city Shipping address city String 3-60 Yes
    shipping.address.country Shipping address country (country iso 2) String 2 Yes
    shipping.address.zip-code Shipping address zip Code String 8 Yes
    cart[] Set of items (at least one Item) Array Min of 1 Yes
    cart[].quantity Item quantity Integer Min of 1 Yes
    cart[].description Item description String 1-200 Yes
    cart[].unit-price Price per unit Double Min of 0.01 Yes
    cart[].type Item type (see more) String - Yes
    cart[].category Item category String 1-64 No

    Response

    Example of a response using credit card payment

    {
      "transaction": {
        "code": 111114891,
        "reference": "REF-XXX-1234567890",
        "amount": 100,
        "status": "PENDING",
        "currency": "BRL",
        "country": "BR",
        "payer-email": "johndoe@email.com",
        "date-created": "2018-10-09T10:23:05.916587756-03:00"
      }
    }
    

    Response Parameter List

    Property Description Type Size Format
    transaction.code BoaCompra's reference Integer
    transaction.reference Merchant's reference String
    transaction.amount Number
    transaction.status Current status (see more) String
    transaction.currency String 3 ISO 4217, e.g. "BRL"
    transaction.country String 2 ISO 3166-2, e.g. "BR"
    transaction.payer-email Customer e-mail address String
    transaction.date-created Date of creation String ISO-8601, e.g. "2018-10-19T14:38:04.082324056-03:00"
    ## Creating a Raw Credit Card Payment If you are PCI Level 1 or Level 2 certified you can submit raw card data to BoaCompra when you make a payment. To submit raw card data, contact your Account Manager, once they've set you up, you are ready to submit card fields when you make a payment request. BoaCompra recommends that you validate the number of digits entered for the credit card and card verification code before submitting the payment information. This will help reduce transaction declines due to buyer error. **Production URL**: `https://api.boacompra.com/transactions` **Sandbox URL**: `https://api.sandbox.boacompra.com/transactions` **HTTP Method**: `POST` ```javascript { "transaction": { "reference": "REF-XXX-1234567890", "project-number": 1, "country": "BR", "currency": "BRL", "checkout-type": "direct", "notification-url": "https://billing.checkout.com/processing", "language": "pt-BR"; }, "charge": [ { "amount": 50.00, "payment-method": { "type": "credit-card" }, "payment-info": { "installments": 2, "credit-card": { "number": "4073020000000002", "cvv": "123", "expiration-date": "2020-12" } } } ], "payer": { "name": "John Doe", "email": "johndoe@email.com", "ip": "64.128.112.215", "document": { "type": "CPF", "number": "31192071280" } } ``` | Property | Description | Type | Size | Required | | ----------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------- | -------- | ------------ | | transaction.reference | Merchant Transaction Identifier | String | 64 | Yes | | transaction.project-number | Merchant Project Identifier. Default value is `1` | Integer | | - | | transaction.contry | Country of the payment. Accepts only `BR` | String | 2 | Yes | | transaction.checkout-type | Checkout type of the transaction. Accepts only direct | String | | Yes | | transaction.notification-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 | 5 | Yes | | charge.amount | Amount of the transaction. Separating cents by point, with two decimal places | Integer | | Yes | | charge.payment-method.type | Payment Method Type. | String | | Yes | | charge.payment-method.sub-type | Payment Method Sub-type. | String | | | | charge.payment-info.installments | | String | | Yes | | charge.payment-info.credit-card.number | | String | | Yes | | charge.payment-info.credit-card.cvv | | String | | Yes | | charge.payment-info.credit-card.expiration-date | | String | | Yes | | payer.name | Customer name | String | | Yes | | payer.email | Customer email | String | | Yes | | payer.document.type | Customer Document Type. Accepts: `cpf` and `cnpj` | String | | Yes | | payer.document.number | Customer Identification document. No special characters allowed. | String | | Yes |

    Creating a Raw Credit Card Payment

    ⚠️ IMPORTANT: Anyone involved with the processing, transmission, or storage of card data must comply with the Payment Card Industry Data Security Standards (PCI DSS).

    If you are PCI Level 1 or Level 2 certified you can submit raw card data to BoaCompra when you make a payment. To submit raw card data, contact your Account Manager, once they've set you up, you are ready to submit card fields when you make a payment request.

    BoaCompra recommends that you validate the number of digits entered for the credit card, expiration date and card verification code before submitting the payment information. This will help reduce transaction declines due to customer error.

    Request

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

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

    HTTP Method: POST

    Example of a request using cURL

    curl -X POST \
      'https://api.boacompra.com/transactions' \
      -H 'accept: application/vnd.boacompra.com.v2+json; charset=UTF-8' \
      -H 'authorization: 123:ba567109f868df40c7cda9c5563bf2a9cdcb8b6b654654165' \
      -H 'content-md5: e0a84d86a1dc5fb29dabafff83623a7d' \
      -H 'content-type: application/json' \
      -H 'x-processing-mode: sync' \
      -d '{
       "transaction":{
          "reference":"REF-RAW-CC-1539193167",
          "project-number":1,
          "country":"BR",
          "currency":"BRL",
          "checkout-type":"direct",
          "notification-url":"https://billing.checkout.com/processing",
          "language":"pt-BR"
       },
       "charge":[
          {
             "amount":50.00,
             "payment-method":{
                "type":"credit-card"
             },
             "payment-info":{
                "installments":2,
                "credit-card":{
                   "number":"4073020000000002",
                   "cvv":"123",
                   "expiration-date":"2020-12"
                }
             }
          }
       ],
       "payer":{
          "name":"John Doe",
          "email":"johndoe@email.com",
          "ip":"64.128.112.215",
          "document":{
             "type":"CPF",
             "number":"31192071280"
          }
       }
    }'
    
    PROPERTY DESCRIPTION TYPE SIZE MANDATORY
    transaction.reference Merchant Transaction Identifier String 64 Yes
    transaction.project-number Merchant Project Identifier. Default value is 1 Integer -
    transaction.country` Country of the payment. Accepts only BR String 2 Yes
    transaction.checkout-type Checkout type of the transaction. Accepts only direct String Yes
    transaction.notification-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 5 Yes
    charge.amount Amount of the transaction. Separating cents by dot, with two decimal places Number Min of 0.20 Yes
    charge.currency Currency of the transaction. Accepts only BRL String 3 Yes
    charge[] Set of payments. Array 1 Yes
    charge[].payment-method.type Means of Payment Type. String - Yes
    charge[].payment-method.sub-type Means of Payment Sub-type. The Card issuer String - -
    charge.payment-info.installments Installments quantity String Min of 1 Yes
    charge.payment-info.credit-card.number Payer Card Number String 19 Yes
    charge.payment-info.credit-card.cvv Payer Card Secutiry Code String 4 Yes
    charge.payment-info.credit-card.expiration-date Payer Card Expiry date printed. Pattern YYYY-MM String 7 Yes
    payer Set of customer's information Object - Yes
    payer.name Payer name String Up to 50 Yes
    payer.email Payer email String Up to 60 Yes
    payer.document.type Payer Document Type. Accepts: cpf and cnpj String - Yes
    payer.document.number Payer Identification document. Remove special characters String - Yes

    Response

    Example of paid response

        {
          "transaction": {
            "code": 111181153,
            "reference": "REF-RAW-CC-1539193167",
            "amount": 100,
            "status": "PAID",
            "currency": "BRL",
            "country": "BR",
            "payer-email": "johndoe@email.com",
            "date-created": "2018-10-10T14:39:32.991217999-03:00"
          }
        }
    

    Example of rejected response

        {
          "transaction": {
            "code": 111181153,
            "reference": "REF-RAW-CC-1539193167",
            "amount": 100,
            "status": "REJECTED",
            "status-reason": "INVALID_CREDIT_CARD",
            "currency": "BRL",
            "country": "BR",
            "payer-email": "johndoe@email.com",
            "date-created": "2018-10-10T14:39:32.991217999-03:00"
          }
        }
    
    PROPERTY DESCRIPTION TYPE SIZE FORMAT
    transaction.code BoaCompra´s reference Integer - e.g.: 111181153
    transaction.reference Merchant´s reference String Up to 64 XXX-XXX-XX-XXXXXXXXXX
    transaction.amount Transaction Amount Number - e.g.: 50.0
    transaction.status Current status (see more) String - e.g.: PAID
    transaction.status-reason Reason for status String - e.g.: INVALID_CREDIT_CARD
    transaction.currency Currency transaction String 3 e.g.: BRL
    transaction.country Country transaction String 2 e.g.: BR
    transaction.payer-email Payer email String Up to 60 e.g.: johndoe@email.com
    transaction.date-created Date of creation String - e.g.: 2018-10-10T14:39:32.991217999-03:00

    Tokenization

    When applied to data security, tokenization is the process of substituting a sensitive data element with a non-sensitive equivalent, referred to 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 a transaction, and also allows the merchant to create its own service of recurring payment.

    How does it work?

    1 - Merchant submits the payment info to /transactions using the parameter charge[].payment-info.save as true.

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

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

    4 - The merchant stores the payment-method object.

    5 - The transaction status is changed to COMPLETE.

    6 - The merchant can now use charge[].payment-info.code to create future transactions for the same customer.

    Step 1: Saving the Payment Method

    The merchant creates a payment request that demands the payment method to be saved.

    Request

    Example of a request using credit card tokenization

    {
      "transaction": {
        "reference": "REF-XXX-1234567890",
        "project-number": 1,
        "country": "BR",
        "currency": "BRL",
        "checkout-type": "direct",
        "notification-url": "https://billing.checkout.com/processing",
        "language": "pt-BR"
      },
      "charge": [
        {
          "amount": 100.00,
          "payment-method": {
            "type": "credit-card",
            "sub-type": "mastercard"
          },
          "payment-info": {
            "installments": 3,
            "token": "eyJkbmEiOiI2NzY3YzAxNDEzNGM0NTc4ODg0ZjU2MjdmYTI0ZGVhZiIsImlwIjoiMjAwLjIyMS4xMzAuNDkiLCJkZiI6ImNmYWI3MDcxMDJlZDQ4MjU4MzJhNmY2MDBhNWZjZjc2In0=",
            "save": true
          }
        }
      ],
      "payer": {
        "name": "John Doe",
        "email": "johndoe@email.com",
        "birth-date": "1988-12-25",
        "phone-number": "+5511991234556",
        "document": {
          "type": "CPF",
          "number": "31192071280"
        },
        "address": {
          "street": "Rua Teste",
          "number": "1102",
          "complement": "AP 10",
          "district": "Bairro Teste",
          "state": "PR",
          "city": "Maringá",
          "country": "BR",
          "zip-code": "87030010"
        },
        "ip": "200.221.118.80"
      },
      "shipping": {
        "cost": 0,
        "address": {
          "street": "Rua dos Bobos",
          "number": "1102",
          "complement": "AP 0",
          "district": "Vinicius de Moraes",
          "state": "PR",
          "city": "Maringá",
          "country": "BR",
          "zip-code": "87030010"
        }
      },
      "cart": [
        {
          "quantity": 1,
          "description": "Calça Jeans",
          "category": "Collectibles",
          "type": "physical",
          "unit-price": 1
        }
      ]
    }
    

    Response

    Example of a response containing a payment method

    {
      "transaction": {
        "code": 99481144,
        "reference": "REF-XXX-1234567890",
        "amount": 100,
        "status": "PENDING",
        "currency": "BRL",
        "country": "BR",
        "payer-email": "johndoe@email.com",
        "date-created": "2018-10-09T15:16:31.76093422-03:00"
      },
      "payment-methods": [
        {
          "code": "5B990EBB79F54E65B752EC555BD3A9B6",
          "credit-card": {
            "brand": "mastercard",
            "masked-number": "************5099",
            "expiration-date": "2021-12"
          },
          "date-created": "2018-10-09T15:16:32.508735399-03:00"
        }
      ]
    }
    

    Step 2: Merchant Stores the Payment Method

    The merchant stores the following object in other to have features like one-click buying, retry sending a transaction, among others alike. This payment method code can only be used to create a new transaction after the transaction's status is changed to COMPLETE.

    Example of a payment method that the merchant can store on their side

    {
      "code": "5B990EBB79F54E65B752EC555BD3A9B6",
      "credit-card": {
        "brand": "mastercard",
        "masked-number": "************5099",
        "expiration-date": "2021-12"
      },
      "date-created": "2018-10-09T15:16:32.508735399-03:00"
    }
    

    Step 3: Merchant Uses the Saved Payment Method

    The merchant uses the stored payment method to create a new transaction for the same customer

    Example of a request using the stored payment method

    {
      "transaction": {
        "reference": "REF-XXX-1234567891",
        "project-number": 1,
        "country": "BR",
        "currency": "BRL",
        "checkout-type": "direct",
        "notification-url": "https://billing.checkout.com/processing",
        "language": "pt-BR"
      },
      "charge": [
        {
          "amount": 100.00,
          "payment-method": {
            "type": "credit-card",
            "sub-type": "mastercard"
          },
          "payment-info": {
            "installments": 3,
            "code": "5B990EBB79F54E65B752EC555BD3A9B6"
          }
        }
      ],
      "payer": {
        "name": "John Doe",
        "email": "johndoe@email.com",
        "birth-date": "1988-12-25",
        "phone-number": "+5511991234556",
        "document": {
          "type": "CPF",
          "number": "31192071280"
        },
        "address": {
          "street": "Rua Teste",
          "number": "1102",
          "complement": "AP 10",
          "district": "Bairro Teste",
          "state": "PR",
          "city": "Maringá",
          "country": "BR",
          "zip-code": "87030010"
        },
        "ip": "200.221.118.80"
      },
      "shipping": {
        "cost": 0,
        "address": {
          "street": "Rua dos Bobos",
          "number": "1102",
          "complement": "AP 0",
          "district": "Vinicius de Moraes",
          "state": "PR",
          "city": "Maringá",
          "country": "BR",
          "zip-code": "87030010"
        }
      },
      "cart": [
        {
          "quantity": 1,
          "description": "Calça Jeans",
          "category": "Collectibles",
          "type": "physical",
          "unit-price": 1
        }
      ]
    }
    

    Available Brands

    PostPay/Cash/ATM

    PostPay in general are cash-based payments. This payment method gives the customer the possibility to select the product online, and pay for it later in a designated establishment. The delay between the initial order and the consumer completing their payment means that this does not always suit perishable goods and time-sensitive purchases. This is a very popular payment type throughout Latin America, with almost every country having its own version and peculiarities.

    Available Payment Methods

    Payment Method Countries Refunds Recurring Chargebacks Type Sub-type
    Boleto Bancário BR Yes No No postpay boleto

    Brazil

    Boleto Bancário

    Type: postpay

    Sub-type: boleto

    Boleto Bancário or just Boleto is a financial document issued by a bank that enables the customer to pay the exact specified amount to the receiving party.

    Boleto always includes:

    S 318cbdb4bdf728f4a39197c79d7c5d62ef9d03ac8bccc047dec24f4478bdc509 1538161434520 print image+jhtml++12401754+

    The customer can pay a boleto at an ATM, a bank, an approved facility, or through their bank's online banking system. After the boleto is paid, the bank sends to BoaCompra a file confirming the payment. The confirmation is received in one business day. However, it may require up to 3-6 business days after the payment date in case of holidays. If a boleto has not been paid before the due date, the corresponding transaction remains open at BoaCompra MyAccount for 8 days. When a Boleto payment is submitted, the BoaCompra payments platform returns a response with an URL in the payment-url field. The URL points to a page with an image of the boleto that the customer needs to proceed with their payment. The merchant can redirect the customer to that URL so that they can complete the payment at an ATM, a bank or an approved facility.

    Workflow

    Direct Checkout Workflow

    1 - Customer fills and submits all necessary payment information to the 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 the merchant.

    4 - The merchant displays the Boleto to the customer using the Boacompra Boleto URL or provides the digitable-line to the customer.

    Creating a Boleto Payment

    To create a boleto payment method, make a POST request as the example.

    Request

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

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

    Method: POST

    Example of a request using boleto

    {
      "transaction": {
        "reference": "REF-XXX-1234567890",
        "project-number": 1,
        "country": "BR",
        "currency": "BRL",
        "checkout-type": "direct",
        "notification-url": "https://billing.checkout.com/processing",
        "language": "pt-BR"
      },
      "charge": [
        {
          "amount": 100.00,
          "payment-method": {
            "type": "postpay",
            "sub-type": "boleto"
          }
        }
      ],
      "payer": {
        "name": "John Doe",
        "email": "johndoe@email.com",
        "birth-date": "1988-12-25",
        "phone-number": "+5511991234556",
        "document": {
          "type": "CPF",
          "number": "31192071280"
        },
        "address": {
          "street": "Rua dos Bobos",
          "number": "1102",
          "complement": "AP 302",
          "district": "Vinicius de Moraes",
          "state": "PR",
          "city": "Maringá",
          "country": "BR",
          "zip-code": "87030010"
        },
        "ip": "200.221.118.80"
      },
      "shipping": {
        "cost": 0,
        "address": {
          "street": "Rua dos Bobos",
          "number": "1102",
          "complement": "AP 302",
          "district": "Vinicius de Moraes",
          "state": "PR",
          "city": "Maringá",
          "country": "BR",
          "zip-code": "87030010"
        }
      },
      "cart": [
        {
          "quantity": 1,
          "description": "Calça Jeans",
          "category": "Collectibles",
          "type": "physical",
          "unit-price": 1
        }
      ]
    }
    

    Request Parameter List

    Parameter Description Type Size Mandatory
    transaction Set of general transaction's information Object - Yes
    transaction.reference Merchant transaction identifier String Up to 64 Yes
    transaction.project-number Merchant project identifier. Default value is 1 Integer - No
    transaction.country Country of the payment. Accepts only BR String 2 Yes
    transaction.checkout-type Checkout type of the transaction. Accepts only direct String - Yes
    transaction.notification-url URL (must bind ports 80 or 443) used to send transaction statuses changes notifications by HTTP String Up to 200 Yes
    transaction.language Language used. Accepts pt-BR, en-US, es-ES, pt-PT and tr-TR String 5 Yes
    charge[] Set of payments. Currently accepting just one (1) payment Array 1 Yes
    charge[].amount Amount of the transaction. Cents are separated by dot, with two (2) decimal places. Number Min of 0.01 Yes
    charge[].payment-method.type Payment Method type (credit-card, postpay or e-wallet) String - Yes
    charge[].payment-method.sub-type Payment Method sub-type. Available payment methods (see more) String - Yes
    payer Set of customer's information Object - Yes
    payer.name Customer name String Up to 50 Yes
    payer.email Customer e-mail String Up to 60 Yes
    payer.birth-date Customer birth date. ISO-8601 Pattern (YYYY-MM-DD) String - No
    payer.phone-number Customer phone number. e.g (+5544999884455) String - No
    payer.document.type Customer document Type. accepts: cpf and cnpj String - Yes
    payer.document.number Customer identification document. No special characters allowed. String - Yes
    payer.ip Customer IP. accepts Ipv4 String - Yes
    payer.address Customer address object Object - No [1]
    payer.address.street Customer address street String 3-160 Yes
    payer.address.number Customer address number String 1-20 Yes
    payer.address.complement Customer address complement String 5-40 No
    payer.address.district Customer address district String 4-60 Yes
    payer.address.state Customer address state or province String 2 Yes
    payer.address.city Customer address city String 3-60 Yes
    payer.address.country Customer address country (country iso 2) String 2 Yes
    payer.address.zip-code Customer address zip code String 8 Yes
    shipping Set of information that will be used to deliver the items in cart (see more) Object - No [1]
    shipping.cost Shipping cost Number - Yes
    shipping.address.street Shipping address street String 3-160 Yes
    shipping.address.number Shipping address number String 1-20 Yes
    shipping.address.complement Shipping address complement String 5-40 No
    shipping.address.district Shipping address district String 4-60 Yes
    shipping.address.state Shipping address state or Province String 2 Yes
    shipping.address.city Shipping address city String 3-60 Yes
    shipping.address.country Shipping address country (country iso 2) String 2 Yes
    shipping.address.zip-code Shipping address zip Code String 8 Yes
    cart[] Set of items (at least one Item) Array Min of 1 Yes
    cart[].quantity Item quantity Integer Min of 1 Yes
    cart[].description Item description String 1-200 Yes
    cart[].unit-price Price per unit Number Min of 0.01 Yes
    cart[].type Item type (see more) String - Yes
    cart[].category Item category String 1-64 No

    Response

    Example of a response using boleto

    {
      "transaction": {
        "code": 111116875,
        "reference": "REF-XXX-1234567890",
        "amount": 100.00,
        "status": "PENDING",
        "currency": "BRL",
        "country": "BR",
        "payer-email": "johndoe@email.com",
        "date-created": "2018-10-09T11:13:37.54658934-03:00",
        "barcode-number": "03399767800000001009853029700000167460590101",
        "digitable-line": "03399853012970000016874605901011976780000000100",
        "payment-url": "https://payment.boacompra.com/b/OXBJSUwzUUNwSm84aHVlbXdqaXRuQT09"
      }
    }
    

    Response Parameter List

    Property Description Type Size Format
    transaction.code BoaCompra's reference Integer
    transaction.reference Merchant's reference String
    transaction.amount Number
    transaction.status Current status (see more) String
    transaction.currency String 3 ISO 4217, e.g. "BRL"
    transaction.country String 2 ISO 3166-2, e.g. "BR"
    transaction.payer-email Customer e-mail address String
    transaction.date-created Date of creation String ISO-8601, e.g. "2018-10-19T14:38:04.082324056-03:00"
    transaction.barcode-number Barcode numerical representation String 44 e.g.: 10496766600000101508745960000100040003898220
    transaction.digitable-line Digitable line String 47 e.g.: 10498745956000010004400038982203676660000010150
    transaction.payment-url Generated Boleto Url String 64 e.g.: https://payment.boacompra.com/b/clhZYUVTRGZRdUNuKzZwR1grcEZsZz09

    Boleto best practices

    When providing an alternative payment method like Boleto Bancário, it is required to include a confirmation page on the flow. Furthermore, on this page we can include some features to increase the payment method conversion, as well as informing the particularities of the payment method chosen to the customer.

    Confirmation page example

    boleto confirmation image

    1. In Brazil we still have a large population of people without bank accounts. It is recommended always offer to the customer the print Boleto option, with this they can make the payment at an ATM, a bank or an approved facility.
      INFO: To use this feature, use transaction.payment-url included in the response of the boleto transaction.

    2. Brazillian banks Apps and some mobile wallets offer their users the option to make boleto payments scanning the bar codes in their smartphones. Providing the Barcode with a good resolution is a good practice to increase conversion with these users.
      INFO: To use this feature, use transaction.barcode-number included in the response of the boleto transaction and associate it with an open-source library like JsBarcode to generate the barcode image.

    3. It is a good practice to offer the option of copying the payment code. This allows the customer to pay directly on their bank's internet banking. This feature is mandatory if want to increase conversion for mobile users.
      INFO: To use this feature, use transaction.digitable-line included in the response of the boleto transaction.

    e-Wallet

    Digital Wallets or e-Wallets are cards repositories and payment data for online customers. The e-wallets allows customers to use a single sign-in to make purchases on the web.

    Workflow

    1. Customer fills and submits all necessary payment information to the 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 the merchant.

    4. The 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/she will be redirected to Merchant's Fail URL.

    Creating an e-Wallet Payment

    To create an e-wallet payment method, make a POST request as the example.

    Request

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

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

    Method: POST

    Example of a request using e-Wallet

    {
      "transaction": {
        "reference": "REF-XXX-1539093014330",
        "project-number": 1,
        "country": "BR",
        "currency": "BRL",
        "checkout-type": "direct",
        "notification-url": "https://billing.checkout.com/processing",
        "language": "pt-BR",
        "redirect-urls": {
          "success": "https://billing.checkout.com/direct?return=1",
          "fail": "https://billing.checkout.com/direct?cancel=1"
        }
      },
      "charge": [
        {
          "amount": 100.00,
          "payment-method": {
            "type": "e-wallet",
            "sub-type": "pagseguro"
          }
        }
      ],
      "payer": {
        "name": "John Doe",
        "email": "johndoe@email.com",
        "birth-date": "1988-12-25",
        "phone-number": "+5511991234556",
        "document": {
          "type": "CPF",
          "number": "31192071280"
        },
        "address": {
          "street": "Rua dos Bobos",
          "number": "1102",
          "complement": "AP 302",
          "district": "Vinicius de Moraes",
          "state": "PR",
          "city": "Maringá",
          "country": "BR",
          "zip-code": "87030010"
        },
        "ip": "200.221.118.80"
      },
      "shipping": {
        "cost": 0,
        "address": {
          "street": "Rua dos Bobos",
          "number": "1102",
          "complement": "AP 302",
          "district": "Vinicius de Moraes",
          "state": "PR",
          "city": "Maringá",
          "country": "BR",
          "zip-code": "87030010"
        }
      },
      "cart": [
        {
          "quantity": 1,
          "description": "Calça Jeans",
          "category": "Collectibles",
          "type": "physical",
          "unit-price": 1
        }
      ]
    }
    

    Request Parameter List

    Parameter Description Type Size Mandatory
    transaction Set of general transaction's information Object - Yes
    transaction.reference Merchant transaction identifier String Up to 64 Yes
    transaction.project-number Merchant project identifier. Default value is 1 Integer - No
    transaction.country Country of the payment. Accepts only BR String 2 Yes
    transaction.checkout-type Checkout type of the transaction. Accepts only direct String - Yes
    transaction.notification-url URL (must bind ports 80 or 443) used to send transaction status changes notifications by HTTP String Up to 200 Yes
    transaction.language Language used. Accepts pt-BR, en-US, es-ES, pt-PT and tr-TR String 5 Yes
    transaction.redirect-urls Set of URL used after finishing the payment on e-wallet's page Object - Yes
    transaction.redirect-urls.success URL used fater finishing the payment on e-wallet's page String Up to 200 Yes
    transaction.redirect-urls.fail URL used when the customer cancels the process on e-wallet's page String Up to 200 Yes
    charge[] Set of payments. Currently accepting just one payment Array 1 Yes
    charge[].amount Amount of the transaction. Cents are separated by dot, with two (2) decimal places. Number Min of 0.01 Yes
    charge[].payment-method.type Payment Method type (credit-card, postpay or e-wallet) String - Yes
    charge[].payment-method.sub-type Payment Method sub-type. Available payment methods (see more) String - Yes
    payer Set of customer's information Object - Yes
    payer.name Customer name String Up to 50 Yes
    payer.email Customer e-mail String Up to 60 Yes
    payer.birth-date Customer birth date. ISO-8601 Pattern (YYYY-MM-DD) String - No
    payer.phone-number Customer phone number. e.g (+5544999884455) String - No
    payer.document.type Customer document Type. accepts: cpf and cnpj String - Yes
    payer.document.number Customer identification document. No special characters allowed. String - Yes
    payer.ip Customer IP. accepts Ipv4 String - Yes
    payer.address Customer address object Object - No [1]
    payer.address.street Customer address street String 3-160 Yes
    payer.address.number Customer address number String 1-20 Yes
    payer.address.complement Customer address complement String 5-40 No
    payer.address.district Customer address district String 4-60 Yes
    payer.address.state Customer address state or province String 2 Yes
    payer.address.city Customer address city String 3-60 Yes
    payer.address.country Customer address country (country iso 2) String 2 Yes
    payer.address.zip-code Customer address zip code String 8 Yes
    shipping Set of information that will be used to deliver the items in cart (see more) Object - No [1]
    shipping.cost Shipping cost Number - Yes
    shipping.address.street Shipping address street String 3-160 Yes
    shipping.address.number Shipping address number String 1-20 Yes
    shipping.address.complement Shipping address complement String 5-40 No
    shipping.address.district Shipping address district String 4-60 Yes
    shipping.address.state Shipping address state or Province String 2 Yes
    shipping.address.city Shipping address city String 3-60 Yes
    shipping.address.country Shipping address country (country iso 2) String 2 Yes
    shipping.address.zip-code Shipping address zip Code String 8 Yes
    cart[] Set of items (at least one Item) Array Min of 1 Yes
    cart[].quantity Item quantity Integer Min of 1 Yes
    cart[].description Item description String 1-200 Yes
    cart[].unit-price Price per unit Number Min of 0.01 Yes
    cart[].type Item type (see more) String - Yes
    cart[].category Item category String 1-64 No

    Response

    Example of a response using e-Wallet

    {
      "transaction": {
        "code": 111115949,
        "reference": "REF-XXX-15390930143123",
        "amount": 100.00,
        "status": "PENDING",
        "currency": "BRL",
        "country": "BR",
        "payer-email": "johndoe@email.com",
        "date-created": "2018-10-09T10:50:09.422046071-03:00",
        "payment-url": "https://gateway.boacompra.com/ewallet.php?token=B47818A1788C8DF39ECB"
      }
    }
    

    Response Parameter List

    Property Description Type Size Format
    transaction.code BoaCompra's reference Integer
    transaction.reference Merchant's reference String
    transaction.amount Number
    transaction.status Current status (see more) String
    transaction.currency String 3 ISO 4217, e.g. "BRL"
    transaction.country String 2 ISO 3166-2, e.g. "BR"
    transaction.payer-email Customer e-mail address String
    transaction.date-created Date of creation String ISO-8601, e.g. "2018-10-19T14:38:04.082324056-03:00"
    transaction.payment-url e-Wallet's page URL String

    Available Payment Methods

    Payment Method Countries Refunds Recurring Chargebacks Type Sub-type
    PagSeguro BR Yes No Yes e-wallet pagseguro
    PayPal BR Yes No Yes e-wallet paypal

    Brazil

    PagSeguro

    Type: e-wallet

    Sub-type: pagseguro

    PagSeguro wallet gives your customers a simplified and secure checkout experience that allows them to make payments using credit cards issued in Brazil with installments. The service provide to customer make purchases adding their card of choice, using saved credit cards or available account balance.

    S 828449aae186f68f64b1deed7914b7b913048330dd743ab7cd4a7b413c872713 1538512697707 ps flow

    PayPal

    Type: e-wallet

    Sub-type: paypal

    PayPal is an e-wallet solution popular worldwide. The service allows the customer to make purchases, add their card of choice, using saved credit cards or available account balance.

    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 environment 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. Contact your Account Manager if you don't have the credentials.

    Tokenization Feature

    When using charge[].payment-method.token and charge[].payment-info.save 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 charge[].payment-method.code instead of charge[].payment-method.token on sandbox environment, use the parameter code as 123E4567E89B12D3A456426655440000 which is the same one returned in the payment-method object response. Any other payment-method-code will return an error 210605:charge_[0-9]_payment_info_code_not_found.

    Sandbox Testing Rules

    These are the rules for simulating payment statuses in transactions using payment with Raw Credit Card Data in the Sandbox.

    STATUS RULE DESCRIPTION
    PAID charge.amount < 50.00 The return is obtained by informing in the POST a charge.amount value less than 50.00
    REJECTED 50.00 < charge.amount < 100.00 The return is obtained by informing in the POST a charge.amount value greater than 50.00 and less than 100.00
    PENDING charge.amount > 100.00 The return is obtained by informing in the POST a charge.amount value greater than 100.00

    Payment method object pre-configured

    {
        "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": 210605,
            "description": "charge_0_payment_info_code_not_found"
        ]
    }
    

    Errors

    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

    Headers

    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

    Transaction API

    Code Key Description
    210101 transaction_missing Transaction is missing
    210102 transaction_invalid Transaction is invalid
    210103 transaction_reference_missing Transaction reference is missing
    210104 transaction_reference_invalid Transaction reference is invalid (special characters) or was already used
    210105 transaction_project_number_missing Transaction project number is missing
    210106 transaction_project_number_invalid Transaction project number is invalid
    210107 transaction_country_missing Transaction country is missing
    210108 transaction_country_invalid Transaction country is invalid. Should be BR
    210109 transaction_currency_missing Transaction currency is missing
    210110 transaction_currency_invalid Transaction currency is invalid. Should be BRL
    210111 transaction_checkout_type_missing Transaction checkout type is missing
    210112 transaction_checkout_type_invalid Transaction checkout type is invalid. Should be direct
    210113 transaction_notification_url_missing Transaction notification is missing
    210114 transaction_notification_url_invalid Transaction notification is not a valid URL
    210115 transaction_redirect_urls_missing Transaction redirect urls is missing
    210116 transaction_redirect_urls_invalid Transaction redirect urls is invalid*
    210117 transaction_language_missing Transaction language is missing
    210118 transaction_language_invalid Transaction language is invalid. Valid values: pt-BR, pt-PT, en-US, es-ES, tr-TR
    210119 transaction_redirect_urls_success_missing Transaction redirect urls is missing
    210120 transaction_redirect_urls_success_invalid Transaction redirect urls is invalid URL*
    210121 transaction_redirect_urls_fail_missing Transaction redirect urls is missing
    210122 transaction_redirect_urls_fail_invalid Transaction redirect urls is invalid URL*
    210201 charge_missing Charge is missing
    210202 charge_invalid Charge is invalid
    210203 charge_[0‑9]_amount_missing Charge amount is missing
    210204 charge_[0‑9]_amount_invalid Charge amount is invalid
    210205 charge_[0‑9]_payment_method_missing Charge payment method is missing
    210206 charge_[0‑9]_payment_method_invalid Charge payment method is invalid
    210207 charge_[0‑9]_payment_method_type_missing Charge payment method type is missing
    210208 charge_[0‑9]_payment_method_type_invalid Charge payment method type is invalid. Valid values: credit-card, postpay or e-wallet
    210209 charge_[0‑9]_payment_method_sub_type_missing Charge payment method sub type is missing
    210210 charge_[0‑9]_payment_method_sub_type_invalid Charge payment method sub type is invalid. Valid values: available credit-card brands, boleto, pagseguro or paypal
    210211 charge_[0‑9]_payment_info_missing Charge payment info is missing
    210212 charge_[0‑9]_payment_info_invalid Charge payment info is invalid
    210213 charge_[0‑9]_payment_info_installments_missing Charge payment info installments is missing
    210214 charge_[0‑9]_payment_info_installments_invalid Charge payment info installments is invalid
    210215 charge_[0‑9]_payment_info_token_missing Charge payment info token is missing
    210216 charge_[0‑9]_payment_info_token_invalid Charge payment info token is invalid. Issue generating token or not accepted card brand See more
    210217 charge_[0‑9]_payment_info_save_missing Charge payment info save is missing
    210218 charge_[0‑9]_payment_info_save_invalid Charge payment info save is invalid
    210219 charge_[0‑9]_payment_info_code_missing Charge payment info is missing
    210220 charge_[0‑9]_payment_info_code_invalid Charge payment info is invalid. Payment method code format doesn't match (alphanum, 32 chars)
    210221 charge_[0‑9]_payment_info_credit_card_invalid Charge payment info credit card is invalid. Validation of fields mandatory (CVV and Expiration Date) based on the rules of each brand
    210222 charge_[0‑9]_payment_info_credit_card_number_invalid Charge payment info credit card number is invalid. Validation of the credit card number based on Luhn's algorithm
    210223 charge_[0‑9]_payment_info_credit_card_cvv_invalid Charge payment info credit card cvv is invalid. Credit card cvv format doesn't match (string, 3-4 characters)
    210224 charge_[0‑9]_payment_info_credit_card_expiration_date_invalid Charge payment info credit card expiration date is invalid. credit card expiration date format doesn't match (string, format:'YYYY-MM')
    210301 payer_missing Payer is missing
    210302 payer_invalid Payer is invalid
    210303 payer_name_missing Payer name is missing
    210304 payer_name_invalid Payer name is invalid. Payer name does not match the requirement
    210305 payer_email_missing Payer email is missing
    210306 payer_email_invalid Payer email is invalid. Payer email does not match the requirement
    210307 payer_birth_date_missing Payer birth date is missing
    210308 payer_birth_date_invalid Payer birth date is invalid
    210309 payer_ip_missing Payer ip is missing
    210310 payer_ip_invalid Payer ip is invalid
    210311 payer_phone_number_missing Payer phone number is missing
    210312 payer_phone_number_invalid Payer phone number is invalid
    210313 payer_document_missing Payer document is missing
    210314 payer_document_invalid Payer document is invalid
    210315 payer_document_type_missing Payer document type is missing
    210316 payer_document_type_invalid Payer document type is invalid. Valid values: CPF or CNPJ
    210317 payer_document_number_missing Payer document number is missing
    210318 payer_document_number_invalid Payer document number is invalid. Should be a valid document
    210319 payer_address_missing Payer address is missing. Required when Cart has an item of type physical
    210320 payer_address_invalid Payer address is invalid
    210321 payer_address_street_missing Payer address street is missing
    210322 payer_address_street_invalid Payer address street is invalid. Should have 3-160 characters
    210323 payer_address_number_missing Payer address number is missing
    210324 payer_address_number_invalid Payer address number is invalid. Should have 1-20 characters
    210325 payer_address_complement_missing Payer address complement is missing
    210326 payer_address_complement_invalid Payer address complement is invalid. Should have 5-40 characters
    210327 payer_address_district_missing Payer address district is missing
    210328 payer_address_district_invalid Payer address district is invalid. Should have 4-60 characters
    210329 payer_address_state_missing Payer address state is missing
    210330 payer_address_state_invalid Payer address state is invalid. Should have 2 characters (e.g.: SP)
    210331 payer_address_city_missing Payer address city is missing
    210332 payer_address_city_invalid Payer address city is invalid. Should have 3-60 characters
    210333 payer_address_country_missing Payer address country is missing
    210334 payer_address_country_invalid Payer address country is invalid. Should have 2 characters (e.g.: BR)
    210335 payer_address_zip_code_missing Payer address zip code is missing
    210336 payer_address_zip_code_invalid Payer address zip code is invalid. Should have 8 characters
    210401 shipping_missing Shipping is missing. Required when Cart has an item of type physical
    210402 shipping_invalid Shipping is invalid
    210403 shipping_cost_missing Shipping cost is missing
    210404 shipping_cost_invalid Shipping cost is invalid
    210405 shipping_address_missing Shipping address is missing
    210406 shipping_address_invalid Shipping address is invalid
    210407 shipping_address_street_missing Shipping address street is missing
    210408 shipping_address_street_invalid Shipping address street is invalid. Should have 3-160 characters
    210409 shipping_address_number_missing Shipping address number is missing
    210410 shipping_address_number_invalid Shipping address number is invalid. Should have 1-20 characters
    210411 shipping_address_complement_missing Shipping address complement is missing
    210412 shipping_address_complement_invalid Shipping address complement is invalid. Should have 5-40 characters
    210413 shipping_address_district_missing Shipping address district is missing
    210414 shipping_address_district_invalid Shipping address district is invalid. Should have 4-60 characters
    210415 shipping_address_state_missing Shipping address state is missing
    210416 shipping_address_state_invalid Shipping address state is invalid. Should have 2 characters (e.g.: SP)
    210417 shipping_address_city_missing Shipping address city is missing
    210418 shipping_address_city_invalid Shipping address city is invalid. Should have 3-60 characters
    210419 shipping_address_country_missing Shipping address country is missing
    210420 shipping_address_country_invalid Shipping address country is invalid. Should have 2 characters (e.g.: BR)
    210421 shipping_address_zip_code_missing Shipping address zip code is missing
    210422 shipping_address_zip_code_invalid Shipping address zip code is invalid. Should have 8 characters
    210501 cart_missing Cart is missing
    210502 cart_invalid Cart is invalid
    210503 cart_[0‑9]_description_missing Cart description is missing
    210504 cart_[0‑9]_description_invalid Cart description is invalid. Should have 1-200 characters
    210505 cart_[0‑9]_category_missing Cart category is missing
    210506 cart_[0‑9]_category_invalid Cart category is invalid. Shoud have 1-64 characters
    210507 cart_[0‑9]_quantity_missing Cart quantity is missing
    210508 cart_[0‑9]_quantity_invalid Cart quantity is invalid. Should be grather than 1
    210509 cart_[0‑9]_unit_price_missing Cart unit price is missing
    210510 cart_[0‑9]_unit_price_invalid Cart unit price is invalid. Should be greather than 0.01
    210511 cart_[0‑9]_type_missing Cart type is missing
    210512 cart_[0‑9]_type_invalid Cart type is invalid. Valid values: digital, physical, service or subscription
    210601 unavailable_payment_method The choosen payment method is not avaliable
    210602 payment_exceed_limits Payment exceed the limit purchase (only for Brazil, R$ 10000) by Payer Document
    210603 payer_blacklisted Payer is blacklisted by our risk analysis and must contact Boacompra's Customer Support
    210604 payer_blacklisted_by_psp Payer is blacklisted by our PSP and must contact Boacompra's Customer Support
    210605 charge_[0‑9]_payment_info_code_not_found Payment method was not found for the payment method code given or is not active