Passo a passo para gerar um Link de Pagamento na API Efí
Introdução
Este recurso permite criar um link para uma tela de pagamento da Efí.
Anteriormente, a pessoa integradora precisava criar sua própria tela de pagamento e usar os endpoints de criação de cobrança e definição de forma de pagamento, o que chamamos de "Checkout Transparente". Isso significa que o pagador não precisava sair do sistema do integrador para efetuar o pagamento da cobrança, e toda a comunicação com a Efí era realizada de forma transparente.
Atendendo a pedidos, criamos a possibilidade de gerar um link para a tela de pagamento da Efí.
Para quem precisa de uma ferramenta de integração mais prática, este endpoint possibilita que a pessoa integradora escolha as formas de pagamento que deseja permitir (boleto bancário, cartão de crédito e/ou pix) e gere um link para a tela de pagamento da Efí. Desta forma, ela redireciona o pagador para o link gerado e não precisa se preocupar com a implementação de uma tela própria.
Tendo em vista que o pagador precisa se sentir seguro ao efetuar uma compra, nossa tela de pagamento permite configurações específicas para que seu cliente se sinta confortável em realizar a transação, mesmo sendo redirecionado para um domínio diferente do que estava anteriormente.
Criando o link de pagamento em One Step
Para criar um link de pagamento em One Step, basta enviar uma requisição POST
para a rota /v1/charge/one-step/link
, Em resposta, você receberá o o payment_url
da transação.
Ao consumir o endpoint /charge/one-step/link
, a cobrança ganha o status link
.
A pessoa integradora só precisa redirecionar o pagador para o link retornado na tag payment_url
e todo o resto será realizado na tela de pagamento da Efí.
Estrutura hierárquica dos atributos do Schema que podem ser utilizados:
"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
Requer ativação da API de Emissão de cobranças
em sua aplicação
Requisição
- Link de pagamento
- Link de pagamento com Split
{
"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
}
}
{
"items": [
{
"amount": 5,
"name": "Game of Thrones",
"value": 827,
"marketplace": {
"repasses": [
{
"payee_code": "payee_code1",
"percentage": 2500
}
]
}
}
],
"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
}
}
Respostas A resposta abaixo representa Sucesso do consumo.
{
"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"
}
}
Criando o link de pagamento em Two Steps
Primeiramente, você precisa criar a transação, informando os detalhes do item/produto/serviço, valor e quantidade. Em seguida, essa transação deve ser associada a um link de pagamento.
1. Crie a transação
Primeiramente, precisamos gerar a transação (também chamada de "cobrança"). É neste momento que será informado o nome do item/produto/serviço, valor da transação, quantidade, dentre outras informações possíveis.
Após criá-la, será retornado o charge_id
, que é o identificador único da transação e que será utilizado para associar à forma de pagamento.
Assim que essa transação é criada, ela recebe o status new
, que significa que a cobrança foi gerada e está aguardando definição da forma de pagamento. Essa cobrança somente terá seu status alterado quando o integrador definir sua forma de pagamento.
Para gerar uma transação, você deve enviar uma requisição POST
para a rota /v1/charge
.
Estrutura hierárquica dos atributos do Schema que podem ser utilizados:
"items"
"name"
"value"
"amount"
"marketplace"
"payee_code"
"percentage"
"shippings"
"name"
"value"
"payee_code"
"metadata"
"custom_id"
"notification_url"
POST /v1/charge
Requer ativação da API de Emissão de cobranças
em sua aplicação
Requisição
{
"items": [
{
"name": "Meu Produto",
"value": 8900,
"amount": 1
}
]
}
Respostas As respostas abaixo representam Sucesso do consumo.
{
"code": 200,
"data": {
"charge_id": numero_charge_id,
"status": "new",
"total": 8900,
"custom_id": null,
"created_at": "2021-06-01 14:58:46"
}
}
2. Crie um link de pagamento
Agora que a transação já foi criada e você já possui o charge_id
, é preciso associá-lo para obter o link de pagamento.
Basta enviar uma requisição POST
para a rota /v1/charge/:id/link
para gerar um link de pagamento.
Estrutura hierárquica dos atributos do Schema que podem ser utilizados:
"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
Importante!Para se criar um "link de pagamento" (chargeLink
), uma "transação" (createCharge
) previamente criada deverá ser informada.
Logo, se houver uma tentativa de pagamento e, por alguma razão, não houver sucesso na confirmação do pagamento (ex: cartão recusado, cliente deseja pagar por outra forma, etc), uma nova transação deverá ser gerada e associada a um novo link de pagamento, pois a transação anterior estará com status de waiting
ou unpaid
, o que significa que devido a tentativa de pagamento, ela já foi atrelada a um método de pagamento.
Requer ativação da API de Emissão de cobranças
em sua aplicação
Requisição
{
"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
}
Respostas A resposta abaixo representa Sucesso do consumo.
{
"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"
}
}
Para retornar informações de um link, você deve enviar uma requisição GET
para a rota /v1/charge/:id
.
GET /v1/charge/:id
Requer ativação da API de Emissão de cobranças
em sua aplicação
Requisição
Parâmetro de entrada: informe a "charge_id" da transação desejada
Respostas As respostas abaixo representam Sucesso(200) do consumo.
- 🟢 200 (Bolix)
- 🟢 200 (Boleto tradicional)
{
"code": 200,
"data": {
"charge_id": 1234567,
"total": 8900,
"status": "waiting",
"custom_id": null,
"created_at": "2022-10-31 10:18:21",
"notification_url": null,
"items": [
{
"name": "Meu Produto",
"value": 8900,
"amount": 1
}
],
"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",
"created_at": "2022-10-31 10:19:05",
"message": "Usando o atributo message, este conteúdo é exibido no campo OBSERVAÇÃO da cobrança emitida via API
e também no campo OBSERVAÇÃO DO VENDEDOR nos e-mails de cobrança enviados ao cliente
É possível utilizar até 4 linhas de conteúdo, com no máximo 100 caracteres por linha
Essa mensagem poderá ser vista nos e-mails relacionados à cobrança, no boleto ou carnê",
"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",
"qrcode_image": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmc vMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0NSA0NSIgc2hhcGUtcmVuZGVyaW5nPSJjcmlzcEVkZ2VzIj48cGF0aCBmaWxsPSIjZmZmZmZmIiBkPSJNMCAwaDQ1djQ1SD..."
},
"link": "link_https_para_acesso_ao_boleto",
"pdf": {
"charge": "link_https_do_pdf_da_cobranca"
},
"expire_at": "2023-12-30",
"configurations": {
"interest": 33,
"fine": 200
}
}
}
}
{
"code": 200,
"data": {
"charge_id": 1234567,
"total": 8900,
"status": "waiting",
"custom_id": null,
"created_at": "2022-10-31 10:18:21",
"notification_url": null,
"items": [
{
"name": "Meu Produto",
"value": 8900,
"amount": 1
}
],
"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",
"created_at": "2022-10-31 10:19:05",
"message": "Usando o atributo message, este conteúdo é exibido no campo OBSERVAÇÃO da cobrança emitida via API
e também no campo OBSERVAÇÃO DO VENDEDOR nos e-mails de cobrança enviados ao cliente
É possível utilizar até 4 linhas de conteúdo, com no máximo 100 caracteres por linha
Essa mensagem poderá ser vista nos e-mails relacionados à cobrança, no boleto ou carnê",
"banking_billet": {
"barcode": "00000.00000 00000.000000 00000.000000 0 00000000000000",
"link": "link_https_para_acesso_ao_boleto",
"pdf": {
"charge": "link_https_do_pdf_da_cobranca"
},
"expire_at": "2023-12-30",
"configurations": {
"interest": 33,
"fine": 200
}
}
}
}
}
Incluir "notification_url" e "custom_id" em uma transação existente
Você pode definir ou modificar as informações enviadas na propriedade metadata
da transação a qualquer momento. Este endpoint é de extrema importância para atualizar a URL de notificação vinculada às transações ou modificar o custom_id associado anteriormente.
Para alterar a notification_url
e/ou custom_id
de uma transação, você deve enviar uma requisição PUT
para a rota /v1/charge/:id/metadata
.
Casos de uso deste endpoint:- A pessoa integradora alterou o IP do servidor que estava associado à URL de notificação das transações;
- A pessoa integradora atualizou a URL de notificação para as novas transações criadas (
createCharge
), mas precisa atualizar também as transações anteriores (updateChargeMetadata
) e que estão associadas com a URL incorreta ou desatualizada; - Foi instalado SSL (https) no servidor do cliente e, mesmo que o cliente defina uma regra de redirecionamento 301 ou 302, será necessário definir a nova URL nas transações que estão usando a URL "antiga";
- A pessoa integradora gerou cobranças sem informar a URL de notificação ao enviar a requisição de criação da transação;
- Modificar ou acrescentar uma informação junto ao atributo
custom_id
associado às transações geradas previamente; e outros cenários possíveis.
PUT /v1/charge/:id/metadata
Requer ativação da API de Emissão de cobranças
em sua aplicação
Requisição
{
"notification_url": 'http:
"custom_id": 'REF0001'
}
Respostas As respostas abaixo representam Sucesso(200) do consumo.
Alterar determinados parâmetros/atributos de um link de pagamento existente
Permite atualizar (alterar) determinados parâmetros e atributos de um link de pagamento criado através do PUT /v1/charge/:id/link
, desde que não tenha ocorrido a confirmação do pagamento.
Algumas informações que são passíveis de serem atualizadas/alteradas em um link de pagamento:
- Forma de pagamento permitida;
- Descontos de boleto e cartão;
- Inserção de descontos (inclusive condicionais);
- Mensagem informativa ao cliente;
- Data de vencimento do link de pagamento;
- Solicitação (ou não) do endereço de entrega do comprador.
PUT /v1/charge/:id/link
Requer ativação da API de Emissão de cobranças
em sua aplicação
Requisição
{
"billet_discount": 500,
"card_discount" : 200,
"expire-at": "2024-12-15"
}
Respostas As respostas abaixo representam Sucesso(200) do consumo.
{
"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"
}
}
Cancelar um link de pagamento existente
Quando uma transação é cancelada, há apenas uma condição para que o status seja alterado novamente: se o cliente imprimir o boleto antes do integrador cancelar a transação, ele poderá efetuar o pagamento normalmente em uma agência bancária. Nesse caso, tanto a pessoa integradora quanto a pessoa pagadora receberão a confirmação do pagamento como de costume, e o status da cobrança será alterado de canceled
para paid
.
Para cancelar uma transação (por exemplo, cancelar um boleto), você deve enviar uma requisição PUT
para a rota /v1/charge/:id/cancel
.
PUT /v1/charge/:id/cancel
Requer ativação da API de Emissão de cobranças
em sua aplicação
Requisição
Parâmetro de entrada: informe a "charge_id" da transação desejada
Respostas As respostas abaixo representam Sucesso(200) do consumo.
Acrescentar descrição ao histórico de uma transação
O histórico de uma transação representa todas as ações que ocorreram com esta transação até o presente momento. As mensagens personalizadas não influenciam na transação em si, apenas em seu histórico.
Você pode visualizar o histórico tanto na página de detalhes da transação na interface quanto utilizando o endpoint específico para obter os detalhes da transação.
Para adicionar uma mensagem personalizada ao histórico da transação, você precisa enviar o charge_id
(identificador único da transação) e a mensagem que deseja adicionar. A mensagem deve ter no mínimo um caractere e no máximo 255 caracteres.
Para fazer isso, basta enviar uma requisição POST
para a rota /v1/charge/:id/history
.
POST /v1/charge/:id/history
Requer ativação da API de Emissão de cobranças
em sua aplicação
Requisição
{
"description": "Camisa Polo tamanho G cor azul, cobrança Bolix, pix com boleto."
}
Respostas As respostas abaixo representam Sucesso do consumo.
Reenviar link de pagamento por e-mail
Uma transação que possui link
e cujo status é Link de pagamento
, pode ter o seu link reenviado por e-mail.
Para fazer isso, você só precisa fornecer o charge_id
(identificador único da transação) e o endereço de e-mail válido para o qual deseja enviar o link da tela de pagamento.
Para reenviar um link de pagamento por e-mail, você deve enviar uma requisição POST
para a rota /v1/charge/:id/link/resend
.
POST /v1/charge/:id/link/resend
Requer ativação da API de Emissão de cobranças
em sua aplicação
Requisição
Respostas As respostas abaixo representam Sucesso do consumo.