Skip to main content

Payment Link

Step by step to generate a payment link in the Efí API


Introduction​

This feature allows you to create a link to an Efí payment screen.

Previously, the integrator had to create their own payment screen and use the endpoints for creating a charge and setting the payment method, which we call "Transparent Checkout". This means that the payer did not need to leave the integrator's system to make the payment, and all communication with Efí was done transparently.

In response to requests, we have created the possibility of generating a link to the Efí payment screen. For those who need a more practical integration tool, this endpoint allows the integrator to choose the payment methods they wish to allow (billet, credit card and/or pix) and generate a link to the Efí payment screen. This way, they redirect the payer to the generated link and do not need to worry about implementing their own screen.

Considering that the payer needs to feel secure when making a purchase, our payment screen allows for specific configurations so that your customer feels comfortable completing the transaction, even when redirected to a different domain than before.


To create a payment link in One Step, simply send a POST request to the route /v1/charge/one-step/link. In response, you will receive the payment_url of the transaction.

When consuming the endpoint /charge/one-step/link, the charge will be assigned the status link. The integrator only needs to redirect the payer to the link returned in the payment_url tag, and everything else will be handled on the Efí payment screen.

Hierarchical structure of Schema attributes that can be used:
 "items"  
      "name"  
      "value"  
      "amount"  
      "marketplace"  
          "payee_code"  
          "percentage"  
  "shippings"  
      "name"  
      "value"  
      "payee_code"  
  "metadata"  
      "custom_id"  
      "notification_url"  
  "customer"
      "email"
  "settings"  
      "billet_discount"  
      "card_discount"  
      "conditional_discount"  
          "type"  
              "percentage",  
              "currency"  
          "value"  
          "until_date"  
      "message"  
      "expire_at"  
      "request_delivery_address"  
      "payment_method"  
          "banking_billet"  
          "credit_card"  
          "all"
POST /v1/charge/one-step/link

Requires activation of the Billing API in your application


Request

{
  "items": [
    {
      "amount": 5,
      "name": "Game of Thrones",
      "value": 827
    },
    {
      "amount": 5,
      "name": "Dexter",
      "value": 620
    },
    {
      "amount": 2,
      "name": "Breaking Bad",
      "value": 750
    }
  ],
  "metadata": {
      "custom_id": "produto 1",
      "notification_url": "sua_url_notificação"
  },
  "customer": {
          "email": "[email protected]"
      },
  "shippings": [
    {
      "name": "Ouro Preto",
      "value": 500
    }
  ],
  "settings": {
    "billet_discount": 500,
    "card_discount": 300,
    "message": "Escreva aqui, se quiser, uma mensagem ao seu cliente, limite de 80 caracteres",
    "conditional_discount":{
      "type": "percentage", 
      "value": 100, 
      "until_date": "2021-12-30"
    },
    "payment_method": "all",
    "expire_at": "2025-02-08",
    "request_delivery_address": true
  }
}

Responses

The responses below represent consumption Success.

{
  "code": 200,
  "data": {
    "charge_id": 3714507,
    "status": "link",
    "total": 8863,
    "custom_id": "cross-media soft",
    "payment_url": "https://pagamento.gerencianet.com.br/:identificador",
    "payment_method": "all",
    "billet_discount": 500,
    "card_discount": 300,
    "conditional_discount_value": 100,
    "conditional_discount_type": "percentage",
    "conditional_discount_date": "2021-12-30",
    "request_delivery_address": true,
    "message": "teste",
    "expire_at": "2025-02-08",
    "created_at": "2021-11-09 11:14:36"
  }
}

Firstly, you need to create the transaction, providing details of the item/produto/serviço, value, and quantity. Then, this transaction must be associated with a payment link.

1. Create the transaction​

Firstly, we need to generate the transaction (also called "charge"). This is when you provide the item/produto/serviço name, transaction value, quantity, among other possible information.

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

As soon as this transaction is created, it receives the status new, which means that the charge has been generated and is awaiting payment method selection. 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:
 "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

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

Responses

The responses below represent consumption Success.

{
  "code": 200, // HTTP return "200" stating that the request was successful
  "data": {
    "charge_id": numero_charge_id, // Identification number of the generated transaction
    "status": "new", // Charge generated, awaiting payment method definition
    "total": 8900, // Total value of the transaction (in cents, where 8900 = $89.00)
    "custom_id": null, // Optional custom identifier
    "created_at": "2021-06-01 14:58:46" // Date and time of transaction creation
  }
}

