Documentation

Credit Card

Suggest Edits

Cards are a dominant payment method worldwide. Credit cards are issued by banks and allow customers to borrow money with a promise to pay it back within a grace period to avoid extra fees. Consumers can accrue a continuing balance of debt, subject to being charged interest on the amount.

To take advantage of the features available in our API, it is important to first understand the concepts involved in processing a credit card transaction.

ConceptDescription
PCI/DSSPayment Card Industry Data Security Standards
Client-side EncryptionProgramming technique to encrypt sensitive cardholder data on the client side and securely transfer this data to the payment gateway to process a payment.
Anti fraudIt is a fraud prevention platform that provides a detailed risk analysis of online purchases. Transactions are subject to a large number of rules, besides the specific rules for each segment. According to the pre-established criteria, the request can be automatically accepted, refused or sent for manual analysis.
TokenizationIt´s a process that allows secure storage of sensitive credit card data. The data is transformed into an encrypted code named “token”, which can be stored in a database. This allows merchants to make recurring payments.
InstallmentsInstallment payments are a way to spread out a payable amount. A customer can split up a full payment into smaller chunks, which they pay off at a regular intervals over a set period.

Workflow

  1. The merchant loads PagSeguro script in the client's browser.

  2. If desired, the merchant gets installments options to show the customer.

  3. The customer fills and submits payment info, then a method is called in PagSeguro's script.

  4. After receiving the direct-token, the customer submits all the necessary information to the merchant's server.

  5. The Merchant submits to /transactions to create the transaction.

  6. PagSeguro creates an order and returns the status transaction and ID to the merchant.

  7. The Merchant returns the transation status to the customer.

When the merchant has the customer's credit card (payment-method object) saved on their side, the first step is not necessary and the parameter code must be used instead of the token parameter.
See more on Tokenization Section

Creating a Credit Card Payment

Step 1: Collect Payer Details

For most payment methods, you can collect the payment details directly from the customer. For credit cards, however, you will need to encrypt any sensitive credit card details.

📘

Are you PCI Level 1 or 2 certified?
You can optionally submit raw card data.
See Creating a Raw Credit Card Payment for more information.

Encrypt credit card details

PagSeguro provides a JavaScript library so you can use it to securely collect your customer's credit card details without sensitive credit card data reaching your server. When the customer enters the details of the card on your site, the script collects the sensitive data and creates an encrypted version that you can securely transmit to PagSeguro.

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 Checkout 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 token method

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.
It's highly recommended not to store or traffic this data in your system unless you have PCI certification. The getDirectToken method expects two parameters: Credit card object and a callback function.

Creating the direct-token in javascript

//credit card data
var data = {
    creditCard: '5555666677778884',
    cvv: '123',
    expiration: {
        month: '02',
        year: '2026'
    }
};

//callback function for payment.getDirectToken function
var callback = function(err, directToken) {
    if (err) {
        //Error in token generation
        return false;
    }
    console.log('Token generated with success');
    console.log(directToken);
};

//note: the payment object must be previously instantiated before call this function (see full example on the next section).
//calling the getDirectToken function to generate the credit-card token
payment.getDirectToken(data, callback);

Credit card object

PropertyTypeValue
creditCardstringCredit card number
cvvstringCredit card CVV
expirationobjectObject with expiration data
expiration.monthstringCredit card expiration month (2 characters)
expiration.yearstringCredit card expiration year (4 characters)

Example of credit card object

var creditCard = {
    creditCard: '5555666677778884',
    cvv: '123',
    expiration: {
        month: '02',
        year: '2020'
    }
};

Callback function

The callback function expects two parameters: an error and a string token.

Example of callback function

var callback = function(err, directToken) {
    if (err) {
        //Error in token generation
        return false;
    }
    console.log('Token generated with success');
    console.log(directToken);
};

Full Example

Here you will find a detailed and explained example of a HTML file implementing our javascript file.

🚧

ATTENTION:

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

<!DOCTYPE html>

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

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

        <title>PagSeguro Direct Checkout 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: hhttps://docs.boacompra.com/docs/direct-api-credit-card#creating-a-credit-card-payment

            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.boacompra.com/direct-api/#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.boacompra.com/direct-api/#transaction-api
                };

                payment.getDirectToken(cardData, callback);
            }
        </script>
    </body>
