Skip to main content

Boleto Bancário com EBANX Direct API#

Sobre este guia#

Esta página explica como adicionar Boleto à sua integração com API Direta. A integração é basicamente a mesma para todos os métodos de pagamento, apenas variando o payment_type_code e alguns campos adicionais obrigatórios.

Se você ainda não está integrado com EBANX Direct API, dê uma olhada neste guia básico. Não tem certeza se EBANX Direct API é a melhor opção para seu e-commerce? Por favor, fale com um de nossos especialistas.

O que você vai precisar#

Antes de iniciar sua integração, certifique-se de ter:

  1. Uma conta em nosso ambiente de testes. Ainda não possui sua conta? Fale com nossa equipe comercial;
  2. Boleto habilitado em sua conta.

Como funciona#

Para completar a integração do Boleto por meio da API Direta do EBANX, siga as etapas abaixo.

  1. Habilitar Boleto

    A disponibilidade do boleto pode variar dependendo do seu contrato. Portanto, o primeiro passo é verificar se ele está ativo no seu Dashboard EBANX.

    Tudo pronto? Podemos avançar para a próxima etapa, caso contrário, entre em contato com nosso representante comercial.

  2. Chame /ws/direct com a API para obter o link do boleto

    O Boleto funciona como um voucher, então você precisará redirecionar seu cliente para uma página que o contenha. Para obter este link, você só precisa chamar o end-point ws/direct (no seu servidor) com os seguintes campos obrigatórios:

    • Operação: Deve ser request;
    • Código do tipo de Pagamento: Deve ser boleto;

    Dados do Cliente:#

    • Nome;
    • E-mail;
    • CPF;
    • Endereço;
    • Número;
    • Cidade;
    • Estado;
    • CEP;
    • Telefone.

    Informação de cobrança:#

    • Código de pagamento do merchant;
    • Código da moeda;
    • Valor total a ser cobrado;

    Opcionalmente, você pode definir uma data de vencimento para o boleto usando o parâmetro payment.due_date no formato dd/mm/aaaa. Pode levar mais de três dias apenas quando a moeda de pagamento é BRL (real) e sua conta de merchant tem esse recurso habilitado. A data de vencimento é baseada na hora local do país onde o pagamento é gerado.

    Atenção

    Observe que o boleto não pode ser cancelado logo após a data de vencimento (5 dias) para ter um período de compensação adequado, especialmente quando o boleto é pago perto de um feriado. Além disso, se a data de validade for feriado ou fim de semana, devemos sempre considerar o próximo dia útil.

    Veja o exemplo:

    curl -X POST 'https://staging.ebanx.com.br/ws/direct' \
    -d 'request_body={
    "integration_key": "your_test_integration_key_here",
    "operation": "request",
    "payment": {
    "name": "José Silva",
    "email": "jose@example.com",
    "document": "853.513.468-93",
    "address": "Rua E",
    "street_number": "1040",
    "city": "Maracanaú",
    "state": "CE",
    "zipcode": "61919-230",
    "country": "br",
    "phone_number": "8522847035",
    "payment_type_code": "boleto",
    "merchant_payment_code": "a92253f29db",
    "currency_code": "BRL",
    "amount_total": 100
    }
    }'

    Uma solicitação bem sucedida retornará uma resposta JSON como mostra o exemplo abaixo. O link do boleto estará no parâmetro payment.boleto_url, e o código de barras do boleto terá o valor de payment.boleto_barcode.

    {
    "payment": {
    "hash": "59ad5dd18a6d5ba0e24327c2ba92a730115a80bd58b3baa5",
    "pin": "655158605",
    "merchant_payment_code": "af461f512c1",
    "order_number": null,
    "status": "PE",
    "status_date": null,
    "open_date": "2017-09-04 14:06:09",
    "confirm_date": null,
    "transfer_date": null,
    "amount_br": "100.38",
    "amount_ext": "100.00",
    "amount_iof": "0.38",
    "currency_rate": "1.0000",
    "currency_ext": "BRL",
    "due_date": "2017-09-08",
    "instalments": "1",
    "payment_type_code": "boleto",
    "boleto_url": "https://staging.ebanx.com.br/print/?hash=59ad5dd18a6d5ba0e24327c2ba92a730115a80bd58b3baa5",
    "boleto_barcode": "34191760071302120372714245740007572710000010038",
    "boleto_barcode_raw": "34195727100000100381760013021203721424574000",
    "pre_approved": false,
    "capture_available": null
    },
    "status": "SUCCESS"
    }
    API Reference

    A referência completa da API para o end-point ws/direct pode ser encontrada aqui. Recomendamos fortemente que você dê uma olhada em todas as opções disponíveis.

  3. Redirecionar o cliente para a url devolvida

    Redirecione seu cliente para a URL retornada no parâmetro boleto_url. Seus clientes verão uma interface como esta:

    Boleto

    Neste ponto, você tem um pagamento pendente em seu Dashboard EBANX.

    note

    Como alternativa, você pode simplesmente entregar o número do código de barras ao seu cliente.

  4. Aguarde o pagamento

    Após o pagamento do Boleto, demorará um tempo para que o EBANX seja informado pelo banco emissor do Boleto. Assim que recebermos a confirmação, o status do pagamento será modificado de pendente para confirmado.

    Caso seus clientes não paguem o Boleto, o pagamento será automaticamente cancelado.

    info

    O Boleto tem uma data de validade (que será configurada por você no parâmetro payment.due_date). Após essa data, o cliente deverá emitir um novo boleto. Opcionalmente, você pode gerar um novo Boleto e enviar aos seus clientes através do seu Dashboard EBANX.

Obtendo Ajuda#

Nós esperamos que este artigo tenha sido esclarecedor, mas caso não tenhamos tirado suas dúvidas você tem as seguintes opções para continuar buscando respostas:

  • Se você ainda não é nosso parceiro e deseja saber mais sobre nossos preços e condições, entre em contato com nossa equipe comercial.
  • Caso você já seja nosso parceiro, entre em contato com nossa equipe de suporte em faleconosco@ebanxpay.com.
Edit this page
Last updated on by Samuell Oliveira