Skip to main content

​
Integration

Before starting the integration, it is necessary to keep in mind that, as this is a delicate operation involving sensitive data from an end user, it is necessary that your development and production environment is secure and has an https certificate. We recommend installing and using the ngrok CLI.

​
Importing the SDK

The first step to import the SDK is to check your integration environment:

Development (Sandbox)

For development use the sandbox SDK through the URL below.
https://sdk.sandbox.wepayments.com.br/v1

Production

For the production environment use the production SDK through the URL below.
https://sdk.wepayments.com.br/v1
To import the transparent checkout SDK, you need to add the following code block to the head of your HTML. 
<!DOCTYPE html>
<html>
  <head>
    <script
      src="URL_SDK_WEPAYMENTS"
      type="text/javascript"
    ></script>
    ...
  </head>
  <body>
    ...
  </body>
</html>

​
Initializing the SDK

The SDK can be initialized in 2 ways: manually or automatically.

​
Initialize manually

To manually initialize the SDK, you need to have a publicKey, this way the transparent checkout SDK will have the necessary configurations for your merchant. Your publicKey is visible within the payin settings view in your dashboard. With your key in hand, you now need to instantiate the SDK as follows: 
const sdk = WEPayin.init({
  publicKey: "YOUR_PUBLIC_KEY",
});

​
Initialize automatically

To automatically initialize the SDK, you need to include the window.autoInitWeSdk instruction before including the script on the page, as in the example: 
<!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>
With this, the SDK will be instantiated in the global variable window.wesdk.
It is also necessary to whitelist, in your dashboard, the domain of the page where the SDK is being included. To do this, access Charges > SDK Management.

​
Retrieve installments

With the SDK instantiated, we now have control over the installments method, where we can retrieve data related to the installments that the customer can make the payment. To obtain this data, we must send to the SDK the total amount of the payment that the customer wants to make (in cents) and also the first six digits of the customer’s card number, this number is called BIN.

​
Payload

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

​
Parameters

ParameterTypeDescription
amountInCentsnumber | stringTotal amount in cents of the charge (Required)
binstringFirst six digits of the credit card (Required)

​
Response

The installments method used is a Promise that returns the following object, according to your configured number of installments: 
{
  "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"
  }
}

​
Generate card token

As informed at the beginning of the integration, the SSL certificate is necessary to operate. As this is a delicate operation involving sensitive data from an end user, it is necessary that your development and production environment is secure and has an https certificate.
With SSL configured, we can start tokenizing the credit card data. For this, it is necessary to call the tokenize method passing its required parameters about the customer’s card data.

​
Payload

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

​
Parameters

ParamTypeDescription
cardNumberstringCredit card number (16-19) - Required
cardholderNamestringCardholder name - Required
cardExpirationMonthstringExpiration month (MM) - Required
cardExpirationYearstringExpiration year (YY - YYYY) - Required
securityCodestringSecurity code number (3-4) - Required
identificationTypestringDocument type (CPF - CNPJ) - Required
identificationNumberstringDocument number - Required

​
Response

The tokenize method used is a Promise that returns the following object: 
{
  "token": "8e832a8bd0b896fd203fb33b13a4c601",
  "expirationMonth": 11,
  "expirationYear": 2025,
  "firstSixDigits": "503143",
  "lastFourDigits": "6351",
  "cardholder": {
    "identification": {
      "number": "12345678912",
      "type": "CPF"
    },
    "name": "CARDHOLDER NAME"
  }
}
With the data finally tokenized, we can now start the process of creating and paying the charge, which will occur simultaneously through a single call to the WEpayments API.

​
Checkout

With the credit card token, the number of installments that will be paid and the other data related to the charge, we can start the checkout. Through the endpoint below that is currently used to create charges, a new object called checkout will now be passed in its payload. If this object is filled in, at the time of creating the charge, its payment will also be made. Endpoint: POST /v1/payin/payments/credit-card

​
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"
    }
  }
}
More details about the required fields and types of values to be sent to this endpoint in our OpenAPI.

​
Response

After sending the data, the API will then return the response with the payment status at the time of completion of the request, as in the example below. 
{
  "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,
  "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": []
}
After this request has been completed, it is possible to check the status of the charge through a GET method at the following endpoint - /v1/payin/payments/credit-card/{key}/status - Passing as key the key of the charge created and returned in the Response above.

Create Charge

Create a new credit card charge

Callback Charge

Receive charge callbacks

About Credit Card

Learn about credit card charges

FAQ

Frequently asked questions