</html>

Step 2 (optional): Get Credit Card Installments

Credit card Installment payments are a way to spread out a payable amount. A customer can choose to split up a full payment into smaller chunks, which they pay off at regular intervals over a set period.

Brazil

Credit Card Installments available in Brazil by brand:

  • Visa - up to 12x
  • MasterCard - up to 12x
  • American Express - up to 12x
  • Elo Card - up to 12x
  • Diners - up to 12x
  • Hipercard - up to 12x

📘

The minimum installment amount is 5 BRL.

To get the payment installments, you need to do the following:

Get brand and installments

To show the installment options for the customer, you must make a request to the Installments API. The installments options will change according to the credit card brand.

📘

Get brand and installments URL

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

Method: GET

PropertyDescriptionTypeSizeRequired
binCredit Card BIN (first six digits of the card)Integer6Yes
countryCountry of PaymentString2Yes
amountValue of orderDoubleMin of 0.01Yes
currencyCurrency of orderString3Yes

Example to get the brand and credit card installments with 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
    }
  ]
}

Check brand name (optional)

If you want to show the credit card brand name, this service offers this possibility.

📘

Check brand name URL

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

Method: GET

PropertyDescriptionTypeSizeRequired
binCredit Card BIN (first six digits of the card)Integer6Yes

Example with 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
    }
}

Bin Object

PropertyType
numberInteger
brandString
cvvSizeInteger
expirableBoolean
validationAlgorithmString
installmentBoolean

Check installment options (optional)

If you want to show the installments amount according to the brand for the customer, this service offers this possibility.

📘

Check installment options URL

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

Method: GET

PropertyDescriptionTypeSizeRequired
brandName of BrandStringYes
countryCountry of PaymentString2Yes
amountValue of orderDoubleMin of 0.01Yes
currencyCurrency of orderString3Yes

Example with 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
    }
  ]
}

Installment Object

PropertyType
quantityInteger
totalAmountInteger
totalinstallmentAmountFloat
interestFreeBoolean

Step 3: Request a Credit Card Payment

After collecting the payment details from the customer, make a request to the Transaction API using the information given by the customer and specifying the chosen payment method by using the payment method type parameter.

📘

The minimum amount value is 0.20 BRL.

Request

📘

Requesting a credit card payment in Production

https://api.boacompra.com/transactions

Method: POST

🚧

Requesting a credit card payment in Sandbox

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

Method: POST

Example of a request using credit card payment

{
  "transaction": {
    "reference": "REF-XXX-1234567890",
    "project-number": 1,
    "country": "BR",
    "currency": "BRL",
    "checkout-type": "direct",
    "notification-url": "https://billing.checkout.com/processing",
    "language": "pt-BR"
  },
  "charge": [
    {
      "amount": 100.00,
      "payment-method": {
        "type": "credit-card",
        "sub-type": "mastercard"
      },
      "payment-info": {
        "installments": 3,
        "token": "eyJkbmEiOiI2NzY3YzAxNDEzNGM0NTc4ODg0ZjU2MjdmYTI0ZGVhZiIsImlwIjoiMjAwLjIyMS4xMzAuNDkiLCJkZiI6ImNmYWI3MDcxMDJlZDQ4MjU4MzJhNmY2MDBhNWZjZjc2In0="
      }
    }
  ],
  "payer": {
    "name": "John Doe",
    "email": "[email protected]",
    "birth-date": "1988-12-25",
    "phone-number": "+5511987654321",
    "document": {
      "type": "CPF",
      "number": "00000000191"
    },
    "address": {
      "street": "Rua Teste",
      "number": "1102",
      "complement": "AP 10",
      "district": "Bairro Teste",
      "state": "PR",
      "city": "Maringá",
      "country": "BR",
      "zip-code": "87030000"
    },
    "ip": "200.221.118.80"
  },
  "shipping": {
    "cost": 0,
    "address": {
      "street": "Rua Teste",
      "number": "1102",
      "complement": "AP 10",
      "district": "Bairro Teste",
      "state": "PR",
      "city": "Maringá",
      "country": "BR",
      "zip-code": "87030000"
    }
  },
  "cart": [
    {
      "quantity": 1,
      "description": "Calça Jeans",
      "category": "Collectibles",
      "type": "physical",
      "unit-price": 1
    }
  ]
}