Now that the transaction has been created and you already have the charge_id, you need to associate it to obtain the payment link.

Simply send a POST request to the route /v1/charge/:id/link to generate a payment link.

Hierarchical structure of Schema attributes that can be used:

  "billet_discount"  
  "card_discount"  
  "conditional_discount"  
      "type"  
          "percentage",  
          "currency"  
      "value"  
      "until_date"  
  "message"  
  "expire_at"  
  "request_delivery_address"  
  "payment_method"  
      "banking_billet"  
      "credit_card"  
      "all"
POST /v1/charge/:id/link
Important!

To create a "payment link" (chargeLink), a previously created "transaction" (createCharge) must be provided.

Therefore, if there is an attempt to make a payment and, for some reason, the payment confirmation is not successful (e.g., declined card, customer wants to pay by another method, etc.), a new transaction must be generated and associated with a new payment link, as the previous transaction will have a status of waiting or unpaid, which means that due to the payment attempt, it has already been associated with a payment method.


Requires activation of the Billing API in your application


Request

{
  "message": "Escreva aqui, se quiser, uma mensagem ao seu cliente, limite de 80 caracteres",
  "payment_method": "all",
  "expire_at": "2012-12-20",
  "request_delivery_address": false,
  "billet_discount": 5000,
  "card_discount": 3000
}

Responses

The responses below represent consumption Success.

{
  "code": 200,
  "data": {
    "charge_id": 148003,
    "status": "link",
    "total": 5990,
    "custom_id": null,
    "payment_url": "https://pagamento.gerencianet.com.br/:identificador",
    "payment_method": "all",
    "created_at": "2016-12-14 11:31:37"
  }
}

To retrieve information from a link, you should send a GET request to the route /v1/charge/:id.

GET /v1/charge/:id
Requires activation of the Billing API in your application


Request

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

Responses

The responses below represent consumption Success(200).

{
  "code": 200, // HTTP return "200" stating that the request was successful
  "data": {
    "charge_id": 1234567, // transaction ID number
    "total": 8900, // total transaction amount (in cents, where 8900 = R$89.00)
    "status": "waiting", // selected payment method, awaiting payment confirmation (the term "waiting" is equivalent to "aguardando")
    "custom_id": null, // optional custom identifier
    "created_at": "2022-10-31 10:18:21", // date and time of transaction creation
    "notification_url": null,
    "items": [
      {
        "name": "My Product", // name of your item, product, or service
        "value": 8900, // value, in cents. For example: 8900 (equals R$ 89.00)
        "amount": 1 // quantity of the item or product
      }
    ],
    "history": [
      {
        "message": "Cobrança criada",
        "created_at": "2222-10-31 10:18:21"
      },
      {
        "message": "Pagamento via boleto aguardando confirmação",
        "created_at": "2022-10-31 10:19:05"
      }      
    ],
    "customer": {
      "name": "Gorbadoc Oldbuck",
      "cpf": "94271564656",
      "email": "[email protected]",
      "phone_number": "5144916523",
      "address": {
        "street": "Avenida Juscelino Kubitschek",
        "number": "909",
        "complement": null,
        "neighborhood": "Bauxita",
        "city": "Ouro Preto",
        "state": "MG",
        "zipcode": "35400000"
      }
    },
    "payment": {
      "method": "banking_billet", // payment method for the charge (banking_billet equals banking billet)
      "created_at": "2022-10-31 10:19:05",
      "message": "Using the message attribute, this content is displayed in the OBSERVATION field of the charge issued via API and also in the SELLER'S OBSERVATION field in the billing emails sent to the customer. Up to 4 lines of content can be used, with a maximum of 100 characters per line. This message can be seen in emails related to the charge, on the billet or booklet",
      "banking_billet": {
        "barcode": "00000.00000 00000.000000 00000.000000 0 00000000000000",
        "pix": {
          "qrcode": "00020101021226990014BR.GOV.BCB.PIX2577qrcodes-pix.gerencianet.com.br/bolix/v2/cobv/0000000000000000000000000000GERENCIANET SA6010OURO PRETO62070503***63047CB1", // BRCode or copy and paste
          "qrcode_image": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmc vMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0NSA0NSIgc2hhcGUtcmVuZGVyaW5nPSJjcmlzcEVkZ2VzIj48cGF0aCBmaWxsPSIjZmZmZmZmIiBkPSJNMCAwaDQ1djQ1SD..." // QR Code image
        },
        "link": "https_link_to_access_the_billet", // Bolix generated link
        "pdf": {
          "charge": "https_pdf_link_of_the_invoice" // Bolix PDF link
        },
        "expire_at": "2023-12-30", // due date of the charge in the following format: 2022-12-30 (i.e., equals 30/12/2022)
        "configurations": {
          "interest": 33, // interest charged per day after the due date (in this case, 33 equals 0.033%)
          "fine": 200 // fine charged after the due date (in this case, 200 equals 2%)
        }
      }
    }
  }
}

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

