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
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.
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}¤cy={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¤cy=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}¤cy={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¤cy=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 |
Updated almost 2 years ago