logo
Documentation Powered by ReDoc

Branvo Pay API (2.0.0)

Download OpenAPI specification:Download

Branvo: contato@branvo.com URL: https://branvopay.com
Download de ambiente e requisições prontas para o POSTMAN

Introdução

Resumo

Esta documentação tem o objetivo de auxiliar o desenvolvedor na integração com a API da plataforma Branvo Pay, para realização de pagamentos online. Estarão descritos a seguir todos os mecanismos necessários para a implementação dessa integração.

A API da Branvo Pay foi escrita seguindo os padrões da tecnologia REST (Representational State Transfer), que é o padrão atual do mercado e da maioria das APIs da web. Dessa maneira, possibilitamos aos desenvolvedores uma integração que independe da linguagem de programação escolhida.

Metodologias

A integração pode ser realizada em dois endpoints: um para ambiente sandbox e um para ambiente de produção. Recomendamos iniciar a integração em ambiente sandbox até a finalização de todos os testes necessários. Os endpoits da API Branvo Pay são os seguintes:

Sandbox

https://sandbox-api.branvopay.com/

Produção

https://api.branvopay.com/

Para envio de requisições para o ambiente sandbox da API https://sandbox-api.branvopay.com, deve ser utilizado o token de testes. O token de produção será inválido neste ambiente.

As requisições da API serão realizadas através de métodos HTTP. Cada um dos métodos possuirá uma responsabilidade distinta e seguirá um padrão de requisição. Os métodos utilizados na API Branvo Pay são os seguintes:

Método Utilização Exemplo
POST string Criar uma transação de cartão, um boleto bancário
GET decimal Criar uma transação de cartão, um boleto bancário
PUT int Capturar uma transação, solicitar a baixa de um boleto

SDKs para integração

Atualmente fornecemos SDK's (Software Development Kits) para auxiliar o desenvolvedor na integração com a API da Branvo Pay. As bibliotecas estão disponíveis nas seguintes linguagens: PHP, Javascript, Java e C#. Para orientações de instalação e uso das bibliotecas, bem como acesso ao nosso GitHub, visite https://branvopay.com/devs.

Retornos

Os retornos da API sempre serão acompanhados dos códigos HTTP correspondentes ao resultado da requisição. O formato do corpo do retorno é JSON. Os códigos HTTP utilizados pela API Branvo Pay são os seguintes:

Código Descrição
200 - OK Quando uma requisição obtém o retorno com sucesso
201 - CREATED Quando uma requisição cria um recurso com sucesso Ex.: Criação de boleto bancário com sucesso
400 - BAD REQUEST Quando uma requisição possui alguma inconsistência. Ex.: Número de cartão inválido
401 - UNAUTHORIZED Problemas de autenticação
403 - FORBIDDEN Problemas de autorização
404 - NOT FOUND Recurso não encontrado
405 - METHOD NOT ALLOWED Recurso não pode ser acessado através do método solicitado

Autenticação

A autenticação na API da Branvo Pay é realizada através do token da conta. Em todas as requisições, o token deve ser enviado através do campo 'Account-Token', no header de cada operação.

Account-Token: seu_token_aqui

Testes

Para a realização de testes na API Branvo Pay, recomendamos a utilização da ferramenta POSTMAN, disponível gratuitamente no link: https://www.getpostman.com/. No início desta documentação, disponibilizamos o download das requisições prontas para importação no POSTMAN.

A API Branvo Pay trabalha com um sistema de cache para requisições em curto intervalo de tempo. Recomendamos intervalo de 1 segundo entre requisições do mesmo tipo.

Glossário

O presente glossário visa explicar alguns termos utilizados nesta documentação, para facilitar o entendimento por parte de todos que realizarem a leitura e evitar dúvidas no momento da integração.

Cliente/Comprador – É o cliente final da loja, aquele que comprou e realizou o pagamento com seu cartão de crédito/boleto.

Loja/Usuário Branvo Pay – É o usuário cadastrado na plataforma Branvo Pay, aquele que recebe os pagamentos. (Estabelecimentos)

Entrada confirmada – O boleto foi enviado para o banco e o seu registro foi confirmado, mas esse status NÃO significa que o boleto foi pago.

