Cartão

Passo a passo para gerar uma cobrança de cartão de crédito na API Efí

Introdução

As transações online via cartão de crédito exigem apenas a numeração de face e o código no verso do cartão, o que pode resultar em transações suspeitas. Por isso, é importante adotar procedimentos de segurança para evitar prejuízos financeiros, como o Chargeback.

Quando uma transação com cartão de crédito é realizada, ela passa por três etapas: autorização da operadora, análise de segurança e captura. Cada transação é analisada para identificar possíveis riscos. Se for aprovada, o valor é debitado na fatura do cliente. Caso contrário, o valor fica reservado até que a comunicação reversa seja concluída e o limite do cartão seja reestabelecido.

Confira a lista de cartões de crédito aceitos pela Efí

• Visa
• Master
• AmericanExpress
• Elo
• Hipercard

Atenção!

Para fazer o pagamento com cartão de crédito,é necessário obter o payment_token da transação. Portanto, é imprescindível seguir os procedimentos para obter o payment_token conforme descrito no documento antes de criar a cobrança com cartão de crédito.

Outra informação importante é você precisa cadastrar o ramo de atividade em sua conta. Confira mais detalhes aqui.

Obtenção do payment_token

Um payment_token é um conjunto de caracteres gerado pela API Efí, que representa os dados do cartão da pessoa pagadora. Ele pode ser configurado para uso único ou reutilização recorrente.

Para transações com cartão de crédito, é realizada uma etapa prévia à criação da cobrança, onde ocorre a geração do payment_token. Isso pode ser feito transmitindo os dados do cartão, podendo utilizar a biblioteca JavaScript, ou o módulo jQuery.

Tokenização de cartão

Se você precisa reutilizar o payment_token para fins de recorrência, utilize o atributo reuse com o valor booleano true. Dessa forma, o payment_token pode ser usado em mais de uma transação de forma segura, sem a necessidade de salvar os dados do cartão

Simulação em Ambiente de Homologação

A simulação de cobranças de cartão em ambiente de Homologação funciona com base na análise imediata de acordo com o último dígito do número do cartão de crédito utilizado:

Cartão com final 1 retorna: "reason":"Dados do cartão inválidos."

Cartão com final 2 retorna: "reason":"Transação não autorizada por motivos de segurança."

Cartão com final 3 retorna: "reason":"Transação não autorizada, tente novamente mais tarde."

Demais finais têm transação aprovada.

Biblioteca JavaScript

Esta biblioteca JavaScript permite a criptografia dos dados do cartão diretamente no navegador do cliente, gerando o payment_token, identificando a bandeira do cartão e obtendo informações de parcelamento.

Demonstração

Para visualizar como essa biblioteca é utilizada em um exemplo prático, você pode conferir uma demonstração aqui.

Veja mais detalhes no repositório da biblioteca no GitHub.

Instalação

Abaixo, fornecemos algumas opções de instalação da biblioteca para atender a projetos web que utilizam JavaScript puro ou frameworks modernos. Veja os detalhes a seguir:

a) Aplicação Web(Browser)

Disponibilizamos duas formas de instalação da biblioteca em aplicações Web.

• Importação por CDN

Importação através do link do CDN da biblioteca.

script

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

• Importação local

Realizando o download da biblioteca localizada em /dist/payment-token-efi.min.js, adicione-a localmente em seu projeto.

script

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

b) Gerenciador de pacote (NPM ou Yarn)

Se você estiver utilizando um gerenciador de pacotes como npm ou yarn, instale a biblioteca diretamente:

shell

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

Após a instalação, você pode importar a biblioteca conforme o ambiente que estiver utilizando:

Universal Module Definition (UMD)

Para ambientes que suportam Universal Module Definition:

script

  import EfiPay from "payment-token-efi";

ECMAScript Modules (ESM)

Para ambientes que suportam ES Modules:

script

  import EfiPay from "payment-token-efi";

CommonJS (CJS)

Para ambientes que utilizam o padrão CommonJS:

script

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

Obs: Esta biblioteca não é compatível no backend em Node.js

Tipagens TypeScript

Se você estiver utilizando TypeScript, quando você instalar a biblioteca payment-token-efi, o TypeScript deve ser capaz de encontrar os tipos automaticamente localizados em types/payment-token-efi.d.ts

Utilização

