Download OpenAPI specification:Download
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.
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 |
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.
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 |
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
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.
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.
Emite um boleto bancário
Account-Token required | string 32 characters |
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
Tabela de Status
| |||||||||||||||||||||||||||||||||||||||||||||||||||
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. |
Boleto emitido com sucesso
Ocorreu um problema ao emitir o boleto
Produção (Ambiente Oficial)
Sandbox (Ambiente de Testes)
{- "clientName": "string",
- "clientType": "PF",
- "clientDocument": "string",
- "clientMail": "user@example.com",
- "clientSecondaryMail": "user@example.com",
- "clientPhone": "string",
- "clientBirthDate": "2021-01-07",
- "billingStreet": "string",
- "billingNumber": "string",
- "billingComplement": "string",
- "billingNeighbourhood": "string",
- "billingCity": "string",
- "billingState": "AC",
- "billingPostcode": "stringst",
- "description": "string",
- "reference": "string",
- "amount": 3,
- "dueDate": "2021-01-07",
- "installments": 1,
- "maxOverdueDays": 0,
- "fine": 0,
- "interest": 0,
- "abbreviate": true,
- "notificationUrl": "string",
- "showTop": true,
- "split": true,
- "splitType": "val",
- "splitAmount": [
- 0,
- 0
], - "splitToken": [
- "string",
- "string"
], - "recurrent": true,
- "frequence": "monthly",
- "dayNumber": "string",
- "recurrentDueDays": 5,
- "startDate": "0000-00-00",
- "finalDate": "0000-00-00"
}
{- "success": true,
- "data": {
- "charges": [
- {
- "code": "string",
- "reference": "string",
- "amount": 0,
- "dueDate": "00/00/0000",
- "installmentLink": "https://sandbox-api.branvopay.com/boleto/v2/print/d1980d55fc05a3052655f61a6ac29e03",
- "recurrence": {
- "code": 0,
- "frequence": "monthly",
- "dayNumber": "string",
- "lastCharge": "00/00/0000",
- "nextCharge": "00/00/0000"
}
}
]
}
}
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
Account-Token required | string 32 characters |
Solicitação de cancelamento efetuada com sucesso
Ocorreu um problema ao solicitar o cancelamento o boleto
Produção (Ambiente Oficial)
Sandbox (Ambiente de Testes)
<?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());
{- "success": true,
- "data": {
- "charges": [
- {
- "code": "string",
- "amount": 0,
- "dueDate": "00/00/0000",
- "cancel": true,
- "status": "Solicitação de Baixa de Título"
}
]
}
}
Realiza a consulta do status do boleto
Account-Token required | string 32 characters |
Consulta de status do boleto efetuada com sucesso
Ocorreu um problema ao consultar o status do boleto
Produção (Ambiente Oficial)
Sandbox (Ambiente de Testes)
<?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());
{- "success": true,
- "data": {
- "charges": [
- {
- "code": "string",
- "amount": 0,
- "dueDate": "00/00/0000",
- "cancel": true,
- "status": "Solicitação de Baixa de Título"
}
]
}
}
Cria uma nova transação de crédito/débito
Account-Token required | string 32 characters |
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 |