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.
É 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 PicpayTransparent = require('pacote');
//ex: const PicpayTransparent = 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 PicpayTransparent
, 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 MerchantToken
dessa forma aqui:
PicpayTransparent.setCredentials({
merchantCredential: "{{cnpj}}",
merchantToken: "{{merchantToken}}"
})
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.
PicpayTransparent.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"
}]
}
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
PicpayTransparent.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.
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"
},
....