❗️
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

How it Works

The merchant loads PagSeguro script in clients browser.
If desired, the merchant get installments options to show to the customer.
Customer fill and submit payment info, then a method is called in PagSeguro script.
After receiving the direct-token customer submit all the necessary information to merchant server.
The Merchant submits to /transactions to create the transaction.
PagSeguro creates an order and returns the status transaction and ID to merchant.
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

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.

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

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:

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

Example to get the credit card installments via cURL

curl -X GET \
    'https://api.boacompra.com/card/installments?brand=visa&country=BR&amount=16.00&currency=BRL' \
    -H 'accept: application/vnd.boacompra.com.v1+json; charset=UTF-8' \
    -H 'authorization: 123:ba567109f868df40c7cda9c5563bf2a9cdcb8b6b654654165'

// Response headers:
HTTP/1.1 200 OK
Content-type: application/vnd.boacompra.com.v1+json; charset=UTF-8

Response body

{
  "installments": [
    {
      "quantity": 1,
      "totalAmount": 16,
      "installmentAmount": 16,
      "interestFree": true
    },
    {
      "quantity": 2,
      "totalAmount": 16.48,
      "installmentAmount": 8.24,
      "interestFree": false
    }
  ]
}

Get brand and installments in the same request

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

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

List of Parameters:

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

Example to get the brand and credit card installments via cURL

curl -X GET \
    'https://api.boacompra.com/card?bin=123456&country=BR&amount=16.00&currency=BRL' \
    -H 'accept: application/vnd.boacompra.com.v1+json; charset=UTF-8' \
    -H 'authorization: 123:ba567109f868df40c7cda9c5563bf2a9cdcb8b6b654654165'

Response headers

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

Response body

{
  "bin": {
    "number": 123456,
    "brand": "visa",
    "cvvSize": 3,
    "expirable": true,
    "validationAlgorithm": "LUHN",
    "installment": true
  },
  "installments": [
    {
      "quantity": 1,
      "totalAmount": 16,
      "installmentAmount": 16,
      "interestFree": true
    },
    {
      "quantity": 2,
      "totalAmount": 16.48,
      "installmentAmount": 8.24,
      "interestFree": false
    }
  ]
}

Tokenization

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

How it Works?

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

2 - 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
Diners
Elo
HiperCard
MasterCard
Visa

Boleto

Direct API Boleto Workflow

How it Works

Customer fills and submits all necessary payment information to merchant server.
The Merchant submits to /transactions to create the transaction.
PagSeguro creates an order and returns the transaction code, Boleto URL and barcode number to merchant.
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

Customer fills and submits all necessary payment information to merchant server.
The Merchant submits to /transactions to create the transaction.
PagSeguro creates an order and returns the Transaction Code and Payment URL to merchant.
Merchant redirects the customer to PagSeguro's Payment URL.
The customer accesses the Payment URL and pays the transaction through the payment method website.
After the success in the payment flow, the customer will be redirected to Merchant's Success URL. If the customer cancels the process, he will be redirected to Merchant's Fail URL.

Transaction API

Header Specification

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

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

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

[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

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 errors

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 PagSeguro	No
session_creating_in_progress	The Process of retrieving a session from PagSeguro was not yet finished	No
session_network_error	The object receives a network error on a attempt to create a session	Yes

🚧
*Implementation error

Transaction API errors

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

❗️This documentation is deprecated

Credit Card

Direct API Credit Card Workflow

How it Works

📘

Including Direct API Script

Direct Payment Token

Credit card object

Callback function

Full Example

🚧ATTENTION

Credit Card Installments

Get brand

📘

Obtain the installment options

📘

Get brand and installments in the same request

📘

Tokenization

How it Works?

Considerations about tokenization:

Available Brands

Boleto

Direct API Boleto Workflow

How it Works

EWallet

How it Works

Transaction API

Header Specification

How to Generate the Authorization Header

Creating Transactions

📘Base URL for Production

🚧Base URL for Sandbox

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

Some considerations about the payer name:

Some considerations about the payer email:

Body example of a request using credit card

Body example of a transaction using boleto

Body example of a transaction using EWallet: PagSeguro

Body example of a transaction using EWallet: PayPal

Transaction response using EWallet: PagSeguro or PayPal

Body example of a transaction request using tokenization feature

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

Expected Response Headers

Status Change

Sandbox

Tokenization Feature

Payment method object pre-configured

Error response when using a wrong payment-method-code

Errors

Credit Card Installments API errors

Direct Payment JS errors

🚧

Transaction API errors

❗️
This documentation is deprecated

🚧
ATTENTION

📘
Base URL for Production

🚧
Base URL for Sandbox