Direct API

❗️

This documentation is deprecated

The documentation you are reading is for the older checkout integration, v1.
IIf you want to read the documentation for the latest version, click here.

Credit Card

Direct API Credit Card Workflow

3334

How it Works

  1. The merchant loads PagSeguro 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 PagSeguro 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. PagSeguro creates an order and returns the status transaction and ID to merchant.

  7. The Merchant returns the transation status to customer.

📘

When the merchant has the customer's credit card (payment-method object) saved in its side the first step is not necessary and the parameter paymet-method.code (as payment-method-code) must be used instead of direct-token parameter.

Including Direct API 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 PagSeguro Payment API.

To include the Direct API 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 API 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

PropertyTypeValue
creditCardstringCredit card number
cvvstringCredit card CVV
expirationobjectObject with expiration data
expiration.monthstringCredit card expiration month (2 characters)
expiration.yearstringCredit 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.

🚧

ATTENTION

We highly recommend to instantiate the payment object as soon as possible after loads the PagSeguro's javascript file. Otherwise, we cannot be sure that all dependecies were loaded successfuly before charging the customer and unknown errors can be triggered, difficulting the payment flow. In case of any doubts, please get in touch with our B2B support.

<!DOCTYPE html>

<!-- This html script must be used into a configured virtual host in your Web Server -->

<html>
    <head>
        <meta charset="utf-8">

        <title>PagSeguro Direct API 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.international.pagseguro.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.international.pagseguro.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.international.pagseguro.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:

  • Get the credit card brand.
  • Obtain the installment options by brand, country, amount and currency.

Or

  • Get the brand and installment options in the same request.

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.

📘

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

Method: GET

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.

📘

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

Method: GET

List of Parameters:

ParameterDescriptionTypeMandatory
brandName of BrandStringYes
countryCountry of PaymentString (Limit 2)Yes
amountValue of orderDoubleYes
currencyCurrency of orderString (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).

📘

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

Method: GET

List of Parameters:

ParameterDescriptionTypeMandatory
binCredit Card BIN (first six digits of the card)Integer NumberYes
countryCountry of PaymentString (Limit 2)Yes
amountValue of orderDoubleYes
currencyCurrency of orderString (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 - PagSeguro creates a unique token (payment-method.code) and maps onto the payment-method object reponse.

3 - PagSeguro 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.

Considerations about tokenization:

  • Tokenization feature can only be used with credit card payment type.
  • The payment-method.code can only be used after the transaction status is changed to COMPLETE.
  • The payment-method.code can only be used with the same customer email it was generated, otherwise it will cause an error.
  • If the merchant tries to save the same credit card for the same email twice, the payment method object won't be returned in the response body.

Available Brands

  • American Express American Express
  • Diners Diners
  • Elo Elo
  • HiperCard HiperCard
  • MasterCard MasterCard
  • Visa Visa

Boleto

Direct API Boleto Workflow

3335

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. PagSeguro creates an order and returns the transaction code, Boleto URL and barcode number to merchant.

  4. Merchant displays the Boleto to customer using the PagSeguro 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. PagSeguro creates an order and returns the Transaction Code and Payment URL to merchant.

  4. Merchant redirects the customer to PagSeguro'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

FieldDescriptionMandatory
AcceptAPI version, data type and encodingYes
AuthorizationAuthorizationYes
Content-TypeOnly Application/json is acceptedYes

Example headers

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

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

Creating Transactions

📘

Base URL for Production

https://api.boacompra.com/transactions

Method: POST

🚧

Base URL for Sandbox

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

Method: POST

Request Data

ParameterDescriptionTypeMandatory
transaction.direct-tokenToken containing credit card encrypted data, generated by Direct API JavaScript APIStringNo[1]
transaction.payment-method-codeToken which represents a payment method previously saved and already activated. Alphanumeric of 32 charactersStringNo
transaction.project-numberMerchant Project Identifier. Default value is 1Integer NumberNo
transaction.typeType of the transaction. Accepts only directStringYes
transaction.descriptionDescription of the transaction. Limit of 200 characteres.StringYes
transaction.payment-typeType of the payment. Accepts credit_card, boleto, pagseguro and paypalStringYes
transaction.countryCountry of the payment. Accepts only BRStringYes
transaction.currencyCurrency of the transaction. Accepts only BRLStringYes
transaction.amountAmount of the transaction. Separating cents by dot, with two decimal placesInteger NumberYes
transaction.referenceMerchant Transaction Identifier. Limit of 64 charactersStringYes
transaction.notify-urlURL (must bind ports 80 or 443) used to send transaction statuses changes notifications by HTTPStringYes
transaction.languageLanguage used. Accepts pt-BR, en-US, es-ES, pt-PT and tr-TRStringYes
transaction.installmentsInstallments quantityInteger NumberNo[2]
transaction.save-payment-methodUsed to save payment method for future transactions. See moreBooleanNo
transaction.redirect-success-urlURL used to redirect the payer after making payment by PagSeguro or PayPal, must be a valid URLStringNo[3]
transaction.redirect-fail-urlURL used to redirect the payer when the payment flow (by PagSeguro or PayPal) failsStringNo[3]
payer.namePayer Full Name. Limit of 50 characters, mininum of 2 words. See moreStringYes
payer.emailPayer Email. Limit of 60 characters. See moreStringYes
payer.ipPayer Address IP. Accepts IPv4 or IPv6StringNo[4]
payer.phone-area-codePayer Area code phone. Limit 2 charactersNumberYes
payer.phone-numberPayer Phone number. Limit 8 to 9 charactersNumberYes
payer.document.typePayer Document type. Accepts: CPF and CNPJStringYes
payer.document.numberPayer Document number. Remove special charactersStringYes
payer.birth-datePayer Birth date. ISO-8601 Pattern (YYYY-MM-DD)String DateYes
[1] Mandatory when payment-type is credit_card, except when using the tokenization feature.
[2] Mandatory when payment-type is credit_card.
[3] Mandatory when payment-type is pagseguro or paypal.
[4] Mandatory when payment-type is boleto, pagseguro or paypal.

The barcode-number response parameter could be used to generate and display the barcode in the own merchant website.
It's in the Interleaved 2 of 5 (ITF) pattern, used by Brazilian Banks.
Could be used the open-source library JsBarcode to generate the barcode image.
The digitable-line response parameter could be used to offer the possibility for the end user to copy the digits equivalent to the barcode to make the payment in his bank website/app, without read the barcode.

Some considerations about the payer name:
  • Maximum length of 50 characters
  • Minimum two words
  • Each word must be separated by ONE space
  • The first and last word must have at least 2 characters long
  • Middle words can have only one character
  • Accepted characters: A to Z, uppercase and/or lowercase letters
  • Special characters accepted: éíóúãõâêôàèìòùäëïöüçñÁÉÍÓÚÃÕÂÊÔÀÈÌÒÙÄËÏÖÜÇÑ&/'.-
Some considerations about the payer email:
  • On the local-part (before the @), only alphanumeric characters and the special characters - + . _ are allowed.

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": "[email protected]",
    "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": "[email protected]",
    "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": "[email protected]",
    "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": "[email protected]",
        "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": "[email protected]",
        "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": "[email protected]",
        "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": "[email protected]",
        "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": "[email protected]",
    "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": "[email protected]",
    "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": "[email protected]",
    "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": "[email protected]",
        "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

PagSeguro 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

Credit Card Installments API errors

CodeKeyDescription
30301bin_missingMissing Bin
30302bin_invalidInvalid Bin
30303brand_missingMissing Brand
30304brand_invalidInvalid Brand
30305country_missingMissing Country
30306country_invalidInvalid Country
30307amount_missingMissing Amount
30308amount_invalidInvalid Amount
30309currency_missingMissing Currency
30310currency_invalidInvalid Currency

Direct Payment JS errors

Only for credit_card payment-type.

ErrorDescriptionCritical
callback_must_be_a_functionThe callback parameter in the getDirectToken method is not a functionYes*
creditcard_object_malformedCredit card object is not a javascript objectYes*
credit_card_internal_errorError on save credit card on PCI environmentNo
creditcard_invalid_fieldsData from credit card object is not validNo
creditcard_invalid_objectCredit card object has an invalid structureYes*
session_create_errorThe object cannot retrive a session from PagSeguroNo
session_creating_in_progressThe Process of retrieving a session from PagSeguro was not yet finishedNo
session_network_errorThe object receives a network error on a attempt to create a sessionYes

🚧

*Implementation error

Transaction API errors

CodeKeyDescription
10203header_accept_bad_formatHeader Accept with bad format
10204header_accept_format_missingMissing Format on header Accept
10205header_accept_charset_missingMissing Charset on header Accept
10206header_accept_application_invalidInvalid Application on Accept Header
10207header_accept_format_invalidInvalid Format on Accept Header
10208header_accept_charset_invalidInvalid Charset on Accept Header
10209header_accept_version_invalidInvalid Version on Accept Header
20900transaction_missingTransaction is missing
20901transaction_amount_missingMissing Transaction Amount
20902transaction_amount_invalidInvalid Transaction Amount
20904payer_email_missingPayer email is missing
20905payer_email_invalidPayer email is not valid
20908transaction_reference_missingTransaction Reference missing
20909transaction_reference_exceed_limitTransaction Reference Exceed Limit
20910transaction_directtoken_missing*Transaction Direct Token Missing
20911transaction_directtoken_invalid*Issue generating Direct Token or not accepted card brand See more
20912transaction_notifyurl_missingTransaction Notify URL Missing
20913transaction_notifyurl_invalidTransaction Notify URL Invalid
20914transaction_notifyurl_length_invalidTransaction Notify URL Invalid Length
20915payer_missingPayer is missing
20919payer_phone_number_missingPayer phone number is missing
20920payer_phone_number_invalidPayer phone number is not valid
20921payer_phone_areacode_missingPayer phone area code is missing
20922payer_phone_areacode_invalidPayer phone area code is not valid
20926payer_document_number_missingPayer document number is missing
20927payer_document_number_invalidPayer document number is not valid
20928payer_name_missingPayer name is missing
20929payer_name_invalidPayer name is not valid
20930transaction_language_missingTransaction Language missing
20931transaction_reference_invalidTransaction Reference has special chars
20932transaction_testmode_invalidTransaction Test Mode value is not accepted
20934payer_birthdate_invalidPayer birth date is not valid
20935payer_birthdate_missingPayer birth date is missing
20936transaction_description_missingTransaction Description Missing
20937transaction_description invalidTransaction Description is not valid
20938transaction_country_missingTransaction Country is missing
20941transaction_currency_missingTransaction Currency is missing
20942transaction_save_payment_method_invalidTransaction Save Payment Method is not valid
20943transaction_currency_length_invalidTransaction Currency Invalid Length
20951transaction_installments_missingTransaction Installments is missing
20952transaction_installments_invalidTransaction Installments are not valid
20954transaction_currency_invalidTransaction Currency is invalid
20955transaction_country_invalidTransaction Country is not valid
20958transaction_reference_invalidTransaction Reference is not unique
20959transaction_project_number_invalidTransaction Project Number is invalid
20965payer_ip_missingPayer IP is missing
20966payer_ip_invalidPayer IP is invalid
20977transaction_type_missingTransaction Type is missing
20978transaction_type_invalidTransaction Type is not valid
20979payment_type_missingPayment type is missing
20980payment_type_invalidPayment type invalid (must be credit_card or boleto)
20981payer_document_type_missingPayer document type is missing
20982payer_document_type_invalidPayer document type is not valid
20984payment_exceed_limitsPayment exceed the limit purchase (only for Brazil, R$ 10000) by Payer Document
20985transaction_language_invalidTransaction Language invalid
20986unavailable_payment_methodThe choosen payment method is not avaliable
20987payment_method_not_foundPayment method was not found for the payment method code given or is not active
20989payment_method_code_invalidPayment method code format doesn't match (alphanum, 32 chars)
209100payer_blacklistedPayer is blacklisted by our risk analysis and must contact PagSeguro's Customer Support
209101payer_blacklisted_by_pspPayer is blacklisted by our PSP and must contact PagSeguro's Customer Support
209102transaction_returnurl_missingTransaction return URL is missing
209103transaction_returnurl_invalidTransaction return URL is invalid
209104transaction_returnurl_length_invalidTransaction return URL has an invalid length
209105transaction_redirectsuccessurl_missingTransaction redirect success URL is missing
209106transaction_redirectsuccessurl_invalidTransaction redirect success URL is invalid
209107transaction_redirectsuccessurl_length_invalidTransaction redirect success URL has an invalid length
209108transaction_redirectfailurl_missingTransaction redirect fail URL is missing
209109transaction_redirectfailurl_invalidTransaction redirect fail URL is invalid
209110transaction_redirectfailurl_length_invalidTransaction redirect fail URL has an invalid length