Este script oferece três funções para manipulação de dados de cartão de crédito. A primeira função permite identificar a bandeira do cartão a partir do seu número. A segunda função busca informações de parcelamento de acordo com as configurações de recebimento via cartão em sua conta. Por fim, a terceira função gera o token de pagamento (payment_token) e a máscara do cartão (card_mask) com base nos dados do cartão.

Para utilizar esse script, é necessário fornecer o código Identificador de conta (payee_code) como parâmetro para gerar o payment_token dos dados do cartão de crédito. Você pode obter essa informação em sua conta digital, no menu API > Introdução > Identificador de conta. Veja onde encontrá-lo. Certifique-se de ter essa informação disponível ao utilizar as funções do script.

a) Identificar a bandeira

Identificar a bandeira

Função para identificar a bandeira

Requisição

Código

async function identifyBrand() {
    try {
      const brand = await EfiPay.CreditCard
        .setCardNumber("4485785674290087")
        .verifyCardBrand();

      console.log("Bandeira: ", brand);
    } catch (error) {
      console.log("Código: ", error.code);
      console.log("Nome: ", error.error);
      console.log("Mensagem: ", error.error_description);
    }
  }

Respostas

A resposta abaixo representa as possíveis saídas do consumo.

🟢 200

"visa" ou "mastercard" ou "amex" ou "elo" ou "hipercard" ou "undefined" ou "unsupported" 

b) Buscar as informações de parcelamento

Buscar as informações de parcelamento

Função para buscar as informações de parcelamento

Requisição

Código

async function listInstallments() {
    try {
      const installments = await EfiPay.CreditCard
        .setAccount("Identificador_de_conta_aqui")
        .setEnvironment("production") // 'production' or 'sandbox'
        .setBrand("visa")
        .setTotal(28990)
        .getInstallments();

        console.log("Parcelas", installments);
    } catch (error) {
      console.log("Código: ", error.code);
      console.log("Nome: ", error.error);
      console.log("Mensagem: ", error.error_description);
    }
  }

Respostas

A resposta abaixo representa Sucesso do consumo.

🟢 200

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

c) Gerar o payment_token e card_mask

Gerar o payment_token e card_mask

Função para gerar o payment_token e card_mask

Requisição

Código

  async function generatePaymentToken() {
    try {
      const result = await EfiPay.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();

      const payment_token = result.payment_token;
      const card_mask = result.card_mask;

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

Respostas

A resposta abaixo representa Sucesso do consumo.

🟢 200

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

e) Ativar debbuger

Ativar debbuger

O debugger pode ser ativado para depurar e encontrar possível falhas.

Requisição

Código

EfiPay.CreditCard.debugger(true);

Respostas

Em caso de erro, será retornado no try/catch o objeto como apresentado abaixo.

🟢 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', 'elo' ou 'hipercard'."
} 

Exemplos práticos

Disponibilizamos alguns exemplos de utilização para as principais linguaguagens de progração front-end. Acesse aqui.

Módulo jQuery

Uma opção para gerar o payment_token a partir dos dados do cartão é usar o front-end. Para isso, você precisa de um código JavaScript específico da sua conta Efí. Para gerá-lo, siga estes passos:

• Efetue login em sua conta Efí e acesse API.
• Copie seu Identificador de conta (veja onde)
• Cole no campo abaixo e clique no botão Gerar

---

Atenção!

Após informar seu identificador de conta, serão gerados 2 (dois) códigos JavaScript distintos.
Copie e utilize o código referente ao ambiente desejado, atentando-se às diferenças do ambiente de "Homologação" e "Produção".

Este script permitirá executar duas funções:

• getPaymentToken: Gera o payment_token de acordo com os dados do cartão;
• getInstallments: Retorna as informações sobre parcelamento de acordo com as configurações de recebimento em sua conta.

Obtendo um "payment_token" (getPaymentToken) e informações sobre parcelamentos (getInstallments)

Código

$gn.ready(function (checkout) {

    checkout.getPaymentToken(
        {
            brand: 'visa', // bandeira do cartão
            number: '4012001038443335', // número do cartão
            cvv: '123', // código de segurança
            expiration_month: '05', // mês de vencimento
            expiration_year: '2021', // ano de vencimento
            reuse: false // tokenização/reutilização do payment_token
        },
        function (error, response) {
            if (error) {
                // Trata o erro ocorrido
                console.error(error);
            } else {
                // Trata a resposta
                console.log(response);
            }
        }
    );

checkout.getInstallments(
        50000, // valor total da cobrança
        'visa', // bandeira do cartão
        function (error, response) {
            if (error) {
                // Trata o erro ocorrido
                console.log(error);
            } else {
                // Trata a respostae
                console.log(response);
            }
        }
    );

});

