Transaction API

📘
This is the latest documentation
This documentation you are reading is for the latest version.
If you are integrated with the old direct checkout integration (v1), please find its documentation here.

Header Specification

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

Example headers

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

🚧
Notice that to create a direct request payment the accept header is slightly different because of its version:

older version: Accept: application/vnd.boacompra.com.v1+json; charset=UTF-8

latest version: Accept: application/vnd.boacompra.com.v2+json; charset=UTF-8

How to Generate the Authorization Header

For POST requests:

The authorization header is formed by merchant-id, secret-key, URL Path (e.g. /transactions) and Content MD5 of the body request previously generated.

Generate hmac-sha256 of URL Path concatenated with Content MD5 using secret key.

The format is merchant-id:hmac-sha256((URL Path + 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;

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)

For GET requests:

Authorization header for GET requests is formed by merchant-id, secret-key, URL Path and URL Query String.
Generate hmac-sha256 of URL Path (e.g. /transactions) + URL Query
String (e.g. ?initial_date=yyyy-mm-dd) using secret key.

The format is merchant-id:hmac-sha256(URL Path + URL Query String, secret-key)

Merchant-id and Secret-key will be provided by PagSeguro 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;

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')

General Header

For all API requests, it is mandatory to format the header as described below:

Field	Mandatory	Description
Accept	Yes	API version, data type and encoding
Accept-Language	No	Input language. Default value is EN_US
Authorization	Yes	SHA256 generated with a secret key to guarantee request authenticity. Format: store-id:hash To generate the authorization, besides the store-id, it is required: secret-key, URL Path (e.g. /transactions), URL Query String (e.g. ?initial_date=yyyy-mm-dd) and Content MD5 (the latter only for POST requests). The hash is generated using hmac-sha256-algorithm (secret-key, (URL Path + URL Query String + Content MD5)).
Content-Type	Yes	Only Application/json is accepted

Header example

GET / HTTP 1.1
Host: api.boacompra.com
Accept: en-US
Accept-Language: application/vnd.boacompra.com.v1+json; charset=UTF-8
Authorization: 123:ba567109f868df40c7cda9c5563bf2a9cdcb8b6bc68cac4a60091fa519352289
Content-Type: application/json

Example for POST requests

public class Header {
    private String secretKey = "ABCDE0987";
    private String storeId = "10";
    private String contentMD5;
    private String httpVerb;

    public Header(String content, String url) throws NoSuchAlgorithmException, MalformedURLException, UnsupportedEncodingException {
        this.setContentMd5(content);
        this.setHttpVerb(new URL(url));
    }

    private void setHttpVerb(URL url) {
        this.httpVerb = url.getPath() + (url.getQuery() != null ? '?' + url.getQuery() : "");
    }

    private void setContentMd5(String content) throws NoSuchAlgorithmException, UnsupportedEncodingException {
        if(StringUtils.isBlank(content)){
            this.contentMD5 = "";
            return;
        }

        MessageDigest md = MessageDigest.getInstance("MD5");
        byte messageDigest[] = md.digest(content.getBytes("UTF-8"));
        this.contentMD5 = new BigInteger(1, messageDigest).toString(16);

        while (this.contentMD5.length() < 32) {
            this.contentMD5 = "0" + this.contentMD5;
        }
    }

    private String generateAuthorization() throws NoSuchAlgorithmException, InvalidKeyException, UnsupportedEncodingException {
        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")));
    }

    public HashMap<String,String> generateHeader() throws InvalidKeyException, NoSuchAlgorithmException, UnsupportedEncodingException {
        HashMap<String, String> headers = new HashMap<>();
        headers.put("Accept", "application/vnd.boacompra.com.v2+json; charset=UTF-8");
        headers.put("Content-Type", "application/json");
        headers.put("Authorization", this.storeId+':'+this.generateAuthorization());

        return headers;
    }
}

String content = "{\"transaction-id\":123456789,\"amount\":10.57,\"notify-url\":\"https://virtualstore.com/notifications\",\"test-mode\":0}";

Header header = new Header(content, "https://api.boacompra.com/boa-compra-end-point");
HashMap<String, String> headerMap = header.generateHeader();

System.out.println(Arrays.asList(headerMap));

<?php

class header
{
  private $secretKey = 'ABCDE0987';
  private $storeId = 10;

  public function __construct($content, $url)
  {
    $this->setContentMd5($content);
    $this->setHttpVerb($url);
  }

  private function setContentMd5($content)
  {
    $this->contentMd5 = md5($content);
  }

  private function setHttpVerb($url)
  {
    if (parse_url($url, PHP_URL_QUERY)) {
      $this->httpVerb = parse_url($url, PHP_URL_PATH).'?'.parse_url($url, PHP_URL_QUERY);
    } else {
      $this->httpVerb = parse_url($url, PHP_URL_PATH);
    }
  }

  private function generateAuthorization()
  {
    return hash_hmac(
      'sha256',
      $this->httpVerb . $this->contentMd5,
      $this->secretKey
    );
  }

  public function generateHeader()
  {
    $headers = array(
      'Accept' => 'application/vnd.boacompra.com.v2+json; charset=UTF-8',
      'Content-Type' => 'application/json',
      'Authorization' => $this->storeId . ':' . $this->generateAuthorization()
    );
    return $headers;
  }
}

echo 'POST EXAMPLE <br />';
$content = '{"transaction-id":123456789,"amount":10.57,"notify-url":"https://virtualstore.com/notifications","test-mode":0}';

$headerPost = new header($content, 'https://api.boacompra.com/boa-compra-end-point');
print_r($headerPost->generateHeader());

require 'uri'
require 'openssl'
require 'digest/md5'

class Header

  SECRET_KEY = 'ABCDE0987'
  STORE_ID = 10

  attr_reader :contentMD5, :httpVerb

  def initialize(content, url)
    setContentMD5(content)
    setHttpVerb(url)
  end

  private
  def setContentMD5(content)
    @contentMD5 = Digest::MD5.hexdigest(content).to_s
  end

  private
  def getQueryString(url)
    uri = URI(url)
    url.to_s.empty? || uri.query.nil? ? '' : '?' + uri.query
  end

  private
  def setHttpVerb(url)
    uri = URI::parse(url)
    @httpVerb = getQueryString(url).to_s.empty? ? uri.path : uri.path + "?" + getQueryString(url)
  end

  private
  def generateAuthorization()
    OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), SECRET_KEY, @httpVerb + @contentMD5)
  end

  public
  def generateHeader()
    headers = {
      "Accept"           => 'application/vnd.boacompra.com.v2+json; charset=UTF-8',
      "Content-Type"     => 'application/json',
      "Authorization"    => STORE_ID.to_s + ":" + generateAuthorization()
    }
    headers
  end