Liquidação/Liquidado – Ato de pagamento do boleto/Boleto liquidado. Este é o status que GARANTE que boleto foi pago.

Baixa/Baixado – Ato de cancelamento do boleto/Boleto cancelado. Este status garante que o boleto foi CANCELADO.

Transação autorizada/aprovada – A transação foi enviada à operadora/adquirente e foi apenas AUTORIZADA, ou seja, recebemos o OK para continuar com a operação, mas ela ainda não foi debitada/creditada e enviada para a fatura do cliente. O real crédito/débito da transação acontece no momento da CAPTURA, podendo ela ser automática ou não, conforme descrito posteriormente. Este status NÃO garante a confirmação do pagamento.

Transação capturada – A transação foi enviada à operadora/adquirente e foi CAPTURADA, ou seja, neste momento é que o valor foi creditado/debitado do cliente. Atente para iniciar a logística posterior ao pagamento apenas quando a transação estiver com este status. Este status GARANTE a confirmação do pagamento, sendo que status anteriores a este NÃO garantem.

Split – Ação de realizar uma divisão de valores. Nesta modalidade, o boleto é emitido por uma conta principal, porém ao ser liquidado/baixado, o valor é dividido entre as contas desejadas.

A seguir, as especificações para integração com os recursos da API.

Boleto Bancário

Emissão

Emite um boleto bancário

header Parameters
Account-Token
required
string 32 characters
Request Body schema: application/json
clientName
required
string <= 40 characters

Nome completo do pagador

clientType
required
string
Enum: "PF" "PJ"

Tipo de pessoa do pagador

clientDocument
required
string

CPF/CNPJ do pagador

clientMail
required
string <email>

E-mail do pagador

clientSecondaryMail
string <email>

E-mail secundário do pagador

clientPhone
required
string

Telefone do pagador com DDD

clientBirthDate
string <date>

Data de nascimento do pagador

billingStreet
required
string <= 30 characters

Rua do endereço do pagador

billingNumber
required
string <= 10 characters

Número do endereço do pagador

billingComplement
string <= 30 characters

Complemento do endereço do pagador

billingNeighbourhood
required
string <= 20 characters

Bairro do endereço do pagador

billingCity
required
string <= 20 characters

Cidade do endereço do pagador

billingState
required
string
Enum: "AC" "AL" "AM" "AP" "BA" "CE" "DF" "ES" "GO" "MA" "MT" "MS" "MG" "PA" "PB" "PR" "PE" "PI" "RJ" "RN" "RO" "RS" "RR" "SC" "SE" "SP" "TO"

Estado do endereço do pagador

billingPostcode
required
string 8 characters

CEP do endereço do pagador

description
required
string

Descrição do boleto

reference
required
string <= 10 characters

Número de referência do boleto (por exemplo, número do pedido).

Este número é de controle do usuário Branvo Pay

amount
required
number >= 3

Valor do boleto

dueDate
required
string <date>

Data de vencimento do boleto

installments
required
integer [ 1 .. 12 ]

Número de parcelas

maxOverdueDays
integer [ 0 .. 30 ]

Permitir pagar em até quantos dias após o vencimento?

Utilize 0 para não permitir pag. após o vencimento

fine
number

Multa, em R$

interest
number

Juros, em %

abbreviate
boolean

Ativar a abreviação automática dos dados enviados?

Caso essa opção seja acionada, a api não retornará erros referentes à limitação de tamanho dos campos, abreviando automaticamente os dados quando o limite de caracteres de algum campo for ultrapassado

Ex: Avenida Governador Pedro Gomes Terceiro É abreviado para Av Gov Pedro Gomes III

logo
string <uri>

URL completa do logotipo da empresa

É necessário estar no formato https:// …

Caso o link seja inválido, o boleto será gerado normalmente sem a imagem

As extensões aceitas são PNG, JPG e GIF

notificationUrl
string

URL de notificação do boleto.

É o endereço através do qual a API da Branvo Pay notificará a aplicação do usuário sobre atualizações nos seus boletos. A aplicação do usuário deverá manter a URL de notificação preparada para receber via GET de acordo com a tabela abaixo:

Tabela de Parâmetros

Parâmetro Tipo Descrição
numero string Número do boleto.
Este campo é o “Nosso Número” gerado pelo banco, e não o número do pedido
valorRecebido decimal Valor pago pelo pagador
status int Status do boleto
Consultar a tabela de status abaixo
vencimento string Data de vencimento. Formato: dd/mm/YYYY
statusDescription string Descrição do Status
dataPagamento string Data de pagamento do boleto.
Formato: dd/mm/YYYY
Em caso de cancelamento, este campo conterá a data do cancelamento
multa decimal Valor de multa + juros pago pelo cliente, se houver

Tabela de Status

Código Status Descrição
0 PENDENTE Boleto está pendente de registro
1 LIQUIDADO Boleto está liquidado (pago)
2 BAIXADO Boleto está baixado (cancelado)
3 ENTRADA CONFIRMADA Boleto foi registrado
4 ALTERACAO Boleto está pendente de alguma alteração
5 PROTESTADO Boleto foi enviado para protesto
6 OUTROS Outras ocorrências
Entrar em contato com o suporte técnico
9 ERRO Erro no registro do boleto
Entrar em contato com o suporte técnico
showTop
boolean
Default: true

Mostrar topo do boleto com instruções de impressão padrão

split
boolean
Default: false

O Split de Pagamentos é um sistema que realiza as divisões dos pagamentos e taxas entre duas ou mais contas Branvo Pay, realizando uma única cobrança do seu cliente e simplificando o gerenciamento de recebíveis. Você pode informar quantas contas forem necessárias para dividir os pagamentos, especificando a quantia que cada conta deve receber, em forma de valor líquido ou porcentagem.

splitType
string
Enum: "val" "perc"

Os valores enviados serão em formato valor ou porcentagem

splitAmount
Array of numbers

Valores a serem repartidos

splitToken
Array of strings

Tokens das contas que irão receber os valores.

Deve respeitar a ordem do parâmetro splitAmount.

Ex.: Se splitAmount[0] = 100.00 e splitToken[0] = 123 a conta referente ao token 123 receberá R$ 100,00, e assim por diante

recurrent
boolean

Uma transação recorrente é uma cobrança que será feita automaticamente pela Branvo Pay, no período informado pelo cliente. É o método utilizado por clubes de assinatura e assinatura de serviços online que possuem pagamento mensal/anual.

frequence
string
Enum: "monthly" "bimonthly" "quarterly" "semester" "yearly"

Frequência de cobrança

dayNumber
string

Dia do mês para execução dessa cobrança

recurrentDueDays
integer
Default: 5

Dias para vencimento do boleto nas próximas cobranças.

Ex.: Se a cobrança é realizada no dia 15, e o parâmetro recurrentDueDays está setado para 1 dia, o vencimento do boleto será dia 16.

startDate
string <date>

Data de início da recorrência. Ela será executada automaticamente a partir desta data e, após, sempre no dia do mês informado em dayNumber, e, caso não informado, será sempre no mesmo dia presente neste campo.

Quando a data de início não for informada, a recorrência será iniciada na data atual.

finalDate
string <date>

Data final da recorrência. Ela será executada automaticamente até esta data.

Responses

200

Boleto emitido com sucesso

400

Ocorreu um problema ao emitir o boleto

post/boleto/v2/emission

Produção (Ambiente Oficial)

https://api.branvopay.com/boleto/v2/emission

Sandbox (Ambiente de Testes)

https://sandbox-api.branvopay.com/boleto/v2/emission

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "clientName": "string",
  • "clientType": "PF",
  • "clientDocument": "string",
  • "clientMail": "user@example.com",
  • "clientSecondaryMail": "user@example.com",
  • "clientPhone": "string",
  • "clientBirthDate": "2020-11-19",
  • "billingStreet": "string",
  • "billingNumber": "string",
  • "billingComplement": "string",
  • "billingNeighbourhood": "string",
  • "billingCity": "string",
  • "billingState": "AC",
  • "billingPostcode": "stringst",
  • "description": "string",
  • "reference": "string",
  • "amount": 3,
  • "dueDate": "2020-11-19",
  • "installments": 1,
  • "maxOverdueDays": 0,
  • "fine": 0,
  • "interest": 0,
  • "abbreviate": true,
  • "logo": "https://example.com/logo.png",
  • "notificationUrl": "string",
  • "showTop": true,
  • "split": true,
  • "splitType": "val",
  • "splitAmount":
    [
    ],
  • "splitToken":
    [
    ],
  • "recurrent": true,
  • "frequence": "monthly",
  • "dayNumber": "string",
  • "recurrentDueDays": 5,
  • "startDate": "0000-00-00",
  • "finalDate": "0000-00-00"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{}

