Checkout transparente

Tudo o que você precisa saber sobre o nosso checkout transparente!

Integração

Antes de iniciar a integração é necessário ter em mente que, como se trata de uma operação delicada que envolve dados sensíveis de um usuário final, é necessário que seu ambiente de desenvolvimento e de produção seja seguro e possua um certificado https. O que recomendamos é a instalação e utilização da CLI do ngrok.

Importando a SDK

O primeiro passo para a importação da SDK é o de conferir seu ambiente de integração:

Para desenvolvimento utilize a SDK de sandbox por meio da URL abaixo.

https://sdk.sandbox.wepayments.com.br/v1

Para o ambiente de produção utilize a SDK de produção por meio da URL abaixo.

https://sdk.wepayments.com.br/v1

Para realizar a importação da SDK de checkout transparente é necessário adicionar ao head de seu HTML o seguinte bloco de código.

<!DOCTYPE html>
<html>
  <head>
    <script
      src="URL_SDK_WEPAYMENTS"
      type="text/javascript"
    ></script>
    ...
  </head>
  <body>
    ...
  </body>
</html>

Inicializando a SDK

A SDK pode ser inicializada de 2 maneiras: manualmente ou automaticamente.

Iniciar manualmente

Para inicializar manualmente a SDK, é necessário que possua uma publicKey, dessa maneira a SDK do checkout transparente possuirá as configurações necessárias de seu merchant.

Sua publicKey é visível dentro da visualização das configurações de payin em seu painel:

SDK publicKey

Com sua chave em mãos, agora é necessário instanciar à SDK da seguinte maneira:

const sdk = WEPayin.init({
  publicKey: "YOUR_PUBLIC_KEY",
});

Iniciar automaticamente

Para inicializar automaticamente a SDK, é necessário incluir a instrução window.autoInitWeSdk antes da inclusão do script na página, como no exemplo:

<!DOCTYPE html>
<html>
  <head>
    <script type="text/javascript">
      window.autoInitWeSdk = true;
    </script>

    <script
      src="URL_SDK_WEPAYMENTS"
      type="text/javascript"
    ></script>
    ...
  </head>
  <body>
    ...
  </body>
</html>

Com isso, a SDK será instanciada na variável global window.wesdk.

E também é necessário liberar, em seu painel, o domínio da página na qual a SDK está sendo incluída. Para isso, acesse Cobranças > Gerenciamento SDK.

Recuperar parcelas

Com a SDK instanciada, temos agora controle sobre o método installments, onde podemos recuperar dados relativos às parcelas que o cliente poderá efetuar o pagamento. Para obtermos esses dados devemos enviar à SDK o valor total do pagamento que o cliente deseja efetuar (em centavos) e também os seis primeiros dígitos do número do cartão do cliente, este número é chamado de BIN.

Payload
const installments = await sdk.installments({
  amountInCents: 100000,
  bin: "533278",
});

Parâmetro	Tipo	Descrição
`amountInCents`	number \| string	Total em centavos da cobrança	Obrigatório
`bin`	string	Seis primeiros dígitos do cartão de crédito	Obrigatório

O método installments utilizado é uma Promise que retorna o seguinte objeto, de acordo com o seu número de parcelas configuradas:

Response
{
    "installments": [
        {
            "installmentsNumber": 1,
            "installmentsAmountInCents": 100000,
            "installmentsTotalAmountInCents": 100000,
            "recommendedMessage": "1 parcela de R$ 1.000,00 (R$ 1.000,00)"
        },
        {
            "installmentsNumber": 2,
            "installmentsAmountInCents": 50000,
            "installmentsTotalAmountInCents": 100000,
            "recommendedMessage": "2 parcelas de R$ 500,00 (R$ 1.000,00)"
        }
    ],
    "issuer": {
        "name": "Visa",
        "thumbnail": "http://logos.com/visa.png",
        "paymentMethodId": "visa"
    }
}

Gerar token do cartão

Como informado no início da integração, o certificado SSL é necessário para operar. como se trata de uma operação delicada que envolve dados sensíveis de um usuário final, é necessário que seu ambiente de desenvolvimento e de produção seja seguro e possua um certificado https.

Com a SSL configurada, podemos iniciar a tokenização dos dados do cartão de crédito. Para tal faz-se necessário a chamada do método tokenize passando seus parâmetros obrigatórios sobre os dados do cartão do cliente.

Payload
const cardToken = await sdk.tokenize({
  cardNumber: "5031433215406351" ,
  cardholderName: "CARDHOLDER NAME",
  cardExpirationMonth: "11",
  cardExpirationYear: "2025",
  securityCode: "123",
  identificationType: "CPF",
  identificationNumber: "53595590040",
});

O método tokenize utilizado é uma Promise que retorna o seguinte objeto:

Response
{
    "token": "8e832a8bd0b896fd203fb33b13a4c601",
    "expirationMonth": 11,
    "expirationYear": 2025,
    "firstSixDigits": "503143",
    "lastFourDigits": "6351",
    "cardholder": {
        "identification": {
            "number": "12345678912",
            "type": "CPF"
        },
        "name": "CARDHOLDER NAME"
    }
}

Param	Type	Description
cardNumber	string	Número do cartão de crédito (16-19)	Required
cardholderName	string	Titular do cartão	Required
cardExpirationMonth	string	Mês de expiração (MM)	Required
cardExpirationYear	string	Ano de expiração (AA - AAAA)	Required
securityCode	string	Número do código de segurança (3-4)	Required
identificationType	string	Tipo de documento (CPF - CPNJ)	Required
identificationNumber	string	Número do documento	Required

Com os dados enfim tokenizados, podemos agora dar início ao processo de criação e pagamento da cobrança, que ocorrerá de maneira simultânea por meio de uma única chamada à API da WEpayments.

Checkout

Com o token do cartão de crédito, a quantidade de parcelas que será efetuado o pagamento e os demais dados referentes a cobrança, podemos iniciar o checkout. Por meio do endpoint abaixo que é utilizado atualmente para criação das cobranças, será passado agora um novo objeto em seu payload chamado checkout. Caso esse objeto esteja preenchido, no momento da criação da cobrança, será efetuado também seu pagamento.

endpoint: /v1/payin/payments/credit-card

method: POST

Payload
{
  "title": {
    "expireDate": "2023-03-16T18:46:11",
    "amountInCents": 100000,
    "instructions": "Payin instructions"
  },
  "buyer": {
    "email": "buyer@email.com",
    "name": "Buyer Name",
    "document": {
      "type": "CPF",
      "number": "53595590040"
    },
    "address": {}
  },
  "statement_descriptor": "merchant_descriptor",
  "clientId": 123,
  "external_urls": {},
  "product_info": [
    {
      "title": "Product title",
      "category_id": "1",
      "id": "1",
      "quantity": "1",
      "unit_price": "12300",
      "description": "Product description"
    }
  ],
  "sender": {
    "name": "",
    "document": "",
    "helpdesk": "merchant.com"
  },
  "checkout": {
    "token": "058f00af2efbadfbc85dddb532cf19d0",
    "installments": 2,
    "payment_method_id": "master",
    "payer_name": "Payer Name",
    "payer_phone": "11999999999",
    "payer_address": {
      "zip_code": "01311000",
      "street_name": "Avenida Paulista",
      "street_number": "123"
    }
  }
}

Mais detalhes sobre os campos obrigatórios e tipos de valores a serem enviados nesse endpoint em nossa OpenAPI. Após o envio dos dados, a API devolverá então a resposta com o status do pagamento no momento do término da requisição, como o exemplo abaixo.

Response
{
  "id": 1234,
  "key": "4d81e367c4ba0r07e3cb2ag4b1bbfe1f5bdcf15a5c74989a4bfea9034f9a60x6",
  "clientId": 123,
  "subscriptionId": null,
  "clientName": "WE Payments - Credit Card",
  "senderName": null,
  "senderDocument": null,
  "senderHelpdesk": "merchant.com",
  "buyerName": "Buyer Name",
  "buyerDocument": "53595590040",
  "buyerEmail": "buyer@email.com",
  "customNumber": null,
  "ourNumber": null,
  "digitableLine": null,
  "barCodeNumber": null,
  "status": {
    "id": 6,
    "name": "Aguardando Aprovação"
  },
  "sender": {
    "name": null,
    "helpdesk": null,
    "document": null
  },
  "typePayin": "credit-card",
  "instructions": "",
  "amountCents": 100000,
  "paidAmountCents": null,
  "paidAt": null,
  "expiresAt": "2023-03-16 18:46:11",
  "createdAt": "2023-03-15T15:01:23.000000Z",
  "fine": null,
  "discount": null,
  "splits": [],
  "statusHistory": [
    {
      "status": {
        "id": 1,
        "name": "Criado"
      },
      "id": 9557,
      "updatedAt": "2023-03-15T15:01:23.000000Z"
    },
    {
      "status": {
        "id": 6,
        "name": "Aguardando Aprovação"
      },
      "id": 9558,
      "updatedAt": "2023-03-15T15:01:23.000000Z"
    },
  ],
  "refundMode": "FULL_REFUND_CLIENT",
  "refundAmountCents": 0,
  "payinRefunds": []
}

Após esta requisição ter sido concluída, é possível verificar o status da cobrança por meio de um método GET no seguinte endpoint - /v1/payin/payments/credit-card/{key}/status - Passando como key a chave da cobrança criada e devolvida na Response acima.

Integração​

Importando a SDK​

Inicializando a SDK​

Iniciar manualmente​

Iniciar automaticamente​

Recuperar parcelas​

Gerar token do cartão​

Checkout​