end

puts '<pre>POST EXAMPLE <br />'
content = '{"transaction-id":123456789,"amount":10.57,"notify-url":"https://virtualstore.com/notifications","test-mode":0}';
headerGet = Header.new(content, 'https://api.boacompra.com/boa-compra-end-point')
puts headerGet.generateHeader()

# Python 2.7
from urlparse import urlparse
import hashlib
import hmac
import md5

class Header:

  __secretKey = '123'
  __storeId = 10

  def __init__(self, content, url):
    self.__setHttpVerb(url)
    self.__setContentMd5(content)

  def __setHttpVerb(self, url):
    urlParsed = urlparse(url)
    self.__httpVerb = urlParsed.path + urlParsed.query

  def __setContentMd5(self, content):
    self.__contentMd5 = md5.new(content).hexdigest()

  def __generateAuthorization(self):
    return hmac.new(
      self.__secretKey,
      self.__httpVerb + self.__contentMd5,
      hashlib.sha256
    ).hexdigest()

  def generateHeader(self):
    return {
      'Accept': 'application/vnd.boacompra.com.v2+json; charset=UTF-8',
      'Content-Type': 'application/json',
      'Authorization': str(self.__storeId) + ':' + self.__generateAuthorization()
    }

from Header import Header

content = '{"transaction-id":123456789,"amount":10.57,"notify-url":"https://virtualstore.com/notifications","test-mode":0}'
url = 'https://api.boacompra.com/boa-compra-end-point'

a = Header(content, url)
print a.generateHeader()

# Python 3.x
from urllib.parse import urlparse
import hashlib
import hmac

class Header:

  __secretKey = '123'
  __storeId = 10

  def __init__(self, content, url):
    self.__setHttpVerb(url)
    self.__setContentMd5(content)

  def __setHttpVerb(self, url):
    urlParsed = urlparse(url)
    self.__httpVerb = urlParsed.path + urlParsed.query

  def __setContentMd5(self, content):
    self.__contentMd5 = hashlib.md5(content.encode()).hexdigest()

  def __generateAuthorization(self):
    authContent = self.__httpVerb + self.__contentMd5

    return hmac.new(
      self.__secretKey.encode(),
      authContent.encode(),
      hashlib.sha256
    ).hexdigest()

  def generateHeader(self):
    return {
      'Accept': 'application/vnd.boacompra.com.v2+json; charset=UTF-8',
      'Content-Type': 'application/json',
      'Authorization': str(self.__storeId) + ':' + self.__generateAuthorization()
    }

from Header import Header

content = '{"transaction-id":123456789,"amount":10.57,"notify-url":"https://virtualstore.com/notifications","test-mode":0}'
url = 'https://api.boacompra.com/boa-compra-end-point'

a = Header(content, url)
print(a.generateHeader())

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

📘This is the latest documentation

Header Specification

Example headers

🚧

How to Generate the Authorization Header

Example authorization for POST requests

Example authorization for GET requests

General Header

Header example

Example for POST requests

Creating Transactions

Expected Response Headers

📘
This is the latest documentation