Cancelamento

Realiza a solicitação de cancelamento do boleto

Esta operação NÃO garante a baixa do boleto, ela apenas é confirmada mediante aprovação e retorno bancário. Ou seja, será solicitada a baixa do boleto, o banco irá analisar, processar a baixa e retornar, e através da sua URL de notificação ele deverá ser efetivamente cancelado pela aplicação do usuário Branvo Pay

header Parameters
Account-Token
required
string 32 characters

Responses

200

Solicitação de cancelamento efetuada com sucesso

400

Ocorreu um problema ao solicitar o cancelamento o boleto

put/boleto/v2/cancel/{code}

Produção (Ambiente Oficial)

https://api.branvopay.com/boleto/v2/cancel/{code}

Sandbox (Ambiente de Testes)

https://sandbox-api.branvopay.com/boleto/v2/cancel/{code}

Request samples

Copy
<?php

use BranvoPay\Boleto;
use BranvoPay\Configuration;
use BranvoPay\Enum\Environment;

$code = 'string';

$config = new Configuration([
    'token' => 'string',
    'env' => Environment::SANDBOX,
]);

$boleto = new Boleto($config);

$response = $boleto->cancel($code);

$data = json_decode($response->getBody()->getContents());

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "success": true,
  • "data":
    {
    }
}

Consulta

Realiza a consulta do status do boleto

header Parameters
Account-Token
required
string 32 characters

Responses

200

Consulta de status do boleto efetuada com sucesso

400

Ocorreu um problema ao consultar o status do boleto

get/boleto/v2/consult/{code}

Produção (Ambiente Oficial)

https://api.branvopay.com/boleto/v2/consult/{code}

Sandbox (Ambiente de Testes)

https://sandbox-api.branvopay.com/boleto/v2/consult/{code}

Request samples

Copy
<?php

use BranvoPay\Boleto;
use BranvoPay\Configuration;
use BranvoPay\Enum\Environment;

$code = 'string';

$config = new Configuration([
    'token' => 'string',
    'env' => Environment::SANDBOX,
]);

$boleto = new Boleto($config);

$response = $boleto->consult($code);

$data = json_decode($response->getBody()->getContents());

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "success": true,
  • "data":
    {
    }
}

Cartão

Nova Transação

Cria uma nova transação de crédito/débito

header Parameters
Account-Token
required
string 32 characters
Request Body schema: application/json
clientName
required
string <= 40 characters

Nome completo do comprador

clientType
required
string
Enum: "PF" "PJ"

Tipo de pessoa do comprador

clientDocument
required
string

Documento do comprador

clientMail
required
string <email>

Email do comprador

clientPhone
required
string

Telefone do comprador com DDD

clientSecondaryMail
string <email>

Email secundário do comprador

clientBirthDate
string <date>

Data de nascimento do comprador

billingStreet
required
string <= 30 characters

Rua do endereço de cobrança do comprador

billingNumber
required
string <= 10 characters

Número do endereço de cobrança do comprador

billingNeighbourhood
required
string <= 20 characters

Bairro do endereço de cobrança do comprador

billingCity
required
string <= 20 characters

Cidade do endereço de cobrança do comprador

billingState
required
string
Enum: "AC" "AL" "AM" "AP" "BA" "CE" "DF" "ES" "GO" "MA" "MT" "MS" "MG" "PA" "PB" "PR" "PE" "PI" "RJ" "RN" "RO" "RS" "RR" "SC" "SE" "SP" "TO"

Estado do endereço de cobrança do comprador

billingPostcode
required
string 8 characters

Cep do endereço de cobrança do comprador