Checkout Transparente via SDK

O SDK do PicPay para a API do Checkout é um serviço que oferece mais segurança ao comprador e controle sobre a experiência do checkout transparente. É ideal para a loja que não possui estrutura para cumprir todos os requisitos de segurança do PCI DSS no uso de cartões de crédito.

Dessa forma, o envio de dados do pagamento do seu cliente de forma segura, diretamente em nosso sistema. Os dados do cartão do comprador, tais como número do cartão e data de validade, não trafegam pelo ambiente da loja e são armazenados de forma criptografada (token) no ambiente do PicPay, que conta com a certificação PCI DSS 3.2.

O que é a certificação PCI DSS?

É um padrão global de segurança de dados de cartões. O PCI DSS foi desenvolvido para incentivar e aprimorar a segurança de dados de pagamento e facilitar a ampla adoção de medidas consistentes de segurança de dados. A certificação é obrigatória para que um e-commerce possa receber, tratar e armazenar dados de cartão.

Instalação do SDK Checkout Transparente

Atualmente é possível instalar o Checkout Transparente de duas formas, utilizando o NPM ou CDN.

Instalação via NPM

Para instalar utilizando o pacote NPM do checkout transparente execute o comando a seguir, considerando o pacote de acordo com o ambiente desejado:

Ambiente	Pacote
Desenvolvimento	checkout-transparent-dev
Produção	checkout-transparent

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

Após a instalação, importe-o em sua aplicação:

const CheckoutTransparent = require('pacote');
//ex: const CheckoutTransparent = require('checkout-transparent-dev')

Instalação via CDN

Para instalar utilizando CDN, basta inserir o script do checkout transparente apontando para o local onde ele esta salvo.

Ambiente	Link
Desenvolvimento	https://checkout-qa.picpay.com/cdn/pp-transparent-v1.0.0.js
Produção	https://checkout.picpay.com/cdn/pp-transparent-v1.0.0.js

<script src="INSERIR-LINK-AQUI"></script>

Logo após a instalação, utilizando uma das opções mostradas acima, estará disponível o objeto chamado CheckoutTransparent, o qual contém os métodos necessários para tokenizar o cartão.

Como utilizar a SDK

Passo 1: Registrar Credenciais

Precisamos registrar as credenciais da loja na qual o cartão será tokenizado, chamando o método setCredentials da SDK. Nesse método é necessário passar a MerchantCredential (CNPJ) e o TransparentToken dessa forma aqui:

CheckoutTransparent.setCredentials({
    merchantCredential: "{{cnpj}}", 
    transparentToken: "{{transparentToken}}"
})

Obs

Para obter o transparentToken é necessário entrar em contato com PicPay.

Passo 2: Obter a Bandeira do Cartão

Após atribuirmos as credenciais, vamos obter a bandeira do cartão pelo seu bin através da chamada ao método a seguir.

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

Onde success e error são parâmetros obrigatórios, dado que são funções de callback que recebem o body da resposta. Dessa forma, você pode realizar o tratamento adequado de acordo com o cenário de sucesso ou falha.

function success(body){ 
    //tratativa para sucesso aqui
}

//Formato de `body` quando sucesso:
{
   "brand":"Visa"
} 

function error(body){
    //tratativa para erro aqui
}

//formato de `body` quando erro:
{
   "errors": [{
      "errorCode": 1,
      "message": "Propriedade 'CardBin' está ausente",
      "field": "CardBin"
   }]
}

O que é bin?

O Bank Identification Number ou Número de Identificação Bancária em português, correspondem aos 6 primeiros dígitos do cartão e serve para identificar a bandeira.

Passo 3: Criar o Token do Cartão

Após o retorno da bandeira do cartão, crie o token do cartão conforme os exemplos a seguir, informando as funções de callback success e error para realizar as devidas tratativas dos cenários de sucesso e erro após o retorno das requisições.

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

//2. Crie as funções para sucesso e falha
function success(body) {
    //lógica para sucesso
}

function error(body){
    //lógica para erro
}

//3. Chame o método `createTemporaryCard` do SDK
CheckoutTransparent.createTemporaryCard({
    card, 
    success, 
    error
})

Valor do body para success:

{
   temporaryToken:"card_t/AIChh82EgN440hTW8vQqHcPC82EwBW"
}

Valor do body para error:

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

Para múltiplos cartões, basta chamar esse método novamente com os dados do novo cartão e utilizar nos objetos de transação abaixo.

Passo 4: Use o Token do Cartão

Com o temporaryCardToken gerado, basta realizar uma cobrança utilizando o endpoint a seguir. Esta chamada deve ocorrer através do seu servidor.

POST /v1/charge/authorization

Abaixo um exemplo de requisição usando esse token temporário.

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": "Venda do produto 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"
        },
        ....