Request Parameter List

ParameterDescriptionTypeSizeMandatory
transactionSet of general transaction's informationObject-Yes
transaction.referenceMerchant transaction identifierStringUp to 64Yes
transaction.project-numberMerchant project identifier. Default value is 1Integer-No
transaction.countryCountry of the payment. Accepts only BRString2Yes
transaction.currencyCurrency of the transaction. Accepts only BRLString3
transaction.checkout-typeCheckout type of the transaction. Accepts only directString-Yes
transaction.notification-urlURL (must bind ports 80 or 443) used to send transaction status changes notifications by HTTPStringUp to 200Yes
transaction.languageLanguage used. Accepts pt-BR, en-US, es-ES, pt-PT and tr-TRString5Yes
transaction.giftingFlags transaction as gifting. We recommend sending this parameter only when the transaction is a gift (value = true). For regular transactions it is not necessary to send it.Boolean-No
charge[]Set of payments. Currently accepting just one (1) paymentArray1Yes
charge[].amountAmount of the transaction. Separating cents by point, with two decimal places. Amount sum must be equal to shipping.cost plus cart items valueDoubleMin of 0.20Yes
charge[].payment-method.typePayment Method type (credit-card, postpay, e-wallet or eft)String-Yes
charge[].payment-method.sub-typePayment Method sub-type. Available brands (see more)String-No
charge[].payment-info.installmentsInstallments quantity (see more)IntegerMin of 1Yes
charge[].payment-info.tokenToken containing credit card encrypted data (see more)String-Yes [1]
charge[].payment-info.codeToken which represents a payment method previously saved and already activated (see more)String32No
charge[].payment-info.saveUsed to save payment method for future transactions (see more)Boolean-No
payerSet of customer's informationObject-Yes
payer.nameCustomer name (see more)StringUp to 255Yes
payer.emailCustomer e-mail addressStringUp to 60Yes
payer.birth-dateCustomer birth date. ISO-8601 Pattern (YYYY-MM-DD)String-Yes [3]
payer.phone-numberCustomer phone number. e.g (+5544999884455)String-Yes
payer.document.typeCustomer document Type. accepts: cpf and cnpjString-Yes
payer.document.numberCustomer identification document. No special characters allowed.String-Yes
payer.ipCustomer IP. accepts IPv4 or IPv6String-No
payer.addressCustomer address objectObject-No [2]
payer.address.streetCustomer address streetString1-160Yes
payer.address.numberCustomer address numberString1-20Yes
payer.address.complementCustomer address complementStringUp to 40No
payer.address.districtCustomer address districtString1-60Yes
payer.address.stateCustomer address state or provinceString2Yes
payer.address.cityCustomer address cityString1-60Yes
payer.address.countryCustomer address country (country iso 2)String2Yes
payer.address.zip-codeCustomer address zip codeString8Yes
shippingSet of information that will be used to deliver the items in cart (see more)Object-No [2]
shipping.costShipping cost. Separating cents by dot, with two decimal placesDoubleMin of 0.01Yes
shipping.address.streetShipping address streetString3-160Yes
shipping.address.numberShipping address numberString1-20Yes
shipping.address.complementShipping address complementString5-40No
shipping.address.districtShipping address districtString4-60Yes
shipping.address.stateShipping address state or provinceString2Yes
shipping.address.cityShipping address cityString3-60Yes
shipping.address.countryShipping address country (country iso 2)String2Yes
shipping.address.zip-codeShipping address zip CodeString8Yes
cart[]Set of items (at least one Item)ArrayMin of 1Yes
cart[].quantityItem quantityIntegerMin of 1Yes
cart[].descriptionItem descriptionString1-200Yes
cart[].unit-pricePrice per unit. Separating cents by dot, with two decimal placesDoubleMin of 0.01Yes
cart[].typeItem type - must be one of the following: digital, physical, service, subscriptionString-Yes
cart[].categoryItem categoryString1-64No

About required fields

1- Required, except when using charge[].payment-info.code
2- Required when cart[].type is physical
3- Required when payer.document.type is cpf

