Google Pay™ API


Google Pay™ facilitates seamless payments in your app or website, allowing customers to utilize any credit card linked to their Google Account, including those from services like Google Play, YouTube, Chrome, and Android devices. The integration of the Google Pay API streamlines the process, enabling the effortless retrieval of credit card information stored in the customer's Google account.

This one-touch payment system ensures ease of checkout, with millions of users having saved their payment methods for quick transactions. The end-to-end encryption secures payment data during transmission from Google servers to the payment processor.

Additionally, a strategic partnership between Google Pay and PagSeguro International further enriches the payment experience, providing a secure solution for users.

Google Pay Payment Flow

  1. The customer selects the Google Pay option within the merchant's platform, be it an online store or app. Using either the Google Pay Web API or Android SDK, the merchant initiates a payment request with Google Pay.
  2. After the customer selects his credit card or provides his payment details (including a new credit card), Google replies with a token.
  3. The merchant's client submits this information to the merchant's server.
  4. The merchant send the raw token (returned by Google) information to PagSeguro International API.

Google Pay Integration (Merchant's side)

For web integration, please see this Google Pay Setup Guide, along with this Google Pay Integration Checklist and this brand guidelines.

For Android integration, please see this Google Pay Setup Guide documentation, along with the Google Pay Integration Check List (Android) and this Google Pay Android brand guidelines.

Google Pay Configuration

In the tokenization specification required by Google in the Request Objects page you need to configure it as:

"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "pagsegurointernational",
    "gatewayMerchantId": "YOUR_MERCHANT_ID"

If you are not sure about your gatewayMerchantId get in touch with your Technical Account Manager.

In the PaymentMethod section of your Google Pay configuration you need to support the same brands supported by PagSeguro International. Currently, we only support credit cards from the brands below:


Supported auth methods and card networks by PagSeguro International

Auth methods: PAN_ONLY (we still do not support CRYPTOGRAM_3DS)


See an example of PagSeguro International compatible configuration:

  "parameters": {  
    "allowedAuthMethods": ["PAN_ONLY"],  
    "allowedCardNetworks": ["AMEX", "DISCOVER", "MASTERCARD", "VISA"]  

See a full example of PaymentMethod configuration:

  "type": "CARD",
  "parameters": {  
    "allowedAuthMethods": ["PAN_ONLY"],  
    "allowedCardNetworks": ["AMEX", "DISCOVER", "MASTERCARD", "VISA"]  
  "tokenizationSpecification": {
    "type": "PAYMENT_GATEWAY",
    "parameters": {
      "gateway": "pagsegurointernational",
      "gatewayMerchantId": "YOUR_MERCHANT_ID"

JSFiddle Example

If you are having trouble to configure your Google Pay Web integration in your web page you can inspire youserlf in this jsfiddle below with the right specifications configured to PagSeguro International.

Completing your integration with Google

Once you've successfully completed all the required stages of the integration process in the testing environment, it's important to proceed by requesting your production access in the Google Pay Business Console as explained in this link. Follow the guidelines provided in the Google Web and Android documentation for this step and update your Google integration configuration to enable access to the Production environment.

In the final steps, reach out to your Technical Account Manager to ensure a thorough review of your configurations. This step is crucial to verify that everything has been accurately set up, and to confirm your readiness to transition to the live environment.

You will see below how to integrate with our payment API and how to send the token received by Google to our API.

Concepts and Terms

List of key definitions and standards that developers may need to successfully integrate.

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 Company that makes the payment, for work performed or goods received.


Direct API uses REST architecture, and the protocol used is HTTPS.
PagSeguro's API uses the Basic Authentication The API's requests and responses bodies are in JSON.


The merchant who wants to transact with PagSeguro must contact our sales team through the website:


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:


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


All transactions generated in the sandbox environment can be manipulated manually by developers to simulate the possible situations that PagSeguro returns through the site:

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


Base URL for Sandbox


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


Base URL for Production


All requests made to the PagSeguro APIs must be authenticated. PagSeguro Direct’s API uses the Basic Authentication approach. That means the Merchant must 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 Direct’s API only accepts requests throughout HTTPS/SSL/TLS

Once the Merchant’s On-boarding is concluded, the 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 transactions with PagSeguro.

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

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

$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;


//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()


// Authorization: Basic MTIzNDozN2IzNmUxNy1lZGIyLTRkNjAtOWFmZC05MTA2MmJlYmY1ZTQ=

Direct API

Sequence Flow

  1. Customer → Merchant: Customer completes the purchase on the merchant's website
  2. Merchant → PagSeguro: Merchant Server validates the customer data and submits the transaction data to PagSeguro
  3. PagSeguro → Merchant: PagSeguro processes the request and returns transaction data to the Merchant Server
  4. Merchant → Customer: Merchant Server returns the transaction data to Customer




Direct API URL for Production
Method: POST



Direct API URL for Sandbox
Method: POST


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

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


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

integrationThe object that contains the integration data for the transaction.Object-Yes
integration.referenceTransaction reference code in the merchant's store.StringMin. 4, Max. 64 - Pattern: ^([A-Za-z0-9-_])+$Yes
integration.notification_urlURL (must bind ports 80 or 443) used to send transaction status change notifications by HTTP.StringA valid URL, Max. 200Yes
integration.languageThe language that will be used when communicating with buyers. For example, it is the language of emails.StringSee Language ValidationYes

Language Validation

List of translations available for PagSeguro:

pt_BRBrazilian Portuguese
pt_PTPortugal Portuguese


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

orderThe object that contains the order data for the transaction.Object-Yes
order.currencyCurrency for charging the transaction (ISO 4217).StringSee Currency ValidationYes
order.items[]Set of items related to billing.ArrayMin. 1, Max. 100Yes
order.items[].quantityItem quantity.IntegerMin. 1Yes
order.items[].descriptionItem description.StringMax. 180 - See Item Description ValidationYes
order.items[].unit_pricePrice per unit.FloatMin. 0.01 - Zero to two decimal places accepted. See more Item Unit Price ValidationYes

Currency Validation

List of currencies available for PagSeguro:

ISO CodeCurrency
BRLBrazilian Real (Brazil)
CLPChilean Peso (Chile)
COPColombian Peso (Colombia)
MXNMexican Peso (Mexico)
PENNuevo Sol (Peru)

Item Description Validation

Rules for validating the item description:

  • Minimum 1 character;
  • The maximum length of 180 characters;
  • Accepted characters: A to Z, uppercase, lowercase letters, and/or numbers;

Item Unit Price Validation

Our API is designed to receive amounts starting from 0.01, but each country and each payment method has a minimum and maximum total amount accepted, so we recommend that the values are those indicated below:

CountryMinimum Total AmountMaximum Total AmountISO Code CurrencyAccepted Brands
Brazil1.0040000.00BRLAmerican Express, MasterCard, Visa
Chile0.011000000.00CLPAmerican Express, MasterCard, Visa
Colombia0.0138000000.00COPAmerican Express, MasterCard, Visa
Mexico0.0174000.00MXNAmerican Express, MasterCard, Visa
Peru0.0134000.00PENAmerican Express, MasterCard, Visa, Discover


The “charge” object contains the payment information to generate the transaction.
The available parameters are:

chargeThe object that contains the payment data for the transaction.Object-Yes
charge.countryCountry of origin of the transaction.StringSee Country ValidationYes
charge.typeRepresents the type of payment method.StringCREDIT_CARDYes
charge.credit_cardThe object contains data specific to payment with credit card.Object-Yes
charge.credit_card.google_payThe object containing all the data related to google pay.Object-Yes
charge.credit_card.google_pay.tokenThe token returned by GoogleString-Yes
charge.credit_card.holder_nameThe cardholder's name on the payer's credit cardStringMin. 2, Max. 26 - See Cardholder's Name ValidationYes

Country Validation

List of countries and their respective currencies accepted by PagSeguro:

ISOCountryCurrency Accepted

Cardholder's Name Validation

Rules for validating the cardholder’s name:

  • Minimum length of 2 characters;
  • The maximum length of 26 characters;
  • Accepted characters: A to Z, uppercase and/or lowercase letters;
  • Special characters accepted: ,.'-
  • Space characters are not accepted at the beginning and end of the string.
  • Each word must be separated by ONE space;


The “payer” object contains information about the Customer who purchased the Merchant.
The available parameters are:

payerThe object that contains the payer data for the transaction.Object-Yes
payer.emailPayer E-mail used in store.StringMax. 60 - See E-mail ValidationYes
payer.ipPayer IP used in store.StringAccepts IPv4 or IPv6Yes
payer.personThe object that contains the person's data for the transaction.Object-Yes
payer.person.namePerson's name.StringMin. 4, Max. 50 - See Name ValidationYes
payer.person.birth_datePerson's birth date.StringFormat (YYYY-mm-dd)Yes
payer.person.documentThe object that contains the payer identification document data for the transaction.Object- See Document ValidationYes
payer.person.document.typeDocument type.StringMin. 2, Max. 4Yes
payer.person.document.numberDocument number.StringMin. 7, Max. 18Yes
payer.person.phoneThe object that contains the phone data for the transaction.Object-Yes country code.StringMin. 1, Max. 3Yes number.StringMin. 1, Max. 11Yes

E-mail Validation

Rules for validating the email:

  • The maximum length of 60 characters;
  • Must include TLD (ex: test@localhost 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:

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

Document Validation

Rules for validating the person’s document:

  • Accepted characters: numbers or A to Z, uppercase letters;
  • Special characters are not accepted;
  • Punctuation must be disregarded;

List of documents and numbers format accepted for PagSeguro:

CountryTypeDocument NameValidationPatternExamples
BrazilCPFCadastro de Pessoas Físicas11 Characters - Format: 999.999.999-99^[0-9]{11}$00011122233, 01234567891
ChileRUTRegistro Único Tributario8 - 9 Characters - Format: 9.999.999-9 or 99.999.999.K^[0-9]{1,2}([0-9]{3}){2}[0-9kK]$220604497, 12531902, 2012346K, 12345678k
ColômbiaCCCédula de Ciudadanía10 Characters^[0-9]{10}$1234567890, 1112223334
ColômbiaCECédula de Extranjería7 Characters^[A-Za-z]{1}[0-9]{6}$a000111, Z778899
ColômbiaTITarjeta de Identidad11 Characters^[0-9]{11}$20503644968, 01234567891
ColômbiaNITNúmero de Identificación Tributaria8 - 10 Characters - Format: 99.999.999, 999.999.999 or 999.999.999-9^[0-9]{8,10}$11111111, 123456789, 2222222222
MéxicoCURPClave Única de Registro de Población18 Characters^[A-Za-z]{4}[0-9]{6}[HMhm][A-Za-z]{5}[0-9]{2}$ABCD112233MGHIJL90, dcba001122habcde12
MéxicoRFCRegistro Federal de Contribuyentes12 - 13 Characters - Format: LLLLNNNNNNAAA^[A-ZÑ&a-zñ]{3,4}[0-9]{6}[A-Za-z0-9]{3}$GAAA750430HZ0, AGB860519G31, zbc123456pl2
PeruDNIDocumento Nacional de Identidad9 Characters - Format: 99.999.999-K^[0-9]{8}[A-Za-z0-9]{1}$123456789, 12345678A, 87654321b
PeruCECédula de Extranjería8 - 10 Characters^[A-Za-z]{2}[0-9]{6,10}$AZ000111, az000111, BB4445556, bb4445556, bc11122233, BC11122233
PeruRUCRegistro Único de Contribuyente11 Characters - Format: 99999999999^[0-9]{11}$20503644968, 01234567891


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

Status 201 Created

    "integration": {
        "reference": "REF-XXX-1234567890",
        "notification_url": "",
        "language": "pt_BR"
    "order": {
        "currency": "BRL",
        "items": [
                "quantity": 1,
                "description": "Product description",
                "unit_price": 101.10
    "charge": {
        "country": "BR",
        "type": "CREDIT_CARD",
        "credit_card": {
            "google_pay": {
                "token": "{\"signature\":\"MEUCIQCpdjkwGbZHReTIo/G5muX0mpbbSE1Yo2L0Sk68GRQXegIgX4evAuOb8+SrYyUMV42isn4wABuoyKveYkwF/y3bLCM\\u003d\",\"intermediateSigningKey\":{\"signedKey\":\"{\\\"keyValue\\\":\\\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEn58WtMd+S2bLaqUAVWpilWWzQBu8t9Xm5zgb6AN5buOcYbVG2ELx59XZGcYo3KscSY6h/x2XuRoBBE5DFR4VNA\\\\u003d\\\\u003d\\\",\\\"keyExpiration\\\":\\\"1700159511279\\\"}\",\"signatures\":[\"MEUCIQDkLiLhgYLkhq7sXKHD+uyv/bZjDbiwqbugNUIyOT1YAwIgEjfLQ77q6cgIcTNyetxIYHUSyghtshmkxsEzx5vDcyk\\u003d\"]},\"protocolVersion\":\"ECv2\",\"signedMessage\":\"{\\\"encryptedMessage\\\":\\\"MU6eLCx3Pm2iTvsvOI2n73KmTavd9IyEtDBG1lEP33klvkwGH4Sb6AlJ2ocDW3IP6X1XK6Cd5clMGEWL0nsMazpCdxdyIhGjyMmtQaKBm0kyRe2/UAPTMMp4++sHPPs5q7GXFz/89KSEYxJUnfDWe73o8dEzlUqUro3Ik5jpaFcWXZppUgYaTVCGawKky+DML54LEvVK4WVfjsJs1MrSa8bgtYXq2AsHlvOWWnxBp+uv96mV4BOt8kveaZ5RQJIRiqVXIcx45ayakPaOS8cTAVqQA0/buiQiJmrfLVzMsqIOqJost88XGPk0y1SC4DdxA1uy8S/GckNlyIyZ3qjrPrBX7st5L+yLnGBFZYtgYFUW7hbcY1ELV8Xtno0n4PTDrgJv4FOScSbyJ49cTZG+mgbJnoa1mRm1I3s2yVRylBoJ5PiHcPRPXVrjWhUMBU5G5e0ePRl3fgNkd9qUD6TZ3tWyvjSGtKsxSLJ8ijj0ic06OI0Q4eqtJRx3ESjZALOYqLfGO8PRtc7Ul03yMgnJwlgHtxsab1ex1UJRSFCKl6mE8PE3UIqx211OX1GIIMn6\\\",\\\"ephemeralPublicKey\\\":\\\"BFNPLyTVg9SmjR7p0u5OdXKxKsjB7AXTKN6IhIEKCyBBwUUEdyswU62+iCPcuAAAUVvjNvR/1WNrFatpichAGlk\\\\u003d\\\",\\\"tag\\\":\\\"U5/T1RpIXRCrvDdfQhofxCxXMyfJ4it5mZTa1WihLOI\\\\u003d\\\"}\"}"
            "holder_name": "Jonh Doe"
    "payer": {
        "email": "[email protected]",
        "ip": "",
        "person": {
            "name": "Mr. Payer Full Name",
            "birth_date": "1970-01-01",
            "document": {
                "type": "CPF",
                "number": "98765432101"
            "phone": {
                "country_code": "55",
                "number": "44900000000"


codeTransaction UUID codeString
referenceTransaction reference code in the merchant's store.String
statusStatus of the created transaction. (PENDING)String
amountThe amount charged for the transaction.Float
currencyThe currency used for billing.String
countryThe country of origin informed in the transaction.String
created_atTransaction creation date in Coordinated Universal Time (UTC)UTC DateTime

Example of a response

    "code": "25a58ef1-3755-476b-b2f6-e445b170a849",
    "reference": "REF-XXX-1234567890",
    "status": "PENDING",
    "amount": 101.1,
    "currency": "BRL",
    "country": "BR",
    "created_at": "2021-04-12T12:43:13Z"



  1. PagSeguroMerchant: PagSeguro notifies Merchant that a transaction status has changed
  2. MerchantPagSeguro: With the transaction code received by the notification, the Merchant requests transaction information from PagSeguro
  3. PagSeguroMerchant: PagSeguro responds back with transaction information

To verify the current transaction status, the Merchant needs to use Search API to query the transaction. If PagSeguro responds to the transaction with the status COMPLETE, the 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.

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:



Upcoming update on our notification servers

Starting November 16th, there are going to be changes to these notification IPs.

By then, two new IPs MUST be added to your firewall or allowlist:


Also, two of the current IPs will continue to be used for notifications:


The remaining two ( and can be removed from your firewall or allowlist after November 16th.



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 cannot respond within this range of days with 200 OK status code, then the notification is expired.