Payment Page API

📘

This is the latest documentation

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

Overview

Welcome to the PagSeguro's Checkout API reference guide.
This document contains the basic concepts and technical details to pay for transactions using our Checkout API for countries that we have available. It also has practical examples of requests and pertinent notes on how our API works.

Concepts and Terms

List with the main definitions and standards that developers may need to successfully integrate with PagSeguro's Checkout API.

TermConcept
APIApplication Programming Interface (API) is a way to allow third parties to use your application's resources.
RESTRepresentational State Transfer (REST) ​​is a style of software architecture for API services.
HTTPSHypertext Transfer Protocol Secure (HTTPS) is the secure version of HTTP, which is the main protocol used to send data between a web browser and a website. HTTPS is encrypted to increase data transfer security.
cURLcURL is a computer software tool for transferring data using various network protocols.
JSONJavaScript Object Notation (JSON) is a lightweight data interchange format.
TLDTop-Level Domain is the last segment of your domain name, that element located after the last dot. Since it is at the end of the address, it is also known as the domain suffix.
SandboxSafe dummy domain beyond production, suitable for a smooth integration experience.
MerchantPerson or organization that provides work or supplies goods for a particular niche.
StoreStore or commercial establishment used in the integration.
CustomerPerson or organization that makes the payment, for work performed or goods received.
transaction-codeTransaction code is generated by PagSeguro after the completion of a payment request. This code is returned through the Notify API.
checkout-codePagSeguro generated code to identify the Checkout created by the request.
OBTOffline bank transfer (OBT), in this method the buyer receives a reference number during the payment process. They will be able to complete the purchase through their internet banking, or directly at a bank service station, informing the reference number or payment details to complete the transaction, in which case the authorization is not immediate.
EFTReal-Time transfer\Electronic Funds Transfer(EFT). In this method the customer pays using some of the bank's online functionality, like internet banking. In most cases payment authorization is immediate.
prepayThe buyer must be in possession of or purchase a card/voucher before initiating a transaction. These cards are generally not associated with acquisitions and authorization is usually immediate. Most prepay products have a fund limit and some do not allow multiple cards/vouchers to move a single transaction.
postpayWhen the shopper makes an online transaction and pays later at an affiliated network of stores or a banking network. These are usually methods that allow payment in cash.
e-wallete-Wallet is an electronic device, online service, or software program that allows one party to make electronic transactions with another party bartering digital currency units for goods and services. This can include purchasing items on-line with a computer or using a smartphone to purchase something at a store.

Considerations

Checkout API uses REST architecture. The protocol used is HTTPS. PagSeguro Checkout’s API uses the Basic Authentication The API’s requests and responses bodies are in JSON format.

Onboarding

Merchant who wants to transact with PagSeguro must contact our sales team through the website: https://international.pagseguro.com/talk-to-us.

Credentials

To carry out the authentication process, the Merchant needs the credentials (Merchant ID and Password) made available in its registration with PagSeguro, through the page: https://myaccount.international.pagseguro.com.

Environments

Test environment available to assist in the development of the integration and simulate transaction requests and status changes available on the platform. Attention: the environment only simulates the creation of a transaction.

Sandbox

All transactions generated in the sandbox environment can be manipulated manually by developers to simulate the possible situations that PagSeguro returns through the site: https://billing-partner.boacompra.com.

In the Sandbox Environment section we explain how to use the sandbox environment.

🚧

Base URL for Sandbox

https://api.sandbox.boacompra.com

Production

Environment used to create transactions in real time. All transactions generated in this environment will be processed by PagSeguro.

📘

Base URL for Production

https://api.boacompra.com

Authentication

All requests made to the PagSeguro APIs must be authenticated. PagSeguro Checkout’s API uses the Basic Authentication approach. That means the Merchant have to send the HTTP requests with the Authorization header.

The Authorization header must contain the word Basic followed by a space and a base64-encoded string with merchant_id:secret_key.

For example:

Authorization: Basic MTIzNDozN2IzNmUxNy1lZGIyLTRkNjAtOWFmZC05MTA2MmJlYmY1ZTQ=