Some considerations about the payer name:

  • Maximum length of 255 characters
  • Minimum two words
  • Each word must be separated by ONE space
  • The first word must have at least 2 characters and at most 50
  • The middle words must have at least 1 character and at most 50
  • 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.

Some considerations about the payer birth-date and payer phone-number:

  • Required parameters for fraud analysis to chargebacks susceptible payment types.
  • Payment type susceptible to chargebacks:
    • credit-card
    • e-wallet

Response

Example of a response using credit card payment

{
  "transaction": {
    "code": "111114891",
    "reference": "REF-XXX-1234567890",
    "amount": 100,
    "status": "PENDING",
    "currency": "BRL",
    "country": "BR",
    "payer-email": "[email protected]",
    "date-created": "2018-10-09T10:23:05.916587756-03:00"
  }
}

Response Parameter List

PropertyDescriptionTypeSizeFormat
transaction.codePagSeguro´s referenceStringUp to 36e.g.: 111181153
transaction.referenceMerchant´s referenceStringUp to 64XXX-XXX-XX-XXXXXXXXXX
transaction.amountTransaction AmountNumber-e.g.: 50.0
transaction.statusCurrent status (see more)String-e.g.: PAID
transaction.currencyCurrency transactionString3e.g.: BRL
transaction.countryCountry transactionString2e.g.: BR
transaction.payer-emailPayer emailStringUp to 60e.g.: [email protected]
transaction.date-createdDate of creationString-e.g.: 2018-10-10T14:39:32.991217999-03:00

Creating a Raw Credit Card Payment

❗️

IMPORTANT

Anyone involved with the processing, transmission, or storage of card data MUST comply with the Payment Card Industry Data Security Standards (PCI DSS).

If you are PCI Level 1 or Level 2 certified you can submit raw card data to PagSeguro when you make a payment. To submit raw card data, contact your Account Manager, once they've set you up, you are ready to submit card fields when you make a payment request.

PagSeguro recommends that you validate the number of digits entered for the credit card, expiration date and card verification code before submitting the payment information. This will help reduce transaction declines due to customer error.

Request

📘

Requesting a raw credit card payment in Production

https://api.boacompra.com/transactions

Method: POST

🚧

Requesting a credit card payment in Sandbox

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

Method: POST

Example of a request using cURL

curl -X POST \
  'https://api.boacompra.com/transactions' \
  -H 'accept: application/vnd.boacompra.com.v2+json; charset=UTF-8' \
  -H 'authorization: 123:ba567109f868df40c7cda9c5563bf2a9cdcb8b6b654654165' \
  -H 'content-type: application/json' \
  -d '{
     "transaction":{
        "reference":"REF-RAW-CC-1539193167",
        "project-number":1,
        "country":"BR",
        "currency":"BRL",
        "checkout-type":"direct",
        "notification-url":"https://billing.checkout.com/processing",
        "language":"pt-BR"
     },
     "charge":[
        {
           "amount":50.00,
           "payment-method":{
              "type":"credit-card"
           },
           "payment-info":{
              "installments":2,
              "credit-card":{
                 "number":"4073020000000002",
                 "cvv":"123",
                 "expiration-date":"2020-12"
              }
           }
        }
     ],
     "payer":{
        "name":"John Doe",
        "email":"[email protected]",
        "ip":"64.128.112.215",
        "phone-number": "+5511991234556",
        "document":{
           "type":"CPF",
           "number":"31192071280"
        }
     },
      "cart": [
          {
              "quantity": 1,
              "description": "Action figure - Spider-man",
              "category": "Collectibles",
              "type": "digital",
              "unit-price": 50.00
          }
      ]
  }'
