Card

Step by step to generate a credit card charge in the Efí API

Introduction

Online credit card transactions require only the front number and the code on the back of the card, which can lead to suspicious transactions. Therefore, it is important to adopt security procedures to prevent financial losses, such as Chargebacks.

When a credit card transaction is made, it goes through three stages: authorization from the operator, security analysis, and capture. Each transaction is analyzed to identify possible risks. If approved, the amount is debited on the customer's invoice. Otherwise, the amount remains reserved until the reversal communication is completed and the card limit is restored.

Check out the list of credit cards accepted by Efí

Visa
Master
AmericanExpress
Elo

Attention!

To make a credit card payment, it is necessary to obtain the payment_token of the transaction. Therefore, it is essential to follow the procedures to obtain the payment_token as described in the document before creating the charge with a credit card.

Another important information is that you need to register the business activity in your account. Check more details here.

Obtaining the payment_token

A payment_token is a set of characters generated by the Efí API, representing the payer's card data. It can be configured for single use or recurrent reuse.

For credit card transactions, a preliminary step is performed before creating the charge, where the payment_token is generated. This can be done by transmitting the card data, using either the JavaScript library or the jQuery module.

Card Tokenization

If you need to reuse the payment_token for recurring purposes, use the reuse attribute with the boolean value true. This way, the payment_token can be safely used in more than one transaction without the need to save the card data.

Simulation in the Homologation Environment

Card charges simulation in the Homologation Environment works based on immediate analysis according to the last digit of the credit card number used:

Card with final 1 returns: "reason":"Invalid card data."

Card with final 2 returns: "reason":"Transaction not authorized for security reasons."

Card with final 3 returns: "reason":"Transaction not authorized, please try again later."

All other finals have the transaction approved.

JavaScript Library

This JavaScript library allows for the encryption of card data directly in the client's browser, generating the payment_token, identifying the card brand, and obtaining installment information.

Demonstration

To see how this library is used in a practical example, you can check out a demonstration here.

See more details in the library's GitHub repository.

Installation

Here are some options for installing the library in web projects using pure JavaScript or technologies like Node.js. See the details below:

a) Web Application

We provide two ways to install the library in web applications.

Import via CDN

Import through the CDN link of the library.

script

  <script src="https://cdn.jsdelivr.net/gh/efipay/js-payment-token-efi/dist/payment-token-efi.min.js"></script>

Local Import

Download the library located at /dist/payment-token-efi.min.js, and add it locally to your project.

script

  <script src="./dist/payment-token-efi.min"></script>

b) Package Manager (NPM or Yarn)

If you are using a package manager like npm or yarn, install the library directly:

Command line

  npm install payment-token-efi 
  // or
  yarn add payment-token-efi    

After installation, you can import the library according to the environment you are using:

Universal Module Definition (UMD)

For environments that support Universal Module Definition:

Code

   import EfiPay from "payment-token-efi";

ECMAScript Modules (ESM)

For environments that support ES Modules:

Code

   import EfiPay from "payment-token-efi";

CommonJS (CJS)

For environments that uses the CommonJS standard:

Code

     const EfiPay = require("payment-token-efi");

Note: This library is not compatible with the backend in Node.js

Framework React Native and others (WebView)

For applications that do not have native DOM support, such as React Native, Ionic, Swift, and other similar frameworks, it is necessary to use a WebView component to run the library. The WebView allows the library to function properly by providing a DOM environment for its execution. We have provided here a demonstration example with React Native.

TypeScript Definitions

If you are using TypeScript, when you install the payment-token-efi library, TypeScript should be able to automatically find the types located in types/payment-token-efi.d.ts.

Usage

This script provides four functions that help in processing credit card data:

The first function allows you to check if the script has been blocked by some browser extension or configuration.
The second function allows you to identify the card brand of the card from the number entered.
The third function fetches installment information according to the card receipt settings in your account.
Finally, the fourth function generates the payment token (payment_token) and card mask (card_mask) based on the card data.

To use this script, you need to provide the account Identifier code (payee_code) as a parameter to generate the payment_token from the credit card data. You can obtain this information in your digital account under API > Introduction > Account Identifier. See where to find it. Make sure you have this information available when using the script functions.

a) Check script blocking

Check script blocking

The isScriptBlocked() function checks whether the fingerprint script, which helps maintain transaction security by collecting payer information, is being blocked by any browser extension or configuration. It is recommended to run this function as soon as the checkout page loads, so that it is possible to identify if it has been blocked before the customer attempts to make the payment.