Because base64 is easily decoded, PagSeguro Checkout’s API only accepts request throughout HTTPS/SSL/TLS.

Once Merchant’s On-boarding is concluded, Merchant’s Developers will have a credential pair (merchant_id and secret_key) to use in the requests. Anyone in possession of the credential pair will be able to create checkouts with PagSeguro.

Be sure to keep both, merchant_id and secret_key, in a safety and private place. Do not share it in client-side application or public repositories.

The code snippet below shows an Authorization header’s example:

<php
$key = '1234';
$secret = '37b36e17-edb2-4d60-9afd-91062bebf5e4';
$encoded = base64_encode(sprintf('%s:%s', $key, $secret));
$header = sprintf('Authorization: Basic %s', $encoded);

echo $header;

// Authorization: Basic MTIzNDozN2IzNmUxNy1lZGIyLTRkNjAtOWFmZC05MTA2MmJlYmY1ZTQ=
String key = "1234";
String secret = "37b36e17-edb2-4d60-9afd-91062bebf5e4";

String encoded = Base64.getEncoder().encodeToString((key + ":" + secret).getBytes());
String header = "Authorization: Basic " + encoded;

System.out.println(header);

//Authorization: Basic MTIzNDozN2IzNmUxNy1lZGIyLTRkNjAtOWFmZC05MTA2MmJlYmY1ZTQ=
require "base64"

key = '1234'
secret = '37b36e17-edb2-4d60-9afd-91062bebf5e4'

encoded = Base64.encode64(key + ':' + secret)
header = 'Authorization: Basic ' + encoded

puts header

// Authorization: Basic MTIzNDozN2IzNmUxNy1lZGIyLTRkNjAtOWFmZC05MTA2MmJlYmY1ZTQ=
import base64

key = "1234"
secret = "37b36e17-edb2-4d60-9afd-91062bebf5e4"
key_secret = key + ":" + secret

encoded = key_secret.encode("ascii")
header = "Authorization: Basic " + base64.b64encode(encoded).decode()

print(header)

// Authorization: Basic MTIzNDozN2IzNmUxNy1lZGIyLTRkNjAtOWFmZC05MTA2MmJlYmY1ZTQ=

Checkout API

Sequence Flow

33343334
  1. Customer → Merchant: Customer finalizes the purchase through Merchants Store

  2. Merchant → PagSeguro: Merchant sends a Create Checkout request to PagSeguro with the Customer's data

  3. PagSeguro → Merchant: PagSeguro processes the requested data and returns a Checkout URL to the Merchant

  4. Merchant → Customer: Merchant redirect Customer to the Checkout URL generated by PagSeguro

  5. Customer → PagSeguro: Customer completes the payment flow at PagSeguro Checkout;

  6. PagSeguro → Merchant: PagSeguro redirects the customer to the Merchant Store.

Enviroments

Production

📘

Checkout API URL for Production

https://api.boacompra.com/v3/checkouts

Method: POST

Sandbox

🚧

Checkout API URL for Sandbox

https://api.sandbox.boacompra.com/v3/checkouts

Method: POST

Request

To create a Checkout with the PagSeguro API, the following objects will be used: integration, order, checkout, charge and payer.

  • To perform authentication, use the default authentication method defined in Authentication Section
  • Use Content-Type header with value "application/json".

Integration

The “integration” object contains integration data referring to the Merchant Store. The available parameters are:

ParameterDescriptionTypeValidationMandatory
integrationGeneral integration information.Object-Yes
integration.referenceMerchant reference code.StringMin. 4, Max. 64
Pattern:
^([A-Za-z0-9-,_/])$
Yes
integration.notification_urlURL (must bind ports 80 or 443) used to send transaction status changes notifications by HTTPStringA valid URL, Max. 200Yes
integration.projectIntegration project identifier. Default value is 1IntegerMin. 1No

Order

The “order” object contains the value and list of products that Customer purchased from the Merchant store. The available parameters are:

ParameterDescriptionTypeValidationMandatory
orderGeneral order information.Object-Yes
order.currencyCurrency of order (ISO 4217)String [*] Yes
order.items[]Set of itemsArrayMin. 1, Max. 100Yes
order.items[].quantityItem quantityIntegerMin. 1Yes
order.items[].descriptionItem descriptionStringMax. 180Yes
order.items[].unit_pricePrice per unitFloatMin. 0.01Yes

Validation Currency

ISO CodeCurrency
ARSArgentine Peso (Argentina)
BOBBolivian Boliviano (Bolivia)
BRLBrazilian Real (Brazil)
CLPChilean Peso (Chile)
COPColombian Peso (Colombia)
CRCCosta Rican Colon (Costa Rica)
EUREuro (Portugal, Spain)
GTQGuatemalan Quetzal (Guatemala)
MXNMexican Peso (Mexico)
NIOCordoba (Nicaragua)
PENNuevo Sol (Peru)
PYGGuarani (Paraguay)
RONLeu Romeno (Romania)
TRYTurkish Lira (Turkey)
USDDollar (Ecuador, El Salvador, Panama, Puerto Rico, USA)
UYUUruguayan Peso (Uruguay)

Checkout

The “checkout” object contains information on how the PagSeguro Checkout will be displayed to Customer, the available parameters are:

ParameterDescriptionTypeValidationMandatory
checkoutCheckout informationObject-Yes
checkout.languageCheckout languageString [*] Yes
checkout.redirect_urlsCheckout redirect URLsObjectA Valid URLYes
checkout.redirect_urls.successCheckout redirect URL successStringMax. 200Yes

Validation Language

List of translations available for PagSeguro Checkout:

LanguageLocate
en_USEnglish
es_ESSpanish
pt_BRBrazilian Portuguese
pt_PTPortugal Portuguese
tr_TRTurkish

Charge

The “charge” object contains the payment information to generate the transaction. Checkout can present the payment methods to Customer in two ways, via the type or via the specific method.

The type is a group of payment methods, being possible to inform only the type, which will show all linked methods at checkout, or directly inform the payment method.
Eg: it is possible to inform the credit card type, which will open options to inform the brand, or inform the VISA payment method directly.

The type can also be omited, in which case checkout would present all payment methods to the customer.

The available parameters are:

ParameterDescriptionTypeValidationMandatory
chargeObject that contains the Billing data for a transaction.Object-Yes
charge.countryCountry of origin of the collection.String[*] Yes
charge.typeGrouper with the Type of charge to be presented at CheckoutString[*] No
charge.credit_cardCredit Card specific payment method.String[*] No
charge.debit_cardDebit Card-Specific Payment MethodString[*] No
charge.e_walletSpecific payment method for Electronic WalletString[*] No
charge.eftSpecific payment method for Real-Time transfer\Electronic Funds Transfer(EFT)String[*] No
charge.obtSpecific payment method for Offline bank transfer (OBT)String[*] No
charge.postpayPostpay specific payment methodString[*] No
charge.prepayPrepay specific payment methodString[*] No

Country Validation

The list of all payment methods by country can be found in the section: Available payment methods by country.

ISOCountry
ARArgentina
BOBolivia
BRBrazil
CLChile
COColombia
CRCosta Rica
ECEcuador
SVEl Salvador
GTGuatemala
MXMexico
NINicaragua
PAPanama
PYParaguay
PEPeru
PTPortugal
PRPuerto Rico
RORomania
ESSpain
TRTurkey
USUnited States
UYUruguay

Type Validation

List of payment types accepted by PagSeguro Checkout:

  • CREDIT_CARD
  • DEBIT_CARD
  • E_WALLET
  • EFT
  • OBT
  • POSTPAY
  • PREPAY

Credit Card Validation

List of accepted payment methods:

  • AMEX
  • ARGENCARD
  • CABAL
  • CENCOSUD
  • CMR
  • DINERS
  • EASY
  • ELO
  • HIPERCARD
  • JCB
  • JUMBO
  • LIDER
  • MAGNA
  • MASTERCARD
  • NATIVA
  • OCA
  • PARIS
  • RIPLEY
  • TARJETA_SHOPPING
  • TROYCARD
  • UNIONPAY
  • VISA

Debit Card Validation