PropertyDescriptionTypeSizeMandatory
transaction.referenceMerchant Transaction IdentifierString64Yes
transaction.project-numberMerchant Project Identifier. Default value is 1Integer--
transaction.countryCountry of the payment. Accepts only BRString2Yes
transaction.currencyCurrency of the transaction. Accepts only BRLString3
transaction.checkout-typeCheckout type of the transaction. Accepts only directString-Yes
transaction.notification-urlURL (must bind ports 80 or 443) used to send transaction statuses changes notifications by HTTPString-Yes
transaction.languageLanguage used. Accepts pt-BR, en-US, es-ES, pt-PT and tr-TRString5Yes
charge[]Set of payments.Array1Yes
charge[].amountAmount of the transaction. Separating cents by dot, with two decimal places. Amount sum must be equal to shipping.cost plus cart items valueDoubleMin of 0.20Yes
charge[].payment-method.typePayment Method type (credit-card, postpay, e-wallet or eft)String-Yes
charge[].payment-method.sub-typeMeans of Payment Sub-type. The Card issuerString--
charge[].payment-info.installmentsInstallments quantityStringMin of 1Yes
charge[].payment-info.credit-card.numberPayer Card NumberString19Yes
charge[].payment-info.credit-card.cvvPayer Card Secutiry CodeString4Yes
charge[].payment-info.credit-card.expiration-datePayer Card Expiry date printed. Pattern YYYY-MMString7Yes
payerSet of customer's informationObject-Yes
payer.namePayer name (see more)StringUp to 255Yes
payer.emailPayer emailStringUp to 60Yes
payer.ipCustomer IP. accepts IPv4 or IPv6String-Yes
payer.phone-numberCustomer phone number. e.g (+5544999884455)String-No
payer.document.typePayer Document Type. Accepts: cpf and cnpjString-Yes
payer.document.numberPayer Identification document. Remove special charactersString-Yes
cart[]Set of items (at least one Item)ArrayMin of 1Yes
cart[].quantityItem quantityIntegerMin of 1Yes
cart[].descriptionItem descriptionString1-200Yes
cart[].unit-pricePrice per unit. Separating cents by dot, with two decimal placesDoubleMin of 0.01Yes
cart[].typeItem type (see more)String-Yes
cart[].categoryItem categoryString1-64No

Response

Example of a response

{
      "transaction": {
        "code": "111181153",
        "reference": "REF-RAW-CC-1539193167",
        "amount": 100,
        "status": "PENDING",
        "currency": "BRL",
        "country": "BR",
        "payer-email": "[email protected]",
        "date-created": "2018-10-10T14:39:32.991217999-03:00"
      }
    }
PropertyDescriptionTypeSizeFormat
transaction.codePagSeguro´s referenceStringUp to 36e.g.: 111181153
transaction.referenceMerchant´s referenceStringUp to 64XXX-XXX-XX-XXXXXXXXXX
transaction.amountTransaction AmountNumber-e.g.: 50.0
transaction.statusCurrent status (see more)String-e.g.: PENDING
transaction.currencyCurrency transactionString3e.g.: BRL
transaction.countryCurrency transactionString2e.g.: BR
transaction.payer-emailPayer emailStringUp to 60e.g.: [email protected]
transaction.date-createdDate of creationString-e.g.: 2018-10-10T14:39:32.991217999-03:00

Tokenization

When applied to data security, tokenization is the process of substituting a sensitive data
element with a non-sensitive equivalent, referred to 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 a transaction,
and also allows the merchant to create its own service of recurring payment.

How does it work?

  1. Merchant submits the payment info to /transactions using the parameter charge[].payment-info.save as true.
  2. PagSeguro creates a unique token (payment-method.code) and maps it into the payment-method object reponse.
  3. PagSeguro returns the transaction object and payment-method object.
  4. The merchant stores the payment-method object.
  5. The transaction status is changed to COMPLETE.
  6. The merchant can now use charge[].payment-info.code to create future transactions for the same customer.

🚧

Important

  • The tokenization feature can only be used with credit card payment method.
  • The credit card code can only be used after the status of the initial transaction is changed to COMPLETE.
  • The credit card code can only be used with the same customer email for which 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.

Step 1: Saving the Payment Method

The merchant creates a payment request that demands the payment method to be saved.

Request

Example of a request using credit card tokenization