Request

Code

try {
    EfiJs.CreditCard
      .setCardNumber('4485785674290087')
      .verifyCardBrand()
      .then(brand => {
          console.log('Bandeira: ', brand);

          if (brand !== 'undefined') {
              // Example: execute the function to generate the payment_token with the brand identified
          }
      }).catch(err => {
          console.log('Código: ', err.code);
          console.log('Nome: ', err.error);
          console.log('Mensagem: ', err.error_description);
      });
} catch (error) {
  console.log('Código: ', error.code);
  console.log('Nome: ', error.error);
  console.log('Mensagem: ', error.error_description);
}

Responses

The responses below represent consumption Success.

🟢 200

mastercard

b) Identify the card brands

Identify the card brands

function to Identify the card brands

Request

Code

try {
    EfiJs.CreditCard
      .setCardNumber('4485785674290087')
      .verifyCardBrand()
      .then(brand => {
          console.log('Bandeira: ', brand);

          if (brand !== 'undefined') {
              // Example: execute the function to generate the payment_token with the brand identified
          }
      }).catch(err => {
          console.log('Código: ', err.code);
          console.log('Nome: ', err.error);
          console.log('Mensagem: ', err.error_description);
      });
} catch (error) {
  console.log('Código: ', error.code);
  console.log('Nome: ', error.error);
  console.log('Mensagem: ', error.error_description);
}

Responses

The responses below represent consumption Success.

🟢 200

mastercard

c) Search for installment information

Search for installment information

Function to search for installment information

Request

Código

try {
  EfiJs.CreditCard
      .setAccount('Identificador_de_conta_aqui')
      .setEnvironment('production') // 'production' or 'sandbox'
      .setBrand('visa')
      .setTotal(28990)
      .getInstallments()
      .then(installments => {
          console.log('Parcelas', installments);
      }).catch(err => {
          console.log('Código: ', err.code);
          console.log('Nome: ', err.error);
          console.log('Mensagem: ', err.error_description);
      });
} catch (error) {
  console.log('Código: ', error.code);
  console.log('Nome: ', error.error);
  console.log('Mensagem: ', error.error_description);
}

Responses

The responses below represent consumption Success.

🟢 200

  {
    "rate": 0,
    "name": "brand",
    "installments": [{
        "installment": 1,
        "has_interest": false,
        "value": 500,
        "currency": "5,00",
        "interest_percentage": 0
    }]
  }

d) Generate the payment_token and card_mask

Generate the payment_token and card_mask

Function to generate the payment_token and card_mask

Request

Código

try {
  EfiJs.CreditCard
      .setAccount('Identificador_de_conta_aqui')
      .setEnvironment('production') // 'production' or 'sandbox'
      .setCreditCardData({
          brand: 'visa',
          number: '4485785674290087',
          cvv: '123',
          expirationMonth: '05',
          expirationYear: '2029',
          holderName: "Gorbadoc Oldbuck",
          holderDocument: "94271564656",
          reuse: false
      })
      .getPaymentToken()
      .then(data => {
          const payment_token = data.payment_token;
          const card_mask = data.card_mask;

          console.log('payment_token', payment_token);
          console.log('card_mask', card_mask);
      }).catch(err => {
          console.log('Código: ', err.code);
          console.log('Nome: ', err.error);
          console.log('Mensagem: ', err.error_description);
      });
} catch (error) {
  console.log('Código: ', error.code);
  console.log('Nome: ', error.error);
  console.log('Mensagem: ', error.error_description);
}

Responses

The responses below represent consumption Success.

🟢 200

  {
    "payment_token": "47f13d72c883c1547ae4a0df11eb46194f333f85",
    "card_mask": "XXXXXXXXXXXX3991"
  }

e) Enable debugger

Enable debugger

The debugger can be activated to debug and find possible faults.

Request

Código

EfiJs.CreditCard.debugger(true);

Responses

In case of an error, the object as shown below will be returned in the try/catch.

🟢 200

 {
  "code": 3500056,
  "error": "invalid_brand",
  "error_description": "O parâmetro [brand] informado é inválido. As opções válidas são: 'visa', 'mastercard', 'amex', 'diners' ou 'elo'."
} 

Practical Examples

We have provided some usage examples for the main front-end programming languages. Click here to access them.

jQuery module

One option for generating the payment_token from the card data is to use the front-end. To do this, you need a JavaScript code specific to your Efí account. To generate it, follow these steps:

Log in to your Efí account and access API.
Copy your Account identifier (see where)
Paste into the field below and click the Generate button

Attention!

After entering your account identifier, 2 (two) distinct JavaScript codes will be generated.
Copy and use the code corresponding to the desired environment, paying attention to the differences between the "Sandbox" and "Production" environments.

This script will allow you to perform two functions:

getPaymentToken: Generates the payment_token according to the card data;
getInstallments: Returns information about installments according to the receipt settings in your account.

Obtaining a "payment_token" (getPaymentToken) and information about installments (getInstallments)

Code

$gn.ready(function (checkout) {

    checkout.getPaymentToken(
        {
            brand: 'visa', // card brand
            number: '4012001038443335', // número do cartão
            cvv: '123', // card number
            expiration_month: '05', // due month
            expiration_year: '2021', // due year
            reuse: false // tokenization/reuse of payment_token
        },
        function (error, response) {
            if (error) {
                // Handle the error
                console.error(error);
            } else {
                // Handle the answer
                console.log(response);
            }
        }
    );

checkout.getInstallments(
        50000, // total value of the charge
        'visa', // card brand
        function (error, response) {
            if (error) {
                // Handle the error
                console.log(error);
            } else {
                // Handle the answer
                console.log(response);
            }
        }
    );

});

$gn.ready (checkout)

This initialization function allows calling the getPaymentToken and getInstallments functions. You pass an object (checkout) that receives instances of these functions.

getPaymentToken

Function to generate the payment_token

Responses

The Responses below represent Success(200) and consumption failures/errors.

🟢 200
🔴 Failure

{
  "code": 200,
  "data": {
      "payment_token": "47f13d72c883c1547ae4a0df11eb46194f333f85",
      "card_mask": "XXXXXXXXXXXX3991"
  }
}

{
  "code": 3500056,
  "error": "invalid_brand",
  "error_description": "O parâmetro [brand] informado é inválido. As opções válidas são: 'visa', 'mastercard', 'amex', 'diners' ou 'elo'."
}
Ou
{
  "code": 3500058,
  "error": "invalid_card_number",
  "error_description": "O parâmetro [number] informado é inválido."
}
Ou
{
  "code": 3500011,
  "error": "invalid_data",
  "error_description": {
      "property": "cvv",
      "message": "Cvv deve conter entre 3 e 4 caracteres"
  }
}
Ou
{
  "code": 3500062,
  "error": "invalid_expiration_month",
  "error_description": "O parâmetro [expiration_month] informado é inválido."
}
Ou
{
  "code": 3500011,
  "error": "invalid_data",
  "error_description": {
      "property": "expiration_year",
      "message": "Expiration year inválido"
  }
}

getInstallments

Function that returns information about installments

Responses

The responses below represent consumption Success.

🟢 200
🔴 Failure

{
  "code": 200,
  "data": {
      "rate": 0,
      "name": "visa",
      "installments": [
          {
              "installment": 1,
              "has_interest": false,
              "value": 47988,
              "currency": "479,88",
              "interest_percentage": 0
          },
          {
              "installment": 2,
              "has_interest": false,
              "value": 23994,
              "currency": "239,94",
              "interest_percentage": 0
          },
          {
              "installment": 3,
              "has_interest": true,
              "value": 16637,
              "currency": "166,37",
              "interest_percentage": 199
          }
      ]
  }
}

{
  "code": 3500056,
  "error": "invalid_brand",
  "error_description": "O parâmetro [brand] informado é inválido. As opções válidas são: 'visa', 'mastercard', 'amex', 'diners' ou 'elo'."
}
Ou
{
  "code": 3500053,
  "error": "missing_total",
  "error_description": "O parâmetro [total] é obrigatório e deve ser um inteiro."
}
Ou
{
  "code": 3500006,
  "error": "greater_than_limit",
  "error_description": "O total fornecido é superior ao limite máximo por transação."
}

Back-end

Attention

The payment_token generation procedure in the back-end has been discontinued based on security measures. In order to ensure the protection of data, sensitive information and to avoid refusal of credit card transactions, we recommend that you discontinue use of this service. Based on our evaluation, we would like to suggest generating through the front-end of the application

Creating a Credit Card Transaction in One Step

After obtaining the payment_token through Javascript code or backend, your server will send the information of the items, transaction, and customer, along with the payment_token, to the Efí API.

Hierarchical structure of Schema attributes that can be used:

v1/charge/one-step

"items"
  "name"
  "value"
  "amount"
  "marketplace"
      "payee_code"
      "percentage"