List of accepted payment methods:

  • MAESTRO
  • REDCOMPRA
  • VISA_ELECTRON
  • WEBPAY

e-Wallet Validation

List of accepted payment methods:

  • GPAY
  • PAGSEGURO
  • PAYPAL
  • PAYVALIDA

EFT Validation

List of accepted payment methods:

  • BANBIF
  • BANCO_DE_OCCIDENTE
  • BANCO_DO_BRASIL
  • BANCOLOMBIA
  • BANRISUL
  • BBVA
  • BCP
  • INTERBANK
  • ITAU
  • KHIPU
  • PIX
  • SANTANDER
  • SCOTIABANK

OBT Validation

List of accepted payment methods:

  • AKBANK
  • BANAMEX
  • BANBIF
  • BANCENTRO_LAFISE
  • BANCO_DE_BOGOTA
  • BANCO_DO_BRASIL
  • BANCO_ESTADO
  • BANCO_NACIONAL_CR
  • BANCOLOMBIA
  • BANCOMER
  • BBVA
  • BCI
  • BCP
  • BRADESCO
  • CAJA_CUSCO
  • CAJA_ICA
  • CAJA_PIURA
  • CAJA_TACNA
  • CAJA_TRUJILLO
  • CATHAY
  • CITI
  • DAVIVIENDA
  • DENIZ
  • ECONOMI
  • GARANTI
  • INTERBANK
  • ISBANK
  • ITAU
  • KASNET
  • KUVET
  • MACRO
  • MUCAP
  • MUTUAL_ALAJUEDA
  • PSE
  • PTT
  • SAFETYPAY
  • SANTANDER
  • SCOTIABANK
  • SEKER
  • SERVIPAG
  • SPEI
  • VAKIFAR
  • WESTERN
  • YAPI_KREDI
  • ZIRAAT

Postpay Validation

List of accepted payment methods:

  • ABITAB
  • BANCENTRO_LAFISE
  • BANCO_NACIONAL_CR
  • BANORTE
  • BOLETO
  • BOLETO_FLASH
  • CASH
  • CATHAY
  • EFECTY
  • GANA
  • LAFISE
  • MUCAP
  • MULTIBANCO
  • MULTICAJA
  • MUTUAL_ALAJUEDA
  • OXXO
  • PAGO_EFECTIVO
  • PAGO_FACIL
  • PAYSHOP
  • RAPIPAGO
  • REDPAGOS
  • TELEDOLAR

Prepay Validation

List of accepted payment methods:

  • TODITO

Payer

The “payer” object contains information about the Customer who made the purchase on the Merchant.
Please note that the "payer" object is optional. However, if you do send it, the following parameters become mandatory: payer.person.phone.country_code and payer.person.phone.number.
The available parameters are:

ParameterDescriptionTypeValidationMandatory
payerPayer informationObject-No
payer.emailPayer E-mailStringMax. 60 [*]No
payer.personPayer of type Person informationObject-No
payer.person.namePerson nameStringMin. 4, Max. 50 [*]No
payer.person.phonePhone informationObject-No
payer.person.phone.country_codePhone country codeStringMin. 1, Max. 3Mandatory when the payer object is sent
payer.person.phone.numberPhone numberStringMin. 1, Max. 11Mandatory when the payer object is sent
payer.person.birth_datePerson birth dateStringFormat (YYYY-mm-dd)No

E-mail Validation

Rules for validating the email:

  • Maximum length of 60 characters;
  • Must include TLD (ex: [email protected] is not accepted, but [email protected] is accepted);
  • Need to include @ between the name and the domain.

Name Validation

Rules for validating the payer’s name:

  • Maximum length of 50 characters;
  • Minimum two words;
  • Each word must be separated by ONE space;
  • The first word must have at least 2 characters long;
  • The middle and last name words must be between 1 and 40 characters long;
  • Middle and last words can have only one character;
  • Accepted characters: A to Z, uppercase and/or lowercase letters;
  • Special characters accepted: àáâäãåąčćęèéêëėįìíîïłńòóôöõøùúûüųūÿýżźñçčšžÀÁÂÄÃÅĄĆČĖĘÈÉÊËÌÍÎÏĮŁŃÒÓÔÖÕØÙÚÛÜŲŪŸÝŻŹÑßÇŒÆČŠŽ∂ð/,.'&-