Atributos relacionados ao envio de dados do cartão e retorno das funcões

$gn.ready (checkout)

Essa função de inicialização permite a chamada das funções getPaymentToken e getInstallments. Você passa um objeto (checkout) que recebe as instâncias dessas funções.

getPaymentToken

Função para gerar o payment_token

Respostas

As respostas abaixo representam Sucesso e falha do consumo.

🟢 200

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

🔴 Falha

{
  "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', 'elo' ou 'hipercard'."
}
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

Função que retorna as informações sobre parcelamento

Respostas

As respostas abaixo representam Sucesso e Falha do consumo.

🟢 200

{
  "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
          }
      ]
  }
}

🔴 Falha

{
  "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', 'elo' ou 'hipercard'."
}
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

Atenção

O procedimento de geração do payment_token no back-end foi descontinuado com base em medidas de segurança. A fim de garantir a proteção dos dados, informações sensíveis e evitar recusa nas transações de cartão de crédito, recomendamos que você descontinue o uso deste serviço . Com base em nossa avaliação, gostaríamos de sugerir a geração através do front-end da aplicação

Criação de cobrança por cartão de crédito em One Step (Um passo)

Após obter o payment_token através do código Javascript ou do back-end, seu servidor enviará as informações dos itens, da transação e do cliente, juntamente com o payment_token, para a API Efí.

Estrutura hierárquica dos atributos do Schema que podem ser utilizados:

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

Requer ativação da API de Emissão de cobranças em sua aplicação.

Requisição

Dados de entrada

{
  "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": "",
    }
  }
}

Respostas

A resposta abaixo representa Sucesso do consumo.

🟢 200 (aprovado)

{
  "code": 200, // retorno HTTP "200" informando que o pedido foi bem sucedido
  "data": {
    "installments": 1, // número de parcelas em que o pagamento deve ser dividido
    "installment_value": 5990, // valor da parcela. Por exemplo: 8900 (equivale a R$ 89,00)
    "charge_id": numero_charge_id, // número da ID referente à transação gerada
    "status": "approved", // Indica que o pagamento foi aprovado pela operadora do cartão mas ainda não foi creditado.
    "total": 5990, // valor, em centavos. Por exemplo: 8900 (equivale a R$ 89,00)
    "payment": "credit_card" // forma de pagamento associada à esta transação ("credit_card" equivale a "cartão de crédito")
  }
}

🟢 200 (recusado)

{
  "code": 200, // retorno HTTP "200" informando que o pedido foi bem sucedido
  "data": {
    "installments": 1, // número de parcelas em que o pagamento deve ser dividido
    "installment_value": 5990, // valor da parcela. Por exemplo: 8900 (equivale a R$ 89,00)
    "charge_id": numero_charge_id, // número da ID referente à transação gerada
    "status": "unpaid", // Indica que o pagamento foi reprovado.
    "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.", // Mensagem que contém o motivo da recusa da transação.
          "retry": true // Indica se é possível tentar novamente a transação.
      },
    "total": 5990, // valor, em centavos. Por exemplo: 8900 (equivale a R$ 89,00)
    "payment": "credit_card" // forma de pagamento associada à esta transação ("credit_card" equivale a "cartão de crédito")
  }
}

Criação de cobrança por cartão de crédito em Two Steps (Dois passos)

Nesta opção é necessário seguir dois passos, enviando o body da requisição com todos os atributos mínimos obrigatórios para a emissão da cobrança.

1. Crie a transação, informando o item/produto/serviço, valor, quantidade, etc;
2. Associe à forma de pagamento via boleto, informando o charge_id da transação e os dados do cliente.

A documentação continua com os procedimentos detalhados, mas lembre-se de instalar uma de nossas bibliotecas em seu servidor para executar os códigos de exemplo. Certifique-se de que a SDK da Efí foi instalada.

1. Criar transação

Primeiramente, precisamos gerar a transação (também chamada de "cobrança"). Nesse momento, você informará o nome do item/produto/serviço, o valor da transação, a quantidade e outras informações relevantes.

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.

No momento da criação, a transação 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:

v1/charge

"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

Dados de entrada

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

Respostas

As respostas abaixo representam Sucesso do consumo.

🟢 200