{
  "transaction": {
    "reference": "REF-XXX-1234567890",
    "project-number": 1,
    "country": "BR",
    "currency": "BRL",
    "checkout-type": "direct",
    "notification-url": "https://billing.checkout.com/processing",
    "language": "pt-BR"
  },
  "charge": [
    {
      "amount": 100.00,
      "payment-method": {
        "type": "credit-card",
        "sub-type": "mastercard"
      },
      "payment-info": {
        "installments": 3,
        "token": "eyJkbmEiOiI2NzY3YzAxNDEzNGM0NTc4ODg0ZjU2MjdmYTI0ZGVhZiIsImlwIjoiMjAwLjIyMS4xMzAuNDkiLCJkZiI6ImNmYWI3MDcxMDJlZDQ4MjU4MzJhNmY2MDBhNWZjZjc2In0=",
        "save": true
      }
    }
  ],
  "payer": {
    "name": "John Doe",
    "email": "[email protected]",
    "birth-date": "1988-12-25",
    "phone-number": "+5511987654321",
    "document": {
      "type": "CPF",
      "number": "00000000191"
    },
    "address": {
      "street": "Rua Teste",
      "number": "1102",
      "complement": "AP 10",
      "district": "Bairro Teste",
      "state": "PR",
      "city": "Maringá",
      "country": "BR",
      "zip-code": "87030010"
    },
    "ip": "200.221.118.80"
  },
  "shipping": {
    "cost": 0,
    "address": {
      "street": "Rua Teste",
      "number": "1102",
      "complement": "AP 0",
      "district": "Bairro Teste",
      "state": "PR",
      "city": "Maringá",
      "country": "BR",
      "zip-code": "87030000"
    }
  },
  "cart": [
    {
      "quantity": 1,
      "description": "Calça Jeans",
      "category": "Collectibles",
      "type": "physical",
      "unit-price": 1
    }
  ]
}

Response

Example of a response containing a payment method

{
  "transaction": {
    "code": "99481144",
    "reference": "REF-XXX-1234567890",
    "amount": 100,
    "status": "PENDING",
    "currency": "BRL",
    "country": "BR",
    "payer-email": "[email protected]",
    "date-created": "2018-10-09T15:16:31.76093422-03:00"
  },
  "payment-methods": [
    {
      "code": "5B990EBB79F54E65B752EC555BD3A9B6",
      "credit-card": {
        "brand": "mastercard",
        "masked-number": "************5099",
        "expiration-date": "2021-12"
      },
      "date-created": "2018-10-09T15:16:32.508735399-03:00"
    }
  ]
}

Step 2: Merchant Stores the Payment Method

The merchant stores the following object in other to have features like one-click buying, retry sending a transaction, among others alike.
This payment method code can only be used to create a new transaction after the transaction's status is changed to COMPLETE..

Example of a payment method that the merchant can store on their side

{
  "code": "5B990EBB79F54E65B752EC555BD3A9B6",
  "credit-card": {
    "brand": "mastercard",
    "masked-number": "************5099",
    "expiration-date": "2021-12"
  },
  "date-created": "2018-10-09T15:16:32.508735399-03:00"
}

Step 3: Merchant Uses the Saved Payment Method

The merchant uses the stored payment method to create a new transaction for the same customer

Example of a request using the stored payment method

{
  "transaction": {
    "reference": "REF-XXX-1234567891",
    "project-number": 1,
    "country": "BR",
    "currency": "BRL",
    "checkout-type": "direct",
    "notification-url": "https://billing.checkout.com/processing",
    "language": "pt-BR"
  },
  "charge": [
    {
      "amount": 100.00,
      "payment-method": {
        "type": "credit-card",
        "sub-type": "mastercard"
      },
      "payment-info": {
        "installments": 3,
        "code": "5B990EBB79F54E65B752EC555BD3A9B6"
      }
    }
  ],
  "payer": {
    "name": "John Doe",
    "email": "[email protected]",
    "birth-date": "1988-12-25",
    "phone-number": "+5511987654321",
    "document": {
      "type": "CPF",
      "number": "00000000191"
    },
    "address": {
      "street": "Rua Teste",
      "number": "1102",
      "complement": "AP 10",
      "district": "Bairro Teste",
      "state": "PR",
      "city": "Maringá",
      "country": "BR",
      "zip-code": "87030000"
    },
    "ip": "200.221.118.80"
  },
  "shipping": {
    "cost": 0,
    "address": {
      "street": "Rua Teste",
      "number": "1102",
      "complement": "AP 10",
      "district": "Bairro dos testes",
      "state": "PR",
      "city": "Maringá",
      "country": "BR",
      "zip-code": "87030000"
    }
  },
  "cart": [
    {
      "quantity": 1,
      "description": "Calça Jeans",
      "category": "Collectibles",
      "type": "physical",
      "unit-price": 1
    }
  ]
}

Available Brands

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

Updated over 1 year ago