You can define or modify the information sent in the metadata property of the transaction at any time. This endpoint is of extreme importance for updating the notification URL linked to transactions or modifying 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.

Use cases for this endpoint:
  1. The integrator changed the server IP associated with the notification URL of transactions;
  2. The integrator updated the notification URL for new transactions created (createCharge), but also needs to update previous transactions (updateChargeMetadata) that are associated with the incorrect or outdated URL;
  3. 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 set the new URL in transactions that are using the "old" URL;
  4. The integrator generated charges without informing the notification URL when sending the transaction creation request;
  5. Modify or add information to the custom_id attribute associated with previously generated transactions; and other possible scenarios.
PUT /v1/charge/:id/metadata
Requires activation of the Billing API in your application


Request

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

Responses

The responses below represent consumption Success(200).

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

Allows updating (changing) certain parameters and attributes of a payment link created through PUT /v1/charge/:id/link, as long as the payment confirmation has not occurred.

Some information that can be updated/changed in a payment link:

  • Allowed payment method;
  • Discounts for boleto and credit card;
  • Inclusion of discounts (including conditional ones);
  • Informative message to the customer;
  • Payment link expiration date;
  • Request (or not) for the buyer's shipping address.
PUT /v1/charge/:id/link
Requires activation of the Billing API in your application


Request

{
  "billet_discount": 500,
  "card_discount" : 200,
  "expire_at": "2024-12-15"
}

Responses

The responses below represent consumption Success(200).

{
  "code": 200,
  "data": {
    "charge_id": 3714507,
    "status": "link",
    "total": 8863,
    "payment_url": "https://pagamento.gerencianet.com.br/:identificador",
    "payment_method": "all",
    "billet_discount": 500,
    "card_discount": 200,
    "conditional_discount_value": 100,
    "conditional_discount_type": "percentage",
    "conditional_discount_date": "2021-12-30",
    "request_delivery_address": true,
    "message": "teste",
    "expire_at": "2024-12-15",
    "created_at": "2021-11-09 11:14:36"
  }
}

When a transaction is cancelled, 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 will receive the payment confirmation as usual, and the status of the charge will change from canceled to paid.

To cancel a transaction (e.g., cancel a boleto), you should send a PUT request to the route /v1/charge/:id/cancel.

PUT /v1/charge/:id/cancel
Requires activation of the Billing API in your application


Request

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

Responses

The responses below represent consumption Success(200).

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

Adding a description to the transaction history​

The transaction history represents all actions that have occurred with this transaction up to the present moment. Custom messages do not influence the transaction itself, only its history.

You can view the history both on the transaction details page in the interface and by using the specific endpoint to get the transaction details.

To add a custom message to the transaction history, you need to send the charge_id (unique identifier of the transaction) and the message you want to add. The message must have at least one character and a maximum of 255 characters.

To do this, simply send a POST request to the route /v1/charge/:id/history.

POST /v1/charge/:id/history
Requires activation of the Billing API in your application


Request

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

Responses

The responses below represent consumption Success.

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

A transaction that has a link and whose status is Payment Link, can have its link resent via email.

To do this, you just need to provide the charge_id (unique identifier of the transaction) and the valid email address to which you want to send the payment screen link.

To resend a payment link via email, you should send a POST request to the route /v1/charge/:id/link/resend.

POST /v1/charge/:id/link/resend
Requires activation of the Billing API in your application


Request

{
  "email": "[email protected]"
}

Responses

The responses below represent consumption Success.

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