Examples

To create a credit card checkout, make a POST request as the example:

Status 201 Created

{
    "integration": {
        "reference": "REF-XXX-1234567890",
        "notification_url": "https://www.merchantwebsite.com/notify?type=transaction",
        "project": 1
    },
    "order": {
        "currency": "BRL",
        "items": [
            {
                "quantity": 1,
                "description": "Product description",
                "unit_price": 101.1
            }
        ]
    },
    "checkout": {
        "language": "pt_BR",
        "redirect_urls": {
            "success": "https://www.merchantwebsite.com/success"
        }
    },
    "charge": {
        "country": "BR",
        "type": "CREDIT_CARD"
    },
    "payer": {
        "email": "[email protected]",
        "person": {
            "name": "Mr. Payer",
            "birth_date": "1970-01-01",
            "phone": {
                "country_code": "55",
                "number": "44900000000"
            }
        }
    }
}

Charge information is used to inform checkout payment settings.
The type attribute allows you to select the category of payment methods that can be used to finalize the checkout.

Example of a credit card type request

{
    ...
    "charge": {
        "country": "BR",
        "type": "CREDIT_CARD"
    }
    ...
}

Example of a postpay type request

{
    ...
    "charge": {
        "country": "BR",
        "type": "POSTPAY"
    }
    ...
}

You can also enter a specific payment method:

Example of a specific credit_card

{
    ...
    "charge": {
        "country": "BR",
        "credit_card": "VISA"
    }
    ...
}

It is mandatory to inform the type or method of payment. It's not possible to inform them simultaneously.

Response

ParameterDescriptionType
codeCheckout UUID code, only used for internal PagSeguro trackingString
urlCheckout URL, used to redirect the customerString
created_atCheckout creation date in Coordinated Universal Time (UTC)UTC DateTime
expires_atCheckout expiration date in Coordinated Universal Time (UTC), maximum time to access the checkout URLUTC DateTime

Example of a response

{
    "code": "5be8a351f5bc4e33ae92dd4b860db314",
    "url": "https://payment.boacompra.com/5be8a351f5bc4e33ae92dd4b860db314",
    "created_at": "2021-04-12T12:43:13Z",
    "expires_at": "2021-04-12T12:45:13Z"
}

The Checkout URL returned has an expiration time, therefore, this URL must be exposed to Customer as soon as it is generated. The expiration time for the checkout URL varies, being 2 minutes for Checkout 2.0 and 15 minutes for Checkout 1.0.

Notification

Workflow

33353335
  1. PagSeguro → Merchant: PagSeguro notifies Merchant that a transaction status has changed

  2. Merchant → PagSeguro: With the transaction code provided in the notification, Merchant requests transaction informations to PagSeguro

  3. PagSeguro → Merchant: PagSeguro responds back with transaction informations

To verify the current transaction status, Merchant needs to use Search API to query the transaction. In case PagSeguro responds the transaction with status COMPLETE, Merchant needs to deliver the purchase to the End User.

Notification Request

After changing the payment status, PagSeguro sends the notification to the Merchant through the URL provided in the integration.notification_url parameter.

POST https://www.merchantwebsite.com/notify?type=transaction HTTP/1.1
Content-Type: application/json
{
    "test_mode": false,
    "notification_type": "transaction",
    "transaction_code": "9DB1FAFB-C0E6-4184-822C-8F18B3D70321"
}

Firewall and allowlist settings

❗️

If you use a firewall or allowlists, please note that to receive our notifications, you MUST allowlist the following IPs:

  • 177.71.206.83
  • 54.233.76.62
  • 34.231.230.192
  • 34.232.159.3

Renotification

📘

Renotification details:

If PagSeguro does not receive a satisfactory response from the Merchant (200 OK) in the first request, the notification enters a retry flow over 5 days and the intervals of retry increase exponentially over the days. If the Merchant is unable to respond within this range of days with 200 OK status code then the notification is expired.