"shippings"
  "name"
  "value"
  "payee_code"
"metadata"
  "custom_id"
  "notification_url"
"payment"
  "credit_card"
      "customer"
          "name"
          "cpf"
          "email"
          "phone_number"
          "birth"
          "address"
              "street"
              "number"
              "neighborhood"
              "zipcode"
              "city"
              "complement"
              "state"
          "juridical_person"
              "corporate_name"
              "cnpj"
      "installments"
      "discount"
          "type"
              "percentage",
              "currency"
          "value"
      "billing_address"
          "street"
          "number"
          "neighborhood"
          "zipcode"
          "city"
          "complement"
          "state"
      "payment_token"
      "message"

POST /v1/charge/one-step

Requires activation of the Billing API in your application.

Request

Input data

{
  "items": [
    {
      "name": "Meu Produto",
      "value": 5990,
      "amount": 1
    }
  ],
  "payment": {
    "credit_card": {
      "customer": {
        "name": "Gorbadoc Oldbuck",
        "cpf": "94271564656",
        "email": "[email protected]",
        "phone_number": "5144916523"
      },
      "installments": 1,
      "payment_token": "",
    }
  }
}

Responses

The responses below represent consumption Success.

🟢 200 (aprovado)
🟢 200 (recusado)

{
  "code": 200, // HTTP return "200" stating that the request was successful
  "data": {
    "installments": 1, // number of installments the payment should be divided into
    "installment_value": 5990, // value of each installment. For example: 8900 (equivalent to R$ 89.00)
    "charge_id": "charge_id_number", // ID number referring to the generated transaction
    "status": "approved", // Indicates that the payment has been approved by the card issuer but has not yet been credited.
    "total": 5990, // value in cents. For example: 8900 (equivalent to R$ 89.00)
    "payment": "credit_card" // payment method associated with this transaction ("credit_card" is equivalent to "cartão de crédito")
  }
}

{
  "code": 200, //HTTP return "200" stating that the request was successful
  "data": {
    "installments": 1, // number of installments the payment should be divided into
    "installment_value": 5990, // value of each installment. For example: 8900 (equivalent to R$ 89.00)
    "charge_id": "numero_charge_id", // ID number referring to the generated transaction
    "status": "unpaid", // Indicates that the payment was rejected.
    "refusal": {
          "reason": "Sistema de segurança: Os dados e comportamentos de utilização do cartão se assemelham a práticas e cenários de alto risco para pagamentos online. Utilize outro cartão ou outro meio de pagamento.", // Message containing the reason for the transaction refusal.
          "retry": true // Indicates whether it is possible to retry the transaction.
      },
    "total": 5990, // value in cents. For example: 8900 (equivalent to R$ 89.00)
    "payment": "credit_card" // payment method associated with this transaction ("credit_card" is equivalent to "cartão de crédito")
  }
}

Creating a Credit Card Transaction in Two Steps

In this option, it is necessary to follow two steps, sending the request body with all the mandatory minimum attributes for issuing the charge.

Create the transaction, providing the item/produto/serviço, valor, quantidade, etc;
Associate with the payment method via boleto, providing the transaction's charge_id and customer data.

The documentation continues with detailed procedures, but remember to install one of our libraries on your server to execute the example codes. Make sure the Efí SDK is installed.

1. Create Transaction

Firstly, we need to generate the transaction (also called "charge"). At this moment, you will provide the name of the item/product/service, the transaction value, quantity, and other relevant information.

Once created, the charge_id will be returned, which is the unique identifier of the transaction and will be used to associate with the payment method.

At the time of creation, the transaction receives the status new, which means that the charge has been generated and is awaiting payment method definition. This charge will only have its status changed when the integrator defines its payment method.

To generate a transaction, you should send a POST request to the route /v1/charge.

Hierarchical structure of Schema attributes that can be used:

v1/charge

"items"  
      "name"  
      "value"  
      "amount"  
      "marketplace"  
          "payee_code"  
          "percentage"  
  "shippings"  
      "name"  
      "value"  
      "payee_code"  
  "metadata"  
      "custom_id"  
      "notification_url"

POST /v1/charge

Requires activation of the Billing API in your application

Request

Input data

{
  "items": [
    {
      "name": "Meu Produto",
      "value": 8900,
      "amount": 1
    }
  ]
}

Responses

The responses below represent consumption Success.

🟢 200

{
  "code": 200, // HTTP return "200" stating that the request was successful
  "data": {
    "charge_id": "charge_id_number", // ID number referring to the generated transaction
    "status": "new", // charge generated, awaiting payment method definition
    "total": 8900, // total transaction amount (in cents, where 8900 = R$89.00)
    "custom_id": null, // optional custom identifier
    "created_at": "2021-06-01 14:58:46" // date and time of transaction creation
  }
}

2. Associate with Payment Method via Card

With the transaction successfully generated, now let's associate it with the desired payment method - in this case, it will be banking_billet (banking billet). To do this, the charge_id obtained when creating the transaction should be provided.

In this step, your backend will send the remaining transaction information, along with the payment_token, to the Efí API.

To associate with the payment method, you should send a POST request to the route /v1/charge/:id/pay, where :id is the charge_id of the desired transaction.

Hierarchical structure of Schema attributes that can be used:

v1/charge/:id/pay

"payment"  
    "credit_card"  
        "customer"  
            "name"  
            "cpf"  
            "email"  
            "phone_number"  
            "birth"  
            "address"  
                "street"  
                "number"  
                "neighborhood"  
                "zipcode"  
                "city"  
                "complement"  
                "state"  
            "juridical_person"  
                "corporate_name"  
                "cnpj"  
        "installments"  
        "discount"  
            "type"  
                "percentage",  
                "currency"  
            "value"  
        "billing_address"  
            "street"  
            "number"  
            "neighborhood"  
            "zipcode"  
            "city"  
            "complement"  
            "state"  
        "payment_token"  
        "message"

POST /v1/charge/:id/pay

Requires activation of the Billing API in your application

Request

Input data

{
  "payment": {
    "credit_card": {
      "customer": {
        "name": "Gorbadoc Oldbuck",
        "cpf": "94271564656",
        "email": "[email protected]",
        "phone_number": "5144916523"
      },
      "installments": 1,
      "payment_token": "",
    }
  }
}

Responses

The responses below represent consumption Success.

🟢 200

{
  "code": 200, // HTTP return "200" stating that the request was successful
  "data": {
    "installments": 1, // number of installments the payment should be divided into
    "installment_value": 8900, // value of each installment. For example: 8900 (equivalent to R$ 89.00)
    "charge_id": "charge_id_number", // ID number referring to the generated transaction
    "status": "waiting", // selected payment method, awaiting payment confirmation ("waiting" is equivalent to "aguardando")
    "total": 8900, // value in cents. For example: 8900 (equivalent to R$ 89.00)
    "payment": "credit_card" // payment method associated with this transaction ("credit_card" is equivalent to "cartão de crédito")
  }
}

Payment made as Juridical person (PJ)

The customer associated with the transaction can be a Juridical person. In this case, it is necessary to inform the Corporate Name and CNPJ of the paying company in the juridical_person attribute.

List of all possible transaction statuses

All transactions have statuses, representing the "situation" of that transaction. Therefore, it is important to know the possible statuses of a transaction in the API to provide the appropriate handling in your system.

Check this link for all details on the possible statuses of transactions.

Callbacks (notifications) of API transactions to your system

Notifications allow you to be informed when a transaction has its status changed. This way, you can identify when a boleto has been paid, for example.

Check this link for all details on how to implement your notification URL.

Rounding of e-commerce card fee

The fee formatting is done with number_format, that is, a simple rounding. Values less than 5 are rounded down, values greater than or equal to 5 are rounded up.

Example:
Fee of 3.342 is rounded down to 3.34 Fee of 3.335 will be rounded up to 3.34

Credit Card Payment Retry

Credit card payments that are declined for operational reasons, such as lack of limit, incorrect data, and temporary issues with the card, may have a new payment attempt via API.

This way, it will not be necessary to repeat the entire process of issuing the charge, making the flow faster and more efficient.

POST /v1/charge/:id/retry

Requires activation of the Billing API in your application

Request

Input data

{
  "payment": {
    "credit_card": {
      "customer": {
        "name": "Gorbadoc Oldbuck",
        "cpf": "94271564656",
        "email": "[email protected]",
        "birth": "1990-08-29",
        "phone_number": "5144916523"
      },
      "billing_address": {
        "street": "Avenida Juscelino Kubitschek",
        "number": "909",
        "neighborhood": "Bauxita",
        "zipcode": "35400000",
        "city": "Ouro Preto",
        "complement": "",
        "state": "MG"
      },
      "payment_token": "75bfce47d230b550f7eaac2a932e0878a934cb3"
    }
  }
}

Responses

The responses below represent consumption Success.

🟢 200

{
  "code": 200, // HTTP return "200" stating that the request was successful
  "data": {
    "installments": 1, // number of installments the payment should be divided into
    "installment_value": 8900, // value of each installment. For example: 8900 (equivalent to R$ 89.00)
    "charge_id": "charge_id_number", // ID number referring to the generated transaction
    "status": "waiting", // selected payment method, awaiting payment confirmation ("waiting" is equivalent to "aguardando")
    "total": 8900, // value in cents. For example: 8900 (equivalent to R$ 89.00)
    "payment": "credit_card" // payment method associated with this transaction ("credit_card" is equivalent to "cartão de crédito")
  }
}

Information

This feature allows the integrator to attempt to reprocess a failed charge. For this, the charge must meet the following criteria:

the charge must be from a credit card

the charge must have the status unpaid

the charge cannot be recurrent

Credit Card Payment Refund

This endpoint allows the refund of a payment made via credit card.

The refund can be total (total) or parcial (partial), depending on the specified amount. If no amount is provided, the refund will be total.

POST /v1/charge/card/:id/refund

Requires activation of the Billing API in your application.

Request

Dados de entrada

{
  "amount": 1000
}

Responses

The response below indicates successful usage.

🟢 200

{
  "status": 200,
  "message": "Reembolso em processamento"
}

Information

This feature allows the integrator to refund a payment. For this, the credit card charge must meet the following criteria:

The charge must have the status paid.

There must not be another refund request for the same charge still in process.

Only one partial refund can be made per day for the same charge.

The charge must be of type credit card.

Partial refunds can be requested up to 90 days after payment confirmation.

Total refunds can be requested up to 360 days after payment confirmation.

Refunds are not available for marketplace sales.

Return Information of Existing Transaction

To retrieve information about a transaction, you should send a GET request to the route /v1/charge/:id, where :id is the charge_id of the desired transaction.

GET /v1/charge/:id

Requires activation of the Billing API in your application

Request

Input data

Input parameter: enter the "charge_id" of the desired transaction

Responses

The responses below represent consumption Success(200).

🟢 200

{
  "code": 200, // HTTP return "200" stating that the request was successful
  "data": {
    "charge_id": 391, // ID number referring to the generated transaction
    "total": 2500, // total transaction amount (in cents, where 2500 = R$25.00)
    "status": "unpaid", // payment of the charge could not be confirmed. 
    "reason": "Número do cartão inválido.", // reason for the card decline
    "custom_id": null, // optional custom identifier
    "created_at": "2022-08-16 11:33:52", // date and time of transaction creation
    "notification_url": null,
    "items": [
      {
        "name": "Product 1", // name of your item, product, or service
        "value": 150, // value in cents. For example: 150 (equivalent to R$ 1.50)
        "amount": 10 // quantity of the item or product
      }
    ],
    "history": [
      {
        "message": "Cobrança criada",
        "created_at": "2022-08-16 11:33:52"
      },
      {
        "message": "Pagamento via cartão de crédito aguardando confirmação",
        "created_at": "2022-08-16 11:33:52"
      },
      {
        "message": "Falha no pagamento - Número do cartão inválido.",
        "created_at": "2022-08-16 11:35:47"
      }
    ],
    "shippings": [
      {
        "name": "Sedex",
        "value": 1000,
        "payee_code": "473f6abd05d8a850a046395ed5544138"
      }
    ],
    "customer": {
      "name": "Gorbadoc Oldbuck",
      "cpf": "65366950031",
      "birth": "1977-01-15",
      "email": "[email protected]",
      "phone_number": "5144916523"
    },
    "payment": {
      "method": "credit_card",
      "created_at": "2022-08-16 11:33:52",
      "message": null,
      "credit_card": {
        "mask": "544969XXXXXX8502",
        "installments": 1,
        "installment_value": 2500,
        "address": {
          "street": "Street 3",
          "number": "10",
          "complement": null,
          "neighborhood": "Bauxita",
          "city": "Ouro Preto",
          "state": "MG",
          "zipcode": "35400000"
        }
      }
    }
  }
}

Return List of Charges

To retrieve information on charges issued in an application, send a GET request to the /v1/charges route.

This endpoint includes various filters to refine your search, such as CPF/CNPJ and status. Among all available filters, the charge_type, begin_date and end_date filters are mandatory and specify the type of transaction and the date range for the charges you wish to retrieve.

Important!

This feature is currently in beta. We are excited to provide you with this tool, but please note that it is still under active development and changes may apply during this period.

Your feedback is incredibly valuable to us during this phase. We invite you to share your experiences and suggestions to help us improve. Feel free to reach out through our Discord community or other support channels.

GET /v1/charges

Requires the scope API de Emissão de cobranças in your Efi Bank application

Request

Input data

Query params:  
  "charge_type"
  "customer_document"
  "status"
  "custom_id"
  "value"
  "date_of"
  "begin_date"
  "end_date"
  "limit"
  "page"
  "offset"

Responses

The responses below represent consumption Success.

🟢 200

{
"code": 200,
"data": [
    {
        "id": 705400488,
        "total": 5990,
        "status": "unpaid",
        "custom_id": null,
        "created_at": "2024-04-16T22:28:10.000Z",
        "customer": {
            "name": "Gorbadoc Oldbuck",
            "phone_number": "5144916523",
            "cpf": "65366950031"
        },
        "payment": {
            "payment_method": "credit_card",
            "paid_at": null,
            "credit_card": {
                "mask": "538393XXXXXX3270",
                "installments": 1,
                "installment_value": 5990,
                "interest": 0,
                "address": {
                    "street": "Avenida Juscelino Kubitschek",
                    "number": "909",
                    "complement": null,
                    "neighborhood": "Bauxita",
                    "city": "Ouro Preto",
                    "state": "MG",
                    "zipcode": "35400000"
                }
            }
        }
    },
    {
        "id": 700261793,
        "total": 8900,
        "status": "unpaid",
        "custom_id": null,
        "created_at": "2024-04-04T22:29:15.000Z",
        "customer": {
            "name": "Gorbadoc Oldbuck",
            "phone_number": "5144916523",
            "cpf": "65366950031"
        },
        "payment": {
            "payment_method": "credit_card",
            "paid_at": null,
            "credit_card": {
                "mask": "538393XXXXXX3270",
                "installments": 1,
                "installment_value": 8900,
                "interest": 0,
                "address": {
                    "street": "Av. JK",
                    "number": "909",
                    "complement": null,
                    "neighborhood": "Bauxita",
                    "city": "Ouro Preto",
                    "state": "MG",
                    "zipcode": "35400000"
                }
            }
        }
    }
],
"params": {
    "begin_date": "2024-03-06T00:00:00.000Z",
    "end_date": "2024-05-01T00:00:00.000Z",
    "pagination": {
        "limit": 2,
        "offset": 0,
        "page": 1
    }
}
}

Usage Limit

As with all endpoints in our API, the charge listing endpoint is subject to a daily usage limit. You can find detailed information about these limits on this page.

If your queries exceed these limits, we recommend submitting a support ticket to request an increase for your account.

Include "notification_url" and "custom_id" in an existing transaction

You can define or modify the information sent in the transaction's metadata property at any time. This endpoint is of extreme importance to update the notification URL linked to transactions or modify the previously associated custom_id.

To change the notification_url and/or custom_id of a transaction, you should send a PUT request to the route /v1/charge/:id/metadata, where :id is the charge_id of the desired transaction.

Use cases of this endpoint:

The integrator changed the server IP associated with the notification URL of the transactions;
The integrator updated the notification URL for new transactions that are created (`createCharge`), but also needs to update previous transactions (`updateChargeMetadata`) that were generated and are associated with the incorrect/outdated URL;
SSL (https) was installed on the client's server and even if the client sets up a 301 or 302 redirection rule, it will be necessary to define the new URL in transactions using the "old" URL;
The integrator generated charges without informing the notification URL when sending the transaction creation request;
Modify or add information to the `custom_id` attribute associated with previously generated transactions;
Among other possible scenarios.

PUT /v1/charge/:id/metadata

Requires activation of the Billing API in your application

Request

Input data

{
  "notification_url": 'http://your_domain.com/notification',
  "custom_id": 'REF0001'
}

Responses

The responses below represent consumption Success(200).

🟢 200

{
  "code": 200 // HTTP return "200" stating that the request was successful
}

Cancel an Existing Transaction

A transaction can only be canceled if it has the status new, waiting, unpaid, or link.

When a transaction is canceled, there is only one condition for the status to be changed again: if the customer prints the boleto before the integrator cancels the transaction, they can make the payment normally at a bank branch. In this case, both the integrator and the payer receive payment confirmation, and the status of the charge changes from canceled to paid.

To cancel a transaction, such as a boleto, you should send a PUT request to the route /v1/charge/:id/cancel, where :id is the charge_id of the transaction you want to cancel.

PUT /v1/charge:id/cancel

Requires activation of the Billing API in your application

Request

Input data

Input parameter: enter the "charge_id" of the desired transaction

Responses

The responses below represent consumption Success(200).

🟢 200

{
  "code": 200 // HTTP return "200" stating that the request was successful
}

Add Description to Transaction History

The history of a transaction shows all the actions that have occurred so far, but custom messages do not affect the transaction itself, they only appear in the history.

This can be viewed both in the transaction details through the interface and using the transaction details endpoint.

You can view the transaction history both in the transaction details interface and using the transaction details endpoint.

You can view the transaction history in the interface or using the transaction details endpoint. To do this, simply send the charge_id identifier and the message you want to add to the transaction history. The description should be between 1 and 255 characters.

POST /v1/charge/:id/history

Requires activation of the Billing API in your application

Request

Input data

{
  "description": "Camisa Polo tamanho G cor azul, cobrança Bolix, pix com boleto."
}

Responses

The responses below represent consumption Success.

🟢 200

{
  "code": 200 // HTTP return "200" stating that the request was successful
}

List Installments According to Credit Card Brand

The installments endpoint is used to list the installments for each credit card brand, already with interest rates and number of installments calculated according to the integrator's account. That means if your account has an interest rate configuration for credit cards (option available for clients who have opted to receive payments in installments), you don't need to make any additional calculations, as this endpoint already provides the calculated values automatically.

Available Brands: visa, mastercard, amex and elo.

GET /v1/installments

Requires activation of the Billing API in your application

Request

Input data

Input_parameter: Provide the "brand" (card brand) and the "total" (total purchase amount) desired

Responses

The response below represent consumption Success(200).

🟢 200

{
  "code": 200, // HTTP return "200" stating that the request was successful
  "data": {
    "rate": 0,
    "name": "visa", // card brand provided
    "installments": [
      {
        "installment": 1,
        "has_interest": false,
        "value": 1000, // value of the first installment
        "currency": "10,00",
        "interest_percentage": 0
      },
      {
        "installment": 2,
        "has_interest": true,
        "value": 515, // value of the second installment
        "currency": "5,15",
        "interest_percentage": 199
      }
    ]
  }
}

Card

Introduction​

Check out the list of credit cards accepted by Efí​

Obtaining the payment_token​

JavaScript Library​

Demonstration​

Installation​

a) Web Application​

b) Package Manager (NPM or Yarn)​

Universal Module Definition (UMD)​

ECMAScript Modules (ESM)​

CommonJS (CJS)​

Framework React Native and others (WebView)​

TypeScript Definitions​

Usage​

a) Check script blocking​

b) Identify the card brands​

c) Search for installment information​

d) Generate the payment_token and card_mask​

e) Enable debugger​

Practical Examples​

jQuery module​

Obtaining a "payment_token" (getPaymentToken) and information about installments (getInstallments)​

Attributes related to sending card data and returning functions​

Back-end​

Creating a Credit Card Transaction in One Step​

Creating a Credit Card Transaction in Two Steps​

1. Create Transaction​

2. Associate with Payment Method via Card​

Credit Card Payment Retry​

Credit Card Payment Refund​

Return Information of Existing Transaction​

Return List of Charges​

Include "notification_url" and "custom_id" in an existing transaction​

Cancel an Existing Transaction​

Add Description to Transaction History​

List Installments According to Credit Card Brand​

Introduction

Check out the list of credit cards accepted by Efí

Obtaining the payment_token

JavaScript Library

Demonstration

Installation

a) Web Application

b) Package Manager (NPM or Yarn)

Universal Module Definition (UMD)

ECMAScript Modules (ESM)

CommonJS (CJS)

Framework React Native and others (WebView)

TypeScript Definitions

Usage

a) Check script blocking

b) Identify the card brands

c) Search for installment information

d) Generate the payment_token and card_mask

e) Enable debugger

Practical Examples

jQuery module

Obtaining a "payment_token" (getPaymentToken) and information about installments (getInstallments)

Attributes related to sending card data and returning functions

Back-end

Creating a Credit Card Transaction in One Step

Creating a Credit Card Transaction in Two Steps

1. Create Transaction

2. Associate with Payment Method via Card

Credit Card Payment Retry

Credit Card Payment Refund

Return Information of Existing Transaction

Return List of Charges

Include "notification_url" and "custom_id" in an existing transaction

Cancel an Existing Transaction

Add Description to Transaction History

List Installments According to Credit Card Brand