Documentation

Encrypted Credit Card Payment

Suggest Edits

To securely process credit card payments without sensitive data touching your servers, PagSeguro provides an encrypted direct-token method for credit card data. This ensures that you remain PCI-DSS compliant while offering customers a secure transaction process.

Encrypted Credit Card Transaction Flow

  1. Merchant → Customer: Load PagSeguro script in the client's browser to encrypt data.
  2. Merchant → PagSeguro: Get installment options from PagSeguro's system (optional).
  3. Merchant → Customer: Dysplay available installment options (optional).
  4. Customer → Merchant: Fill and submit payment info.
  5. Merchant → PagSeguro: Submit encrypted data to the Create a payment endpoint.
  6. PagSeguro → Merchant: Create order and return transaction status and ID.
  7. Merchant → Customer: Return transaction status to the customer.

Follow the steps below to create an encrypted credit card payment:

Step 1: Collecting Customer's Information

Before initiating the payment, you need to collect all necessary information from the customer. This includes basic details such as their name, email, birth date, contact information, and address. Make sure that all fields are correctly filled out to avoid any issues during the payment process.

🚧

Delivery Address

Payer address is required when the cart item type is physical.

Sensitive credit card information must be encrypted before transmission. PagSeguro provides a JavaScript library to securely collect and transmit customer payment details.

🚧

Data Validation

Ensure that the card details are validated before submission to avoid errors such as incorrect card numbers, expiration dates, or CVVs.

To initiate the encrypted credit card payment, you need to use the Direct Checkout JS. This script helps in encrypting the payment data before transmitting it to PagSeguro.

Include the Direct Checkout JavaScript

You must include the following <script> tag to load the PagSeguro payment library:

<script src="http://stc.boacompra.com/payment.boacompra.min.js"></script>

📘

Script Loading Order

This script should be included early in the page load to ensure that all dependencies are correctly loaded before proceeding with the payment flow.

Direct Token Method

The Direct Token method allows you to send encrypted credit card data to PagSeguro, ensuring compliance with PCI-DSS standards.

👍

Security Reminder

Avoid storing raw credit card data. Only transmit tokenized card data unless your system is PCI compliant.

Here’s an example of how to generate a Direct Token using the getDirectToken method:

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

Below, you can see the descriptions of the needed parameters:

PropertyTypeDescription
creditCardstringThe credit card number
cvvstringThe credit card CVV
expirationobjectAn object with expiration data
expiration.monthstringThe expiration month (2 digits)
expiration.yearstringThe expiration year (4 digits)

The callback function returns two parameters: an error (if any) and the generated token.

Full Example

This is a full HTML implementation example for generating a Direct Token using PagSeguro's JavaScript library.

<!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): Getting Credit Card Brand and Installments

Credit card installment options allow customers to divide payments into smaller amounts. Installments are available for credit card transactions in Brazil.

Installments Available in Brazil

Credit card installment options:

  • Visa, MasterCard, American Express, Elo, Diners, Hipercard: Up to 12 installments.

📘

Minimum Installment Amount

The minimum installment amount is 5 BRL.

Check Card's Brand and Installments

You can check the card's brand and available installment options through the same endpoint with the Get brand and installments endpoint. To use this endpoint, you'll need to send the card's first six digits, the country of payment, and the order's value and currency. Below is an example request and response:

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'

{
  "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 Card's Brand

To check only the card's brand, you can use the Check brand name endpoint. For this endpoint, you'll only need to send the card's first six digits. Below is an example request and response:

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'

{
    "bin": {
        "number": 123456,
        "brand": "visa",
        "cvvSize": 3,
        "expirable": true,
        "validationAlgorithm": "LUHN",
        "installment": true
    }
}

Check Available Installments

To check the available installment options for a specific card, use the Check installment options endpoint. To use this endpoint, you'll need to send the card's brand, the country of payment, and the order's value and currency. Below is an example request and response:

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'

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

Step 3: Requesting a Credit Card Payment

After generating the Direct Token, you can use it to make a credit card payment request by sending it and the other needed information to the Create a payment endpoint. The token goes under the payment-info parameter.

📘

Minimum Transaction Amount

The minimum amount for a credit card transaction is 0.20 BRL.

Below is an example request and response:

{
  "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
    }
  ]
}

{
  "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"
  }
}

Updated about 2 months ago