{
  "code": 200, // retorno HTTP "200" informando que o pedido foi bem sucedido
  "data": {
    "charge_id": numero_charge_id, // número da ID referente à transação gerada
    "status": "new", // cobrança gerada, aguardando definição da forma de pagamento
    "total": 8900, // valor total da transação (em centavos, sendo 8900 = R$89,00)
    "custom_id": null, // identificador próprio opcional
    "created_at": "2021-06-01 14:58:46" // data e hora da criação da transação
  }
}

2. Associar à forma de pagamento via cartão

Com a transação gerada com sucesso, agora vamos associar com a forma de pagamento desejada - neste caso, será banking_billet (boleto bancário). Para tal, deverá ser informado o charge_id obtido ao criar a transação.

Nesta etapa, seu backend enviará o restante das informações da transação, junto com o payment_token para a API Efí.

Para associar à forma de pagamento, você deve enviar uma requisição POST para a rota /v1/charge/:id/pay, onde :id é o charge_id da transação desejada.

Estrutura hierárquica dos atributos do Schema que podem ser utilizados:

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

Requer ativação da API de Emissão de cobranças em sua aplicação

Requisição

Dados de entrada

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

Respostas

As respostas abaixo representam Sucesso do consumo.

🟢 200

{
  "code": 200, // retorno HTTP "200" informando que o pedido foi bem sucedido
  "data": {
    "installments": 1, // número de parcelas em que o pagamento deve ser dividido
    "installment_value": 8900, // valor da parcela. Por exemplo: 8900 (equivale a R$ 89,00)
    "charge_id": numero_charge_id, // número da ID referente à transação gerada
    "status": "waiting", // forma de pagamento selecionada, aguardando a confirmação do pagamento ("waiting" equivale a "aguardando")
    "total": 8900, // valor, em centavos. Por exemplo: 8900 (equivale a R$ 89,00)
    "payment": "credit_card" // forma de pagamento associada à esta transação ("credit_card" equivale a "cartão de crédito")
  }
}

Pagamento realizado como Pessoa Jurídica (PJ)

O cliente associado à transação pode ser uma Pessoa Jurídica. Nesse caso é necessário informar a Razão Social e o CNPJ da empresa pagadora no atributo juridical_person.

Relação de todos os possíveis status de uma transação

Todas as transações possuem status, que representa a "situação" dessa transação. Portanto, é importante conhecer os possíveis status de uma transação na API para fornecer as devidas tratativas em seu sistema.

Confira neste link todos os detalhes dos possíveis status das transações.

Callbacks (notificações) das transações da API para seu sistema

As notificações permitem que você seja informado quando uma transação tiver seu status alterado. Dessa forma, você poderá identificar quando um boleto for pago, por exemplo.

Confira neste link todos os detalhes sobre como implementar a sua URL de notificação.

Arredondamento de tarifa do cartão e-commerce

A formatação da tarifa é feita com number_format, ou seja, um arredondamento simples. Valores menores que 5 é arredondado para baixo, valores maiores ou igual a 5 o arredondamento é para cima.

Exemplo:
Tarifa de 3,342 é arredondado para baixo 3,34 Tarifa de 3,335 vai ser arredondado para cima 3,34

Retentativa de pagamento via cartão de crédito

Os pagamentos realizados via cartão de crédito, que forem recusados por algum motivo operacional, como falta de limite, dados incorretos e problemas temporários com o cartão, poderão ter uma nova tentativa de pagamento via API.

Dessa forma, não será necessário realizar todo o processo de emissão da cobrança novamente, tornando o fluxo mais rápido e eficiente.

POST /v1/charge/:id/retry

Requer ativação da API de Emissão de cobranças em sua aplicação

Requisição

Dados de entrada

{
  "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"
    }
  }
}

Respostas

As respostas abaixo representam Sucesso do consumo.

🟢 200

{
  "code": 200, // retorno HTTP "200" informando que o pedido foi bem sucedido
  "data": {
    "installments": 1, // número de parcelas em que o pagamento deve ser dividido
    "installment_value": 8900, // valor da parcela. Por exemplo: 8900 (equivale a R$ 89,00)
    "charge_id": numero_charge_id, // número da ID referente à transação gerada
    "status": "waiting", // forma de pagamento selecionada, aguardando a confirmação do pagamento ("waiting" equivale a "aguardando")
    "total": 8900, // valor, em centavos. Por exemplo: 8900 (equivale a R$ 89,00)
    "payment": "credit_card" // forma de pagamento associada à esta transação ("credit_card" equivale a "cartão de crédito")
  }
}

