Transparent Checkout via SDK

The PicPay SDK for Checkout API is a service that offers greater buyer security and control over the transparent checkout experience. It is ideal for stores that do not have the structure to comply with all PCI DSS security requirements when using credit cards.

This way, sending your customer's payment data securely, directly into our system. The buyer's card data, such as card number and expiration date, does not travel through the store environment and is stored in encrypted form (token) in the PicPay environment, which is PCI DSS 3.2 certified.

What is PCI DSS certification?

It is a global card data security standard. PCI DSS is designed to encourage and enhance the security of payment data and facilitate the widespread adoption of consistent data security measures. Certification is mandatory for an e-commerce store to receive, process and store card data.

Installing the Transparent Checkout SDK

It is possible to install Transparent Checkout in two ways, using NPM or CDN.

Installation via NPM

To install using the transparent checkout NPM package, run the following command, considering the package according to the desired environment:

Environment	Package
Development	checkout-transparent-dev
Production	checkout-transparent

npm i package 
//ex: npm i checkout-transparent-dev

After installation, import it into your application:

const PicpayTransparent = require('package');
//ex: const PicpayTransparent = require('checkout-transparent-dev')

Installation via CDN

To install using CDN, simply insert the transparent checkout script pointing to the location where it is saved.

Environment	Link
Development	https://checkout-qa.picpay.com/cdn/pp-transparent-v1.0.0.js
Production	https://checkout.picpay.com/cdn/pp-transparent-v1.0.0.js

<script src="INSERT-LINK-HERE"></script>

After installation, using one of the options shown above, the object called PicpayTransparent will be available, which contains the methods necessary to tokenize the card.

How to use the SDK

Step 1: Register Credentials

We need to register the credentials of the store where the card will be tokenized, calling the SDK's setCredentials method. In this method it is necessary to pass the MerchantCredential (CNPJ) and the MerchantToken like this here:

PicpayTransparent.setCredentials({
    merchantCredential: "{{cnpj}}", 
    merchantToken: "{{merchantToken}}"
})

Step 2: Obtain the Card Flag

After assigning the credentials, we will obtain the card flag from its bin by calling the following method.

PicpayTransparent.getCardBrand({
    bin: "411111", 
    success, 
    error
})

Where success and error are mandatory parameters, as they are callback functions that receive the body of the response. This way, you can carry out the appropriate treatment according to the success or failure scenario.

function success(body){ 
    //treatment for success here
}

//Format `body` on success:
{
   "brand":"Visa"
} 

function error(body){
    //error treatment here
}

//format `body` when error:
{
   "errors": [{
      "errorCode": 1,
      "message": "Propriedade 'CardBin' está ausente",
      "field": "CardBin"
   }]
}

What is bin?

The Bank Identification Number corresponds to the first 6 digits of the card and serves to identify the brand.

Step 3: Create the Card Token

After the card flag returns, create the card token as per the following examples, informing the success and error callback functions to carry out the appropriate handling of success and error scenarios after the requests return.

//1. Create the `card` object
const card = {
   brand: "Visa",
   number: "4111111111111111",
   holderName: "FULANO SILVA",
   holderDocument: "65844359038",
   expirationMonth: "02",
   expirationYear: "2026",
   cvv: "223"
}

//2. Create handler functions for success and failure 
function success(body) {
    //logic for success
}

function error(body){
    //logic for error
}

//3. Call the SDK's `createTemporaryCard` method
PicpayTransparent.createTemporaryCard({
    card, 
    success, 
    error
})

Value of body for success:

{
   temporaryToken:"card_t/AIChh82EgN440hTW8vQqHcPC82EwBW"
}

body value for error:

{
   "errors":[{
      "errorCode":1,
      "message":"Propriedade 'Cvv' está ausente.",
      "field":"Cvv"
   }]
}

For multiple cards, simply call this method again with the new card data and use it in the transaction objects below.

Step 4: Use the Card Token

With the temporaryCardToken generated, simply charge using the following endpoint. This call must occur through your server.

POST /v1/charge/authorization

Below is an example of a request using this temporary token.

curl -L -X POST '<https://checkout-api-sandbox.picpay.com/api/v1/charge/authorization>' \\
-H 'Content-Type: application/json' \\
-H 'Accept: application/json' \\
-H 'Authorization: Bearer <TOKEN>' \\
--data-raw '{
  "paymentSource": "GATEWAY",
  "smartCheckoutId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "merchantChargeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "customer": {
		...
  },
  "transactions": [
    {
      "paymentType": "CREDIT",
      "amount": 100,
      "softDescriptor": "Sale product x",
      "transactionId": "string",
      "entryMode": "CREDENTIAL_ON_FILE",
      "issuerTransactionId": "string",
      "credit": {
        "temporatyCardToken": "card_t/AIChh82EgN440hTW8vQqHcPC82EwBW",
        "installmentNumber": 1,
        "installmentType": "NONE"
        "billingAddress": {
            "street": "Rua Gil Martins de Oliveira",
            "number": "315",
            "neighborhood": "Santa Lucia",
            "city": "Vitória",
            "state": "ES",
            "country": "Brasil",
            "zipCode": "29056300",
            "complement": "PicPay"
        },
        ....