Informação

Esta funcionalidade permite que o integrador tente reprocessar uma cobrança que falhou. Para isso, a cobrança deve atender aos seguintes critérios:

a cobrança deve ser de cartão de crédito

a cobrança deve ter o status unpaid

a cobrança não pode ser recorrente

Estorno de pagamento via cartão de crédito

Este endpoint permite realizar o estorno de um pagamento efetuado por meio de cartão de crédito.

O estorno pode ser total ou parcial, dependendo do valor especificado. Se o valor não for informado, o estorno será total.

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

Requer ativação da API de Emissão de cobranças em sua aplicação

Requisição

Dados de entrada

{
  "amount": 1000
}

Respostas

A resposta abaixo representa Sucesso do consumo.

🟢 200

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

Informação

Esta funcionalidade permite que o integrador faça o estorno de um pagamento. Para isso, a cobrança deve atender aos seguintes critérios:

a cobrança deve ter o status paid

não pode ter outro estorno para a mesma cobrança ainda em processamento

só pode ter um estorno por dia para a mesma cobrança (parcial)

a cobrança tem que ser do tipo cartão de crédito

o estorno parcial pode ser solicitado em até 90 dias após a confirmação do pagamento

o estorno total pode ser solicitado em até 360 dias após a confirmação do pagamento

o estorno não está disponível para vendas de marketplace

Retornar informações de cobrança existente

Para retornar informações de uma transação, você deve enviar uma requisição GET para a rota /v1/charge/:id, onde :id é o charge_id da transação desejada.

GET /v1/charge/:id

Requer ativação da API de Emissão de cobranças em sua aplicação

Requisição

Dados de entrada

Parâmetro de entrada: informe a "charge_id" da transação desejada

Respostas

As respostas abaixo representam Sucesso(200) do consumo.

🟢 200

{
  "code": 200, // retorno HTTP "200" informando que o pedido foi bem sucedido
  "data": {
    "charge_id": 391, // número da ID referente à transação gerada
    "total": 2500, // valor total da transação (em centavos, sendo 2500 = R$25,00)
    "status": "unpaid", //não foi possível confirmar o pagamento da cobrança. O termo "unpaid" equivale a "não pago".
    "reason": "Número do cartão inválido.", //motivo da recusa do cartão
    "custom_id": null, // identificador próprio opcional
    "created_at": "2022-08-16 11:33:52", // data e hora da criação da transação
    "notification_url": null,
    "items": [
      {
        "name": "Product 1", // nome de seu item, produto ou serviço
        "value": 150, // valor, em centavos. Por exemplo: 150 (equivale a R$ 1,50)
        "amount": 10 // quantidade do item ou produto
      }
    ],
    "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"
        }
      }
    }
  }
}

Retornar lista de cobranças

Para retornar as informações das cobranças emitidas em uma aplicação, você deve enviar uma requisição GET para a rota /v1/charges.

Este endpoint possui filtros para afunilar os resultados da busca, tais como CPF/CNPJ e status. Dentre todos os filtros disponíveis, os filtros charge_type, begin_date e end_date são obrigatórios e representam o tipo da transação e o intervalo de datas em que as cobranças consultadas devem estar compreendidas.

Importante!

Atualmente este recurso está em versão beta. Estamos entusiasmados em compartilhar essa ferramenta com você, porém, é essencial lembrar que ela está em desenvolvimento ativo e pode passar por alterações durante este período.

Valorizamos profundamente seu feedback durante esta fase e queremos ouvir suas experiências e sugestões para aprimorar continuamente nossos serviços. Sinta-se à vontade para entrar em contato conosco por meio de nossa comunidade do Discord ou outros canais de suporte.

GET /v1/charges

Requer ativação da API de Emissão de cobranças em sua aplicação

Requisição

Dados de entrada

Parâmetros de entrada:  
  "charge_type"
  "customer_document"
  "status"
  "custom_id"
  "value"
  "date_of"
  "begin_date"
  "end_date"
  "limit"
  "page"
  "offset"

Respostas

As respostas abaixo representam Sucesso(200) do consumo.

🟢 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
      }
  }
}

Limite de consumo

Assim como todos os endpoints de nossa API, a listagem de cobranças também possui um limite diário, que pode ser conferido na aba Limites de Consumo.

Caso as consultas excedam estes valores, recomendamos abrir um ticket em sua conta, solicitando a liberação.

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, onde :id é o charge_id da transação desejada.

Casos de uso deste endpoint:

1. A pessoa integradora alterou o IP do servidor que estava associado à URL de notificação das transações;
2. A pessoa integradora atualizou a URL de notificação para as novas transações que forem criadas (createCharge), mas precisa atualizar também as transações anteriores (updateChargeMetadata) que foram geradas e que estão associadas com a URL incorreta/desatualizada;
3. 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";
4. A pessoa integradora gerou cobranças sem informar a URL de notificação ao enviar a requisição de criação da transação;
5. Modificar ou acrescentar uma informação junto ao atributo custom_id associado às transações geradas previamente;
6. Dentre outros possíveis cenários.

PUT /v1/charge/:id/metadata

Requer ativação da API de Emissão de cobranças em sua aplicação

Requisição

Dados de entrada

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

Respostas

As respostas abaixo representam Sucesso(200) do consumo.

🟢 200

{
  "code": 200 // retorno HTTP "200" informando que o pedido foi bem sucedido
}

Cancelar uma transação existente

Uma transação pode ser cancelada apenas se ela possuir o status new, waiting, unpaid ou link.

Quando uma transação é cancelada, existe apenas uma condição para que o status seja alterado novamente: se o cliente imprimir o boleto antes que a pessoa integradora cancele a transação, ele poderá realizar o pagamento normalmente em uma agência bancária. Nesse caso, tanto a pessoa integradora quanto a pagadora recebem a confirmação do pagamento, e o status da cobrança é alterado de canceled para paid.

Para cancelar uma transação, como um boleto, você deve enviar uma requisição PUT para a rota /v1/charge/:id/cancel, onde :id é o charge_id da transação que você deseja cancelar.

PUT /v1/charge:id/cancel

Requer ativação da API de Emissão de cobranças em sua aplicação

Requisição

Dados de entrada

Parâmetro de entrada: informe a "charge_id" da transação desejada

Respostas

As respostas abaixo representam Sucesso(200) do consumo.

🟢 200

{
  "code": 200 // retorno HTTP "200" informando que o pedido foi bem sucedido
}

Acrescentar descrição ao histórico de uma transação

O histórico de uma transação mostra todas as ações que ocorreram até o momento, mas as mensagens personalizadas não afetam a transação em si, apenas aparecem no histórico.

Este pode ser visualizado tanto no detalhamento da transação pela interface quanto usando o endpoint de detalhes da transação.

Você pode visualizar o histórico tanto na interface de detalhes da transação quanto usando o endpoint de detalhes da transação.

Você pode visualizar o histórico da transação na interface ou usando o endpoint de detalhes da transação. Para isso, basta enviar o identificador charge_id e a mensagem que deseja adicionar ao histórico da transação. A descrição deve ter entre 1 e 255 caracteres.

POST /v1/charge/:id/history

Requer ativação da API de Emissão de cobranças em sua aplicação

Requisição

Dados de entrada

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

Respostas

As respostas abaixo representam Sucesso do consumo.

🟢 200

{
  "code": 200 // retorno HTTP "200" informando que o pedido foi bem sucedido
}

Listar parcelas de acordo com a bandeira do cartão

O endpoint installments é utilizado para listar as parcelas de cada bandeira de cartão de crédito, já com os valores de juros e número de parcelas calculados de acordo com a conta integradora. Ou seja, se a sua conta possui uma configuração de juros para cartão de crédito (opção disponível para clientes que optaram por receber pagamentos de forma parcelada), você não precisa fazer nenhum cálculo adicional, pois esse endpoint já fornece os valores calculados automaticamente.

Bandeiras disponíveis: visa, mastercard, amex, elo e hipercard.

GET /v1/installments

Requer ativação da API de Emissão de cobranças em sua aplicação

Requisição

Dados de entrada

Parâmetro de entrada: informe o "brand" (bandeira) e o "total" (valor total da compra) desejado

Respostas

A resposta abaixo representa Sucesso(200) do consumo.

🟢 200

{
  "code": 200, // retorno HTTP "200" informando que o pedido foi bem sucedido
  "data": {
    "rate": 0,
    "name": "visa", // bandeira do cartão informada
    "installments": [
      {
        "installment": 1,
        "has_interest": false,
        "value": 1000, // valor da primeira parcela
        "currency": "10,00",
        "interest_percentage": 0
      },
      {
        "installment": 2,
        "has_interest": true,
        "value": 515, // valor da segunda parcela
        "currency": "5,15",
        "interest_percentage": 199
      }
    ]
  }
}