Wide Pay API
Documentação
Seja bem-vindo à documentação do Wide Pay! Aqui você encontrará as informações necessárias para fazer a integração com nossa infraestrutura.
Visão geral
Com a API do Wide Pay, é possível utilizar qualquer recurso disponível em sua conta, como: gerar transações, carnês, assinaturas e receber notificações toda vez que algum status sofrer alteração.
Carteira e token
Para utilização da API, é necessário ter o ID da carteira e o token de autenticação.
O conceito de carteiras do Wide Pay serve para que você possa separar os recebimentos, pagamentos e transferências, como, por exemplo, se você tiver duas lojas.
Para ter um gerenciamento completo de suas carteiras, como criar, editar, obter ID e token, primeiramente, faça o login em sua conta Wide Pay, acesse o menu superior Configurações e depois clique em Carteiras.
Ambiente de testes
A configuração do ambiente de teste é realizada na hora em que você adiciona a carteira no Wide Pay.
Após realizados os testes de integração, você poderá migrar a carteira para o ambiente de produção. Lembramos que uma carteira já em produção não pode ser migrada para o ambiente de testes.
Endpoint e respostas
Todas as respostas da API são em JSON e as requisições são feitas no endpoint:
https://api.widepay.com/v1
Toda chamada para a API tem, no retorno, o atributo sucesso e, em caso de erro, também virá o atributo erro, conforme os exemplos abaixo:
{
"sucesso": true
}{
"sucesso": false,
"erro": "Mensagem de erro..."
}As mensagens de erros variam de acordo com o método e existe uma condição especial para os erros abaixo:
-
Caso a mensagem de erro seja
Erro na validação dos campos.será porque algum atributo obrigatório do método não foi enviado ou é inválido e também virá o atributovalidacao, com o detalhamento dos atributos inválidos, conforme o exemplo abaixo:{ "sucesso": false, "erro": "Erro na validação dos campos.", "validacao": [ { "id": "cpf", "erro": "O CPF informado é inválido." }, { "id": "vencimento", "erro": "O preenchimento do campo é obrigatório." } ] } -
Caso a mensagem de erro seja
Erro na execução da solicitação.será porque não houve sucesso da chamada em nenhum dos itens e também virá o atributoexecucao, com o detalhamento dos erros, conforme o exemplo abaixo:{ "sucesso": false, "erro": "Erro na execução da solicitação.", "execucao": [ { "id": "2812", "erro": "Cobrança não encontrada." }, { "id": "441", "erro": "A cobrança já está cancelada." } ] }
Exemplos
Nos exemplos que você encontrará na documentação, usaremos o cURL e os códigos compatíveis com as bibliotecas disponíveis.
Os exemplos da documentação utilizam ID 148446 e token 800440511285a9b0808ea85a94f3dd62, portanto, lembre-se de substituir pelo ID e token da sua carteira.
Dúvidas ou sugestões
Mande um e-mail para contato@widepay.com em caso de dúvidas ou sugestões de melhorias e integrações da API.
Recebimentos
Cobranças
Em cobranças, você pode realizar recebimentos via boleto de Pix.
Confira na tabela abaixo a lista de todos os status de uma cobrança e sua respectiva descrição.
| Status | Forma | Descrição |
|---|---|---|
| Aguardando | Boleto e Pix | Cobrança criada e aguardando pagamento |
| Cancelado | Boleto e Pix | Cobrança cancelada pelo solicitante |
| Em análise | Boleto | Após o pagamento, a cobrança pode ser submetida a uma análise antifraude |
| Recebido | Boleto e Pix | Pagamento recebido |
| Recebido manualmente | Boleto e Pix | Pagamento recebido manualmente |
| Vencido | Boleto e Pix | Um dia após o vencimento caso não haja o pagamento, o status é alterado |
Gerando uma cobrança
URL
https://api.widepay.com/v1/recebimentos/cobrancas/adicionar
ATRIBUTOS DE ENVIO
| Atributo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| forma | Sim | Definido | Forma de recebimento: Boleto e/ou Pix |
| cliente | Sim | String | Nome do cliente, tamanho máximo: 100 caracteres |
| pessoa | Sim | Definido | Pode ser Física ou Jurídica |
| cpf | Condicional | CPF | Obrigatório, se o atributo pessoa for Física |
| cnpj | Condicional | CNPJ | Obrigatório, se o atributo pessoa for Jurídica |
| Não | - | ||
| telefone | Não | Telefone | - |
| endereco | Não | Objeto | - |
| endereco[rua] | Não | String | Tamanho máximo: 100 caracteres |
| endereco[numero] | Não | String | Tamanho máximo: 10 caracteres |
| endereco[complemento] | Não | String | Tamanho máximo: 100 caracteres |
| endereco[bairro] | Não | String | Tamanho máximo: 100 caracteres |
| endereco[cep] | Não | CEP | - |
| endereco[cidade] | Não | String | Tamanho máximo: 100 caracteres |
| endereco[estado] | Não | String | Tamanho: 2 caracteres |
| endereco[coletar] | Não | Definido | Opção para que a tela de pagamento solicite ao cliente que informe um endereço de entrega, pode ser Não ou Sim |
| itens | Sim | Array | Itens da cobrança, máximo de itens: 10 |
| itens[][descricao] | Sim | String | Tamanho máximo: 255 caracteres |
| itens[][valor] | Sim | Decimal | Casas decimais: 2, valor mínimo: -999999.99, valor máximo: 999999.99 |
| itens[][quantidade] | Não | Numérico | Valor padrão: 1, valor máximo: 99999 |
| itens[][desconto] | Não | Decimal | Casas decimais: 2, não pode ultrapassar a quantidade x valor do item |
| desconto | Não | Decimal | Desconto para pagamento até o vencimento, casas decimais: 2, não pode ultrapassar 90% do valor da cobrança |
| multa | Não | Decimal | Valor em porcentagem, casas decimais: 2, valor máximo: 20, se não definido, pegará o valor definido no Wide Pay |
| juros | Não | Decimal | Valor em porcentagem aplicado ao mês, casas decimais: 2, valor máximo: 20, se não definido, pegará o valor definido no Wide Pay |
| referencia | Não | String | Código de referência para associar à cobrança um ID específico do seu sistema ou aplicação, tamanho máximo: 100 caracteres |
| notificacao | Não | URL | URL que será chamada quando a cobrança muda de status |
| vencimento | Condicional | Data | Obrigatório, se o atributo forma for Boleto ou Pix |
| enviar | Não | Definido | Formas de envio da cobrança, atualmente só pode ser E-mail |
| mensagem | Não | String | Memsagem enviada ao cliente no e-mail de cobrança, tamanho máximo: 255 caracteres |
| boleto | Não | Objeto | Parâmetros opcionais de configuração do boleto, utilizado somente se o atributo forma for Boleto |
| boleto[instrucoes] | Não | String, Array | Linhas de instruções, máximo de itens: 4, tamanho máximo de cada item: 100 caracteres. Se não definido, utilizará o valor definido no Wide Pay |
ATRIBUTOS DE RETORNO
| Atributo | Descrição |
|---|---|
| id | ID da cobrança gerada |
| link | Link de pagamento da cobrança |
| Link do arquivo PDF da cobrança | |
| boleto | Em caso boleto na forma de recebimento, será retornado os dados neste atributo |
| pix | Em caso Pix na forma de recebimento, será retornado os dados neste atributo |
Exemplo 1
Criando uma cobrança simples com o envio mínimo de atributos
curl \
-X POST 'https://api.widepay.com/v1/recebimentos/cobrancas/adicionar' \
-u '148446:800440511285a9b0808ea85a94f3dd62' \
-d 'forma=Pix' \
-d 'cliente=Lívia Pontarolo Almeida' \
-d 'pessoa=Física' \
-d 'cpf=463.384.662-02' \
-d 'itens[0][descricao]=Descrição item 1' \
-d 'itens[0][valor]=22.50' \
-d 'vencimento=2017-08-10' <?php
require_once('../src/WidePay.php'); // Caminho para o SDK
$wp = new WidePay('148446', '800440511285a9b0808ea85a94f3dd62'); // ID e token da carteira
$adicionar = $wp->api('recebimentos/cobrancas/adicionar', array(
'forma' => 'Pix',
'cliente' => 'Lívia Pontarolo Almeida',
'pessoa' => 'Física',
'cpf' => '463.384.662-02',
'itens' => array(
array(
'descricao' => 'Descrição item 1',
'valor' => 22.50
)
),
'vencimento' => '2017-08-10'
));
if ($adicionar->sucesso) {
echo $adicionar->id; // ID da cobrança gerada
echo $adicionar->link; // Link da cobrança gerada
} else {
echo $adicionar->erro;
if ($adicionar->erro == 'Erro na validação dos campos.') {
print_r($adicionar->validacao); // Imprime os erros de validação
}
}const moment = require("moment");
const WidePay = require("wide-pay-node");
const config = {
widePayId: '406218',
widePayToken: 'c257c157c07f397dfdf5496258b33d86'
};
const options = {
forma: 'Pix',
cliente: 'Lívia Pontarolo Almeida',
pessoa: 'Física',
cpf: '463.384.662-02',
vencimento: moment().add(5, 'days').format('YYYY-MM-DD'),
itens: [
{
'descricao': 'Descrição item 1',
'valor': 10,
}
],
};
(async () => {
const widePay = new WidePay(config.widePayId, config.widePayToken);
const adicionar = await widePay.api('/recebimentos/cobrancas/adicionar', options)
if (adicionar.sucesso) {
console.log(adicionar.id); // ID da cobrança gerada
console.log(adicionar.link); // Link da cobrança gerada
} else {
console.log(adicionar.erro);
if (adicionar.erro === 'Erro na validação dos campos.') {
console.log(adicionar.validacao); // Imprime os erros de validação
}
}
console.log(adicionar)
})()Exemplo 2
Criando uma cobrança completa com o envio de todos os atributos disponíveis
curl \
-X POST 'https://api.widepay.com/v1/recebimentos/cobrancas/adicionar' \
-u '148446:800440511285a9b0808ea85a94f3dd62' \
-d 'forma=Boleto,Pix' \
-d 'cliente=Lívia Pontarolo Almeida' \
-d 'pessoa=Física' \
-d 'cpf=463.384.662-02' \
-d 'email=emaildalivia@gmail.com' \
-d 'telefone=67 98888-0000' \
-d 'endereco[rua]=Rua Primeiro de Julho' \
-d 'endereco[numero]=192' \
-d 'endereco[complemento]=Sala 25' \
-d 'endereco[bairro]=Vila Carvalho' \
-d 'endereco[cep]=79005-610' \
-d 'endereco[cidade]=Campo Grande' \
-d 'endereco[estado]=MS' \
-d 'endereco[coletar]=Sim' \
-d 'itens[0][descricao]=Descrição item 1' \
-d 'itens[0][valor]=20' \
-d 'itens[0][quantidade]=2' \
-d 'itens[0][desconto]=4.99' \
-d 'itens[1][descricao]=Descrição item 2' \
-d 'itens[1][valor]=10.50' \
-d 'referencia=Fatura 12345' \
-d 'notificacao=http://www.minhaaplicacao.com/script-notificacao.php' \
-d 'vencimento=2017-08-10' \
-d 'enviar=E-mail' \
-d 'mensagem=Mensagem personalizada no e-mail' \
-d 'boleto[desconto]=4.5' \
-d 'boleto[multa]=2' \
-d 'boleto[juros]=1' \
-d 'boleto[instrucoes][0]=Instrução personalizada ao cliente, linha 1' \
-d 'boleto[instrucoes][1]=Instrução personalizada ao cliente, linha 2'<?php
require_once('../src/WidePay.php'); // Caminho para o SDK
$wp = new WidePay('148446', '800440511285a9b0808ea85a94f3dd62'); // ID e token da carteira
$adicionar = $wp->api('recebimentos/cobrancas/adicionar', array(
'forma' => 'Boleto,Pix',
'cliente' => 'Lívia Pontarolo Almeida',
'pessoa' => 'Física',
'cpf' => '463.384.662-02',
'email' => 'emaildalivia@gmail.com',
'telefone' => '67 98888-0000',
'endereco' => array(
'rua' => 'Rua Primeiro de Julho',
'numero' => '192',
'complemento' => 'Sala 25',
'bairro' => 'Vila Carvalho',
'cep' => '79005-610',
'cidade' => 'Campo Grande',
'estado' => 'MS',
'coletar' => 'Sim'
),
'itens' => array(
array(
'descricao' => 'Descrição item 1',
'valor' => 20,
'quantidade' => 2,
'desconto' => 4.99
),
array(
'descricao' => 'Descrição item 2',
'valor' => 10.50
)
),
'referencia' => 'Fatura 12345',
'notificacao' => 'http://www.minhaaplicacao.com/script-notificacao.php',
'vencimento' => '2017-08-10',
'enviar' => 'E-mail',
'mensagem' => 'Mensagem personalizada no e-mail',
'boleto' => array(
'desconto' => 4.5,
'multa' => 2,
'juros' => 1,
'instrucoes' => array(
'Instrução personalizada ao cliente, linha 1',
'Instrução personalizada ao cliente, linha 2'
)
)
));
if ($adicionar->sucesso) {
echo $adicionar->id; // ID da cobrança gerada
echo $adicionar->link; // Link da cobrança gerada
} else {
echo $adicionar->erro; // Erro
if ($adicionar->erro == 'Erro na validação dos campos.') {
print_r($adicionar->validacao); // Imprime os erros de validação
}
} const moment = require("moment");
const WidePay = require("wide-pay-node");
const config = {
widePayId: '406218',
widePayToken: 'c257c157c07f397dfdf5496258b33d86'
};
const options = {
forma: 'Boleto,Pix',
cliente: 'Lívia Pontarolo Almeida',
pessoa: 'Física',
cpf: '463.384.662-02',
email: 'emaildalivia@gmail.com',
telefone: '67 98888-0000',
endereco: {
rua: 'Rua Primeiro de Julho',
numero: '192',
bairro: 'Vila Carvalho',
complemento: 'Sala 25',
cep: '79005-610',
cidade: 'Campo Grande',
estado: 'MS',
coletar: 'Sim',
},
vencimento: moment().add(5, 'days').format('YYYY-MM-DD'),
itens: [
{
'descricao': 'Descrição item 1',
'valor': 20,
'quantidade': 2,
'desconto': 4.99
}, {
'descricao': 'Descrição item 2',
'valor': 10,
}
],
referencia: 'Fatura 12345',
notificacao: 'http://www.minhaaplicacao.com/script-notificacao.php'
};
(async () => {
const widePay = new WidePay(config.widePayId, config.widePayToken);
const adicionar = await widePay.api('/recebimentos/cobrancas/adicionar', options)
if (adicionar.sucesso) {
console.log(adicionar.id); // ID da cobrança gerada
console.log(adicionar.link); // Link da cobrança gerada
} else {
console.log(adicionar.erro);
if (adicionar.erro === 'Erro na validação dos campos.') {
console.log(adicionar.validacao); // Imprime os erros de validação
}
}
console.log(adicionar)
})()Retorno dos exemplos:
{
"sucesso": true,
"id": "87312",
"link": "https://www.widepay.com/cobranca/406218-87312-5c2b11f1",
"pdf": "https://www.widepay.com/cobranca/406218-87312-5c2b11f1.pdf",
"boleto": {
"parametros": {
"banco": "001",
"agencia": "6993-0",
"conta": "17282-0",
"convenio": "3188299",
"carteira": "17",
"variacao": "019",
"numero": "1"
},
"imagem": "iVBORw0KGgoAAAANSUhEUgAAAnoAAABL...",
"codigo-barras": "00191920500000005000000003351860000000000117",
"linha-digitavel": "00190.00009 03351.860006 00000.001172 1 92050000000500"
},
"pix": {
"emv": "00020101021226620014br.gov.bcb.pix...",
"imagem": "data:image/png;base64,iVBORw0KGgoAAAANSU..."
}
}Boleto de uma cobrança
Lembramos que para obter os dados do boleto de uma cobrança, a forma de recebimento da mesma deve ser Boleto.
URL
https://api.widepay.com/v1/recebimentos/cobrancas/boleto
ATRIBUTOS DE ENVIO
| Atributo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| id | Sim | String | ID da cobrança |
| html | Não | Definido | Traz no retorno da requisição o HTML do boleto, pode ser Não ou Sim, valor padrão: Não |
| carne | Não | Definido | Muda o layout HTML do boleto do formato convencional para o formato de carnê, pode ser Não ou Sim, valor padrão: Não |
| pix | Não | Definido | Adiciona o QR Code do Pix no HTML do boleto, se a cobrança tiver sido gerada com as duas formas, pode ser Não ou Sim, valor padrão: Não |
ATRIBUTOS DE RETORNO
| Atributo | Descrição |
|---|---|
| parametros | Parâmetros da configuração do boleto, pode ser usado para gerar o boleto por sistema próprio, os dados mudam dependendo do banco configurado no Wide Pay |
| imagem | Imagem do código de barras |
| codigo-barras | Código de barras do boleto |
| linha-digitavel | Linha digitável do boleto |
| html | HTML do boleto |
Exemplo 3
Obtendo dados do boleto de uma cobrança
curl \
-X POST 'https://api.widepay.com/v1/recebimentos/cobrancas/boleto' \
-u '148446:800440511285a9b0808ea85a94f3dd62' \
-d 'id=58219' \
-d 'atualizar=Sim' \
-d 'html=Sim' \
-d 'carne=Não' \
-d 'pix=Sim'<?php
require_once('../src/WidePay.php'); // Caminho para o SDK
$wp = new WidePay('148446', '800440511285a9b0808ea85a94f3dd62'); // ID e token da carteira
$boleto = $wp->api('recebimentos/cobrancas/boleto', array(
'id' => '58219',
'atualizar' => 'Sim',
'html' => 'Sim',
'carne' => 'Não',
'pix' => 'Sim'
));
if ($boleto->sucesso) {
print_r($boleto->parametros); // Imprime os parâmetros de configuração do boleto
echo $boleto->html; // HTML do boleto
} else {
echo $boleto->erro; // Erro
} const WidePay = require("wide-pay-node");
const config = {
widePayId: '406218',
widePayToken: 'c257c157c07f397dfdf5496258b33d86'
};
const options = {
id: '4509FBB5977E4854',
atualizar: 'Não',
html: 'Sim',
carne: 'Não',
pix: 'Sim'
};
(async () => {
const widePay = new WidePay(config.widePayId, config.widePayToken);
const boleto = await widePay.api('/recebimentos/cobrancas/boleto', options)
if (boleto.sucesso) {
console.log(boleto.parametros); // Imprime os parâmetros de configuração do boleto
console.log(boleto.html); // HTML do boleto
} else {
console.log(boleto.erro); // Erro
}
console.log(boleto)
})()Retorno do exemplo:
{
"sucesso": true,
"parametros": {
"banco": "033",
"agencia": "4582",
"conta": "13001057-3",
"convenio": "208822",
"carteira": "101",
"numero": "1"
},
"imagem": "iVBORw0KGgoAAAANSUhEUgAAAnoAAABL...",
"codigo-barras": "00191920500000005000000003351860000000000117",
"linha-digitavel": "00190.00009 03351.860006 00000.001172 1 92050000000500",
"html": "<table>...</table>"
}Pix de uma cobrança
Lembramos que para obter os dados do Pix de uma cobrança, a forma de recebimento da mesma deve ser Pix.
URL
https://api.widepay.com/v1/recebimentos/cobrancas/pix
ATRIBUTOS DE ENVIO
| Atributo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| id | Sim | String | ID da cobrança |
ATRIBUTOS DE RETORNO
| Atributo | Descrição |
|---|---|
| emv | Código do QR Code, Pix Copia e Cola |
| imagem | Imagem do QR Code |
Exemplo 4
Obtendo dados do Pix de uma cobrança
curl \
-X POST 'https://api.widepay.com/v1/recebimentos/cobrancas/pix' \
-u '148446:800440511285a9b0808ea85a94f3dd62' \
-d 'id=58219'<?php
require_once('../src/WidePay.php'); // Caminho para o SDK
$wp = new WidePay('148446', '800440511285a9b0808ea85a94f3dd62'); // ID e token da carteira
$pix = $wp->api('recebimentos/cobrancas/pix', array(
'id' => '58219'
));
if ($pix->sucesso) {
echo $pix->emv; // Emv do pix
echo $pix->imagem; // Imagem do pix
} else {
echo $pix->erro; // Erro
}const WidePay = require("wide-pay-node");
const config = {
widePayId: '406218',
widePayToken: 'c257c157c07f397dfdf5496258b33d86'
};
const options = {
id: '4509FBB5977E4854'
};
(async () => {
const widePay = new WidePay(config.widePayId, config.widePayToken);
const pix = await widePay.api('/recebimentos/cobrancas/pix', options)
if (pix.sucesso) {
console.log(pix.emv); // Emv do pix
console.log(pix.imagem); // Imagem do pix
} else {
console.log(pix.erro); // Erro
}
console.log(pix)
})()Retorno do exemplo:
{
"sucesso": true,
"emv": "00020101021226620014br.gov.bcb.pix...",
"imagem": "data:image/png;base64,iVBORw0KGgoAAAANSU..."
}Consultando uma cobrança
URL
https://api.widepay.com/v1/recebimentos/cobrancas/consultar
ATRIBUTOS DE ENVIO
| Atributo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| id | Não | String, Array | ID da cobrança a ser consultada, pode ser um ou mais. Caso não seja passado o ID, será retornado as últimas cobranças geradas |
ATRIBUTOS DE RETORNO
| Atributo | Descrição |
|---|---|
| total | Total de cobranças retornadas |
| cobrancas | Lista com as cobranças encontradas |
Exemplo 5
Efetuando a consulta de uma cobrança
curl \
-X POST 'https://api.widepay.com/v1/recebimentos/cobrancas/consultar' \
-u '148446:800440511285a9b0808ea85a94f3dd62' \
-d 'id=988236'<?php
require_once('../src/WidePay.php'); // Caminho para o SDK
$wp = new WidePay('148446', '800440511285a9b0808ea85a94f3dd62'); // ID e token da carteira
$consultar = $wp->api('recebimentos/cobrancas/consultar', array(
'id' => '988236'
));
if ($consultar->sucesso) {
echo $consultar->cobrancas[0]['id']; // ID da cobrança
echo $consultar->cobrancas[0]['status']; // Status da cobrança
print_r($consultar->cobrancas[0]); // Imprime todos os dados da cobrança
} else {
echo $consultar->erro; // Erro
} const WidePay = require("wide-pay-node");
const config = {
widePayId: '406218',
widePayToken: 'c257c157c07f397dfdf5496258b33d86'
};
const options = {
id: '4509FBB5977E4854',
};
(async () => {
const widePay = new WidePay(config.widePayId, config.widePayToken);
const consultar = await widePay.api('/recebimentos/cobrancas/consultar', options)
if (consultar.sucesso) {
console.log(consultar.cobrancas[0]['id']); // ID da cobrança
console.log(consultar.cobrancas[0]['status']); // Status da cobrança
console.log(consultar.cobrancas[0]); // Imprime todos os dados da cobrança
} else {
console.log(consultar.erro); // Erro
}
console.log(consultar)
})()
Alguns atributos do retorno variam de acordo com a forma do recebimento, abaixo você encontrará a descrição de alguns atributos importantes de uma cobrança, e mais abaixo, alguns exemplos de retornos:
valorValor total da cobrançarecebidoValor recebidotarifaValor da tarifa descontada pelo Wide PayrecebimentoData do recebimentocompensacaoData de compensação do valor recebidostatusStatus atual da cobrançadetalhamentoDetalhes do recebimentohistoricoDatas de alteração do status
Retorno de um exemplo de cobrança que está aguardando pagamento:
{
"sucesso": true,
"total": "1",
"cobrancas": [
{
"id": "988236",
"cobranca": null,
"carne": null,
"assinatura": null,
"forma": "Boleto,Pix",
"cliente": "Lívia Pontarolo Almeida",
"pessoa": "Física",
"cpf": "463.384.662-02",
"cnpj": null,
"email": "emaildalivia@gmail.com",
"telefone": "67 98888-0000",
"endereco": {
"rua": "Rua Primeiro de Julho",
"numero": "192",
"complemento": "Sala 25",
"bairro": "Vila Carvalho",
"cep": "79005-610",
"cidade": "Campo Grande",
"estado": "MS"
},
"itens": [
{
"descricao": "Descrição item 1",
"valor": "20",
"quantidade": "2",
"desconto": "4.99"
},
{
"descricao": "Descrição item 2",
"valor": "10.5",
"quantidade": "1",
"desconto": "0"
}
],
"referencia": "Fatura 12345",
"valor": "40.51",
"recebido": null,
"tarifa": null,
"notificacao": "http://www.minhaaplicacao.com/script-notificacao.php",
"vencimento": "2017-08-10",
"recebimento": null,
"compensacao": null,
"criacao": "2017-06-25 18:55:18",
"status": "Aguardando",
"detalhamento": null,
"duplicado": null,
"compensado": null,
"historico": [
{
"status": "Aguardando",
"data": "2017-06-25 18:55:18"
}
],
"comentario": null,
"favorito": null
}
]
}Retorno de um exemplo de cobrança recebida por boleto:
{
"sucesso": true,
"total": "1",
"cobrancas": [
{
"id": "988236",
"cobranca": null,
"carne": null,
"assinatura": null,
"forma": "Boleto",
"cliente": "Lívia Pontarolo Almeida",
"pessoa": "Física",
"cpf": "463.384.662-02",
"cnpj": null,
"email": null,
"telefone": null,
"endereco": {
"rua": null,
"numero": null,
"complemento": null,
"bairro": null,
"cep": null,
"cidade": null,
"estado": null
},
"itens": [
{
"descricao": "Descrição item 1",
"valor": "22.50",
"quantidade": "1",
"desconto": "0"
}
],
"referencia": null,
"valor": "22.50",
"recebido": "22.50",
"tarifa": "2.15",
"notificacao": null,
"vencimento": "2017-08-10",
"recebimento": "2017-06-23 00:00:00",
"compensacao": "2017-06-30",
"criacao": "2017-06-22 10:50:35",
"status": "Recebido",
"detalhamento": {
"tarifa": {
"fixa": "2.15"
}
},
"duplicado": null,
"compensado": "Não",
"historico": [
{
"status": "Aguardando",
"data": "2017-06-22 10:50:35"
},
{
"status": "Recebido",
"data": "2017-06-24 00:30:10"
}
],
"comentario": null,
"favorito": null
}
]
}Cancelando uma cobrança
URL
https://api.widepay.com/v1/recebimentos/cobrancas/cancelar
ATRIBUTOS DE ENVIO
| Atributo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| id | Sim | String, Array | ID da cobrança a ser cancelada, pode ser um ou mais |
ATRIBUTOS DE RETORNO
| Atributo | Descrição |
|---|---|
| total | Total de cobranças afetadas |
Exemplo 6
Efetuando o cancelamento de uma cobrança
curl \
-X POST 'https://api.widepay.com/v1/recebimentos/cobrancas/cancelar' \
-u '148446:800440511285a9b0808ea85a94f3dd62' \
-d 'id=58219'<?php
require_once('../src/WidePay.php'); // Caminho para o SDK
$wp = new WidePay('148446', '800440511285a9b0808ea85a94f3dd62'); // ID e token da carteira
$cancelar = $wp->api('recebimentos/cobrancas/cancelar', array(
'id' => '58219'
));
if ($cancelar->sucesso) {
echo $cancelar->total; // Total de cobranças afetadas
} else {
echo $cancelar->erro; // Erro
} const WidePay = require("wide-pay-node");
const config = {
widePayId: '406218',
widePayToken: 'c257c157c07f397dfdf5496258b33d86'
};
const options = {
id: '4509FBB5977E4854',
};
(async () => {
const widePay = new WidePay(config.widePayId, config.widePayToken);
const cancelar = await widePay.api('/recebimentos/cobrancas/cancelar', options)
if (cancelar.sucesso) {
console.log(cancelar.total); // Total de cobranças afetadas
} else {
console.log(cancelar.erro); // Erro
}
console.log(cancelar)
})()Retorno do exemplo:
{
"sucesso": true,
"total": 1
}Exemplo 7
Efetuando o cancelamento de duas ou mais cobranças
curl \
-X POST 'https://api.widepay.com/v1/recebimentos/cobrancas/cancelar' \
-u '148446:800440511285a9b0808ea85a94f3dd62' \
-d 'id[0]=58219' \
-d 'id[1]=68231'<?php
require_once('../src/WidePay.php'); // Caminho para o SDK
$wp = new WidePay('148446', '800440511285a9b0808ea85a94f3dd62'); // ID e token da carteira
$cancelar = $wp->api('recebimentos/cobrancas/cancelar', array(
'id' => array('58219', '68231')
));
if ($cancelar->sucesso) {
echo $cancelar->total; // Total de cobranças afetadas
} else {
echo $cancelar->erro; // Erro
} const WidePay = require("wide-pay-node");
const config = {
widePayId: '406218',
widePayToken: 'c257c157c07f397dfdf5496258b33d86'
};
const options = {
id: ['4509FBB5977E4854', '68231'],
};
(async () => {
const widePay = new WidePay(config.widePayId, config.widePayToken);
const cancelar = await widePay.api('/recebimentos/cobrancas/cancelar', options)
if (cancelar.sucesso) {
console.log(cancelar.total); // Total de cobranças afetadas
} else {
console.log(cancelar.erro); // Erro
}
console.log(cancelar)
})()
Retorno do exemplo:
{
"sucesso": true,
"total": 2
}Recebendo manualmente uma cobrança
URL
https://api.widepay.com/v1/recebimentos/cobrancas/manual
ATRIBUTOS DE ENVIO
| Atributo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| id | Sim | String, Array | ID da cobrança a ser recebida, pode ser um ou mais |
ATRIBUTOS DE RETORNO
| Atributo | Descrição |
|---|---|
| total | Total de cobranças afetadas |
Exemplo 8
Efetuando o recebimento manual de uma cobrança
curl \
-X POST 'https://api.widepay.com/v1/recebimentos/cobrancas/manual' \
-u '148446:800440511285a9b0808ea85a94f3dd62' \
-d 'id=58219'<?php
require_once('../src/WidePay.php'); // Caminho para o SDK
$wp = new WidePay('148446', '800440511285a9b0808ea85a94f3dd62'); // ID e token da carteira
$manual = $wp->api('recebimentos/cobrancas/manual', array(
'id' => '58219'
));
if ($manual->sucesso) {
echo $manual->total; // Total de cobranças afetadas
} else {
echo $manual->erro; // Erro
} const WidePay = require("wide-pay-node");
const config = {
widePayId: '406218',
widePayToken: 'c257c157c07f397dfdf5496258b33d86'
};
const options = {
id: '879831BF977E6369',
};
(async () => {
const widePay = new WidePay(config.widePayId, config.widePayToken);
const manual = await widePay.api('/recebimentos/cobrancas/manual', options)
if (manual.sucesso) {
console.log(manual.total); // Total de cobranças afetadas
} else {
console.log(manual.erro); // Erro
}
console.log(manual)
})()Retorno do exemplo:
{
"sucesso": true,
"total": 1
}Exemplo 9
Efetuando o recebimento manual de duas ou mais cobranças
curl \
-X POST 'https://api.widepay.com/v1/recebimentos/cobrancas/cancelar' \
-u '148446:800440511285a9b0808ea85a94f3dd62' \
-d 'id[0]=58219' \
-d 'id[1]=68231'<?php
require_once('../src/WidePay.php'); // Caminho para o SDK
$wp = new WidePay('148446', '800440511285a9b0808ea85a94f3dd62'); // ID e token da carteira
$manual = $wp->api('recebimentos/cobrancas/manual', array(
'id' => array('58219', '68231')
));
if ($manual->sucesso) {
echo $manual->total; // Total de cobranças afetadas
} else {
echo $manual->erro; // Erro
} const WidePay = require("wide-pay-node");
const config = {
widePayId: '406218',
widePayToken: 'c257c157c07f397dfdf5496258b33d86'
};
const options = {
id: ['879831BF977E6369','879831BF977E6369']
};
(async () => {
const widePay = new WidePay(config.widePayId, config.widePayToken);
const manual = await widePay.api('/recebimentos/cobrancas/manual', options)
if (manual.sucesso) {
console.log(manual.total); // Total de cobranças afetadas
} else {
console.log(manual.erro); // Erro
}
console.log(manual)
})()
Retorno do exemplo:
{
"sucesso": true,
"total": 2
}Recebendo notificação da cobrança
As notificações servem para que você seja informado de uma alteração de status da cobrança. Dessa forma você poderá, por exemplo, identificar um pagamento e fazer os procedimentos de liquidação no seu sistema ou aplicação.
As notificações são enviadas quando uma cobrança possui uma URL de notificação definida na criação, ou, se não estiver definida, o sistema envia a notificação para a URL informada nas configurações do Wide Pay.
O envio da notificação é feito via POST via o parâmetro notificacao, que conterá o ID numérico da notificação que será usado para fazer a consulta dos dados da cobrança. Também virá o parâmetro carteira, contendo o ID da carteira dona da cobrança.
URL
https://api.widepay.com/v1/recebimentos/cobrancas/notificacao
ATRIBUTOS DE ENVIO
| Atributo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| id | Sim | Numérico | ID da notificação a ser consultada |
ATRIBUTOS DE RETORNO
| Atributo | Descrição |
|---|---|
| cobranca | Objeto com dados da cobrança |
Exemplo 10
Efetuando a consulta de uma notificação
curl \
-X POST 'https://api.widepay.com/v1/recebimentos/cobrancas/notificacao' \
-u '148446:800440511285a9b0808ea85a94f3dd62' \
-d 'id='<?php
require_once('../src/WidePay.php'); // Caminho para o SDK
$wp = new WidePay('148446', '800440511285a9b0808ea85a94f3dd62'); // ID e token da carteira
$notificacao = $wp->api('recebimentos/cobrancas/notificacao', array(
'id' => $_POST["notificacao"] // ID da notificação recebido do Wide Pay via POST
));
if ($notificacao->sucesso) {
echo $notificacao->cobranca['id']; // ID da cobrança
echo $notificacao->cobranca['status']; // Status da cobrança
print_r($notificacao->cobranca); // Imprime todos os dados da cobrança
} else {
echo $notificacao->erro; // Erro
} const WidePay = require("wide-pay-node");
const config = {
widePayId: '406218',
widePayToken: 'c257c157c07f397dfdf5496258b33d86'
};
const options = {
id: request.body.notificacao
};
(async () => {
const widePay = new WidePay(config.widePayId, config.widePayToken);
const notificacao = await widePay.api('/recebimentos/cobrancas/notificacaor', options)
if (notificacao.sucesso) {
console.log(notificacao.cobranca['id']); // ID da cobrança
console.log(notificacao.cobranca['status']); // Status da cobrança
console.log(notificacao.cobranca); // Imprime todos os dados da cobrança
} else {
console.log(notificacao.erro); // Erro
}
console.log(notificacao)
})()Retorno do exemplo:
{
"sucesso": true,
"cobranca": {
"id": "81932",
"cobranca": null,
"carne": null,
"assinatura": null,
"forma": "Pix",
"cliente": "Lívia Pontarolo Almeida",
"pessoa": "Física",
"cpf": "463.384.662-02",
"cnpj": null,
"email": null,
"telefone": null,
"endereco": {
"rua": null,
"numero": null,
"complemento": null,
"bairro": null,
"cep": null,
"cidade": null,
"estado": null
},
"itens": [
{
"descricao": "Descrição item 1",
"valor": "60",
"quantidade": "1",
"desconto": "0"
}
],
"referencia": null,
"valor": "60.00",
"recebido": null,
"tarifa": null,
"notificacao": "http://www.minhaaplicacao.com/script-notificacao.php",
"vencimento": null,
"recebimento": null,
"compensacao": null,
"criacao": "2017-05-17 08:29:05",
"status": "Recebido manualmente",
"detalhamento": null,
"duplicado": null,
"compensado": null,
"historico": [
{
"status": "Aguardando",
"data": "2017-05-17 08:29:05"
},
{
"status": "Recebido manualmente",
"data": "2017-06-25 15:22:41"
}
],
"comentario": null,
"favorito": null
}
}Carnês
Um carnê é formado por várias cobranças agrupadas, as parcelas de um carnê tem o vencimento mensal, por exemplo, ao gerar um carnê com o primeiro vencimento para 15/03, a próxima parcela terá o vencimento para 15/04, sempre com intervalo de 1 mês.
Confira na tabela abaixo a lista de todos os status de um carnê e sua respectiva descrição.
| Status | Descrição |
|---|---|
| Ativo | Carnê em dia e com as parcelas aguardando o pagamento |
| Cancelado | Carnê cancelado pelo solicitante |
| Finalizado | Quando o carnê é finalizado pelo pagamento das parcelas |
| Pendente | Status aplicado quando existem uma ou mais parcelas vencidas |
Gerando um carnê
URL
https://api.widepay.com/v1/recebimentos/carnes/adicionar
ATRIBUTOS DE ENVIO
| Atributo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| forma | Sim | Definido | Forma de recebimento: Boleto e/ou Pix |
| cliente | Sim | String | Nome do cliente, tamanho máximo: 100 caracteres |
| pessoa | Sim | Definido | Pode ser Física ou Jurídica |
| cpf | Condicional | CPF | Obrigatório, se o atributo pessoa for Física |
| cnpj | Condicional | CNPJ | Obrigatório, se o atributo pessoa for Jurídica |
| Não | - | ||
| telefone | Não | Telefone | - |
| endereco | Não | Objeto | - |
| endereco[rua] | Não | String | Tamanho máximo: 100 caracteres |
| endereco[numero] | Não | String | Tamanho máximo: 10 caracteres |
| endereco[complemento] | Não | String | Tamanho máximo: 100 caracteres |
| endereco[bairro] | Não | String | Tamanho máximo: 100 caracteres |
| endereco[cep] | Não | CEP | - |
| endereco[cidade] | Não | String | Tamanho máximo: 100 caracteres |
| endereco[estado] | Não | String | Tamanho: 2 caracteres |
| itens | Sim | Array | Itens do carnê, máximo de itens: 10 |
| itens[][descricao] | Sim | String | Tamanho máximo: 255 caracteres |
| itens[][valor] | Sim | Decimal | Casas decimais: 2, valor mínimo: -999999.99, valor máximo: 999999.99 |
| itens[][quantidade] | Não | Numérico | Valor padrão: 1, valor máximo: 99999 |
| itens[][desconto] | Não | Decimal | Casas decimais: 2, não pode ultrapassar a quantidade x valor do item |
| referencia | Não | String | Código de referência para associar ao carnê um ID específico do seu sistema ou aplicação, tamanho máximo: 100 caracteres |
| notificacao | Não | URL | URL que será chamada quando o carnê muda de status |
| vencimento | Sim | Data | Primeiro vencimento do carnê |
| parcelas | Sim | Numérico | Valor mínimo: 2, valor máximo: 12 |
| dividir | Sim | Definido | Pode ser Não ou Sim. Caso seja Não, o valor total dos itens será o valor de cada parcela. Caso seja Sim, o valor total dos itens será dividido pelas parcelas |
| enviar | Não | Definido | Formas de envio do carnê, atualmente só pode ser E-mail |
| mensagem | Não | String | Memsagem enviada ao cliente no e-mail de cobrança, tamanho máximo: 255 caracteres |
| boleto | Não | Objeto | Parâmetros opcionais de configuração do boleto |
| boleto[desconto] | Não | Decimal | Desconto para pagamento por boleto até o vencimento, casas decimais: 2, não pode ultrapassar 50% do valor do carnê |
| boleto[multa] | Não | Decimal | Valor em porcentagem, casas decimais: 2, valor máximo: 20, se não definido, pegará o valor definido no Wide Pay |
| boleto[juros] | Não | Decimal | Valor em porcentagem aplicado ao mês, casas decimais: 2, valor máximo: 20, se não definido, pegará o valor definido no Wide Pay |
| boleto[instrucoes] | Não | String, Array | Linhas de instruções, máximo de itens: 4, tamanho máximo de cada item: 100 caracteres. Se não definido, utilizará o valor definido no Wide Pay |
ATRIBUTOS DE RETORNO
| Atributo | Descrição |
|---|---|
| id | ID do carnê gerado |
| link | Link de pagamento do carnê |
| cobrancas | Lista com os IDS das cobranças geradas |
Exemplo 11
Criando um carnê simples com o envio mínimo de atributos
curl \
-X POST 'https://api.widepay.com/v1/recebimentos/carnes/adicionar' \
-u '148446:800440511285a9b0808ea85a94f3dd62' \
-d 'cliente=Lívia Pontarolo Almeida' \
-d 'pessoa=Física' \
-d 'cpf=463.384.662-02' \
-d 'itens[0][descricao]=Descrição item 1' \
-d 'itens[0][valor]=22.50' \
-d 'vencimento=2018-04-10' \
-d 'parcelas=6' \
-d 'dividir=Não'<?php
require_once('../src/WidePay.php'); // Caminho para o SDK
$wp = new WidePay('148446', '800440511285a9b0808ea85a94f3dd62'); // ID e token da carteira
$adicionar = $wp->api('recebimentos/carnes/adicionar', array(
'cliente' => 'Lívia Pontarolo Almeida',
'pessoa' => 'Física',
'cpf' => '463.384.662-02',
'itens' => array(
array(
'descricao' => 'Descrição item 1',
'valor' => 22.50
)
),
'vencimento' => '2018-04-10',
'parcelas' => '6',
'dividir' => 'Não'
));
if ($adicionar->sucesso) {
echo $adicionar->id; // ID do carnê gerado
echo $adicionar->link; // Link do carnê gerado
print_r($adicionar->cobrancas); // Imprime todos os IDS das cobranças geradas
} else {
echo $adicionar->erro;
if ($adicionar->erro == 'Erro na validação dos campos.') {
print_r($adicionar->validacao); // Imprime os erros de validação
}
} const moment = require("moment");
const WidePay = require("wide-pay-node");
const config = {
widePayId: '406218',
widePayToken: 'c257c157c07f397dfdf5496258b33d86'
};
const options = {
cliente: 'Lívia Pontarolo Almeida',
pessoa: 'Física',
cpf: '463.384.662-02',
itens: [
{
'descricao': 'Descrição item 1',
'valor': 20,
'quantidade': 2,
'desconto': 4.99
}, {
'descricao': 'Descrição item 2',
'valor': 10,
}
],
vencimento: moment().add(5, 'days').format('YYYY-MM-DD'),
parcelas: 6,
dividir: 'Não',
};
(async () => {
const widePay = new WidePay(config.widePayId, config.widePayToken);
const adicionar = await widePay.api('/recebimentos/carnes/adicionar', options)
if (adicionar.sucesso) {
console.log(adicionar.id); // ID do carnê gerado
console.log(adicionar.link); // Link do carnê gerado
console.log(adicionar.cobrancas); // Imprime todos os IDS das cobranças geradas
} else {
console.log(adicionar.erro);
if (adicionar.erro === 'Erro na validação dos campos.') {
console.log(adicionar.validacao); // Imprime os erros de validação
}
}
console.log(adicionar)
})()
Exemplo 12
Criando um carnê completo com o envio de todos os atributos disponíveis
curl \
-X POST 'https://api.widepay.com/v1/recebimentos/carnes/adicionar' \
-u '148446:800440511285a9b0808ea85a94f3dd62' \
-d 'cliente=Lívia Pontarolo Almeida' \
-d 'pessoa=Física' \
-d 'cpf=463.384.662-02' \
-d 'email=emaildalivia@gmail.com' \
-d 'telefone=67 98888-0000' \
-d 'endereco[rua]=Rua Primeiro de Julho' \
-d 'endereco[numero]=192' \
-d 'endereco[complemento]=Sala 25' \
-d 'endereco[bairro]=Vila Carvalho' \
-d 'endereco[cep]=79005-610' \
-d 'endereco[cidade]=Campo Grande' \
-d 'endereco[estado]=MS' \
-d 'itens[0][descricao]=Descrição item 1' \
-d 'itens[0][valor]=20' \
-d 'itens[0][quantidade]=2' \
-d 'itens[0][desconto]=4.99' \
-d 'itens[1][descricao]=Descrição item 2' \
-d 'itens[1][valor]=10.50' \
-d 'referencia=Fatura 12345' \
-d 'notificacao=http://www.minhaaplicacao.com/script-notificacao.php' \
-d 'vencimento=2018-04-10' \
-d 'parcelas=6' \
-d 'dividir=Não' \
-d 'enviar=E-mail' \
-d 'mensagem=Mensagem personalizada no e-mail' \
-d 'boleto[desconto]=4.5' \
-d 'boleto[multa]=2' \
-d 'boleto[juros]=1' \
-d 'boleto[instrucoes][0]=Instrução personalizada ao cliente, linha 1' \
-d 'boleto[instrucoes][1]=Instrução personalizada ao cliente, linha 2'<?php
require_once('../src/WidePay.php'); // Caminho para o SDK
$wp = new WidePay('148446', '800440511285a9b0808ea85a94f3dd62'); // ID e token da carteira
$adicionar = $wp->api('recebimentos/carnes/adicionar', array(
'cliente' => 'Lívia Pontarolo Almeida',
'pessoa' => 'Física',
'cpf' => '463.384.662-02',
'email' => 'emaildalivia@gmail.com',
'telefone' => '67 98888-0000',
'endereco' => array(
'rua' => 'Rua Primeiro de Julho',
'numero' => '192',
'complemento' => 'Sala 25',
'bairro' => 'Vila Carvalho',
'cep' => '79005-610',
'cidade' => 'Campo Grande',
'estado' => 'MS'
),
'itens' => array(
array(
'descricao' => 'Descrição item 1',
'valor' => 20,
'quantidade' => 2,
'desconto' => 4.99
),
array(
'descricao' => 'Descrição item 2',
'valor' => 10.50
)
),
'referencia' => 'Fatura 12345',
'notificacao' => 'http://www.minhaaplicacao.com/script-notificacao.php',
'vencimento' => '2018-04-10',
'parcelas' => '6',
'dividir' => 'Não',
'enviar' => 'E-mail',
'mensagem' => 'Mensagem personalizada no e-mail',
'boleto' => array(
'desconto' => 4.5,
'multa' => 2,
'juros' => 1,
'instrucoes' => array(
'Instrução personalizada ao cliente, linha 1',
'Instrução personalizada ao cliente, linha 2'
)
)
));
if ($adicionar->sucesso) {
echo $adicionar->id; // ID do carnê gerado
echo $adicionar->link; // Link do carnê gerado
print_r($adicionar->cobrancas); // Imprime todos os IDS das cobranças geradas
} else {
echo $adicionar->erro; // Erro
if ($adicionar->erro == 'Erro na validação dos campos.') {
print_r($adicionar->validacao); // Imprime os erros de validação
}
} const moment = require("moment");
const WidePay = require("wide-pay-node");
const config = {
widePayId: '406218',
widePayToken: 'c257c157c07f397dfdf5496258b33d86'
};
const options = {
cliente: 'Lívia Pontarolo Almeida',
pessoa: 'Física',
cpf: '463.384.662-02',
email: 'emaildalivia@gmail.com',
telefone: '67 98888-0000',
endereco: {
rua: 'Rua Primeiro de Julho',
numero: '192',
complemento: 'Sala 25',
bairro: 'Vila Carvalho',
cep: '79005-610',
cidade: 'Campo Grande',
estado: 'MS'
},
itens: [
{
descricao: 'Descrição item 1',
valor: 20,
quantidade: 2,
desconto: 4.99
},
{
descricao: 'Descrição item 2',
valor: 10.50
}
],
referencia: 'Fatura 12345',
notificacao: 'http://www.minhaaplicacao.com/script-notificacao.php',
vencimento: moment().add(5, 'days').format('YYYY-MM-DD'),
parcelas: '6',
dividir: 'Não',
enviar: 'E-mail',
mensagem: 'Mensagem personalizada no e-mail',
boleto: {
desconto: 4.5,
multa: 2,
juros: 1,
instrucoes: [
'Instrução personalizada ao cliente, linha 1',
'Instrução personalizada ao cliente, linha 2'
]
}
};
(async () => {
const widePay = new WidePay(config.widePayId, config.widePayToken);
const adicionar = await widePay.api('/recebimentos/carnes/adicionar', options)
if (adicionar.sucesso) {
console.log(adicionar.id); // ID do carnê gerado
console.log(adicionar.link); // Link do carnê gerado
console.log(adicionar.cobrancas); // Imprime todos os IDS das cobranças geradas
} else {
console.log(adicionar.erro);
if (adicionar.erro === 'Erro na validação dos campos.') {
console.log(adicionar.validacao); // Imprime os erros de validação
}
}
console.log(adicionar)
})()
Retorno dos exemplos:
{
"sucesso": true,
"id": "16758",
"link": "https://www.widepay.com/carne/148446-16758-28c1f1a5",
"cobrancas": ["371201","371202","371203","371204","371205","371206"]
}Montando um carnê
Com esse método você tem a possibilidade de montar um carnê a partir dos IDS de cobranças já geradas.
URL
https://api.widepay.com/v1/recebimentos/carnes/montar
ATRIBUTOS DE ENVIO
| Atributo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| cobrancas | Sim | Array | IDS das cobranças que serão vinculadas ao carnê, quantidade mínima: 2, quantidade máxima: 24 |
| referencia | Não | String | Código de referência para associar ao carnê um ID específico do seu sistema ou aplicação, tamanho máximo: 100 caracteres |
| notificacao | Não | URL | URL que será chamada quando o carnê muda de status |
ATRIBUTOS DE RETORNO
| Atributo | Descrição |
|---|---|
| id | ID do carnê gerado |
| link | Link de pagamento do carnê |
Exemplo 13
Efetuando a montagem de um carnê
curl \
-X POST 'https://api.widepay.com/v1/recebimentos/carnes/montar' \
-u '148446:800440511285a9b0808ea85a94f3dd62' \
-d 'cobrancas[0]=2719' \
-d 'cobrancas[1]=2149' \
-d 'cobrancas[2]=31292'<?php
require_once('../src/WidePay.php'); // Caminho para o SDK
$wp = new WidePay('148446', '800440511285a9b0808ea85a94f3dd62'); // ID e token da carteira
$montar = $wp->api('recebimentos/carnes/montar', array(
'cobrancas' => array('2719', '2149', '31292')
));
if ($montar->sucesso) {
echo $montar->id; // ID do carnê gerado
echo $montar->link; // Link do carnê gerado
} else {
echo $montar->erro; // Erro
if ($montar->erro == 'Erro na validação dos campos.') {
print_r($montar->validacao); // Imprime os erros de validação
}
} const moment = require("moment");
const WidePay = require("wide-pay-node");
const config = {
widePayId: '406218',
widePayToken: 'c257c157c07f397dfdf5496258b33d86'
};
const options = {
cobrancas: ['2719', '2149', '31292']
};
(async () => {
const widePay = new WidePay(config.widePayId, config.widePayToken);
const montar = await widePay.api('/recebimentos/carnes/montar', options)
if (montar.sucesso) {
console.log(montar.id); // ID do carnê gerado
console.log(montar.link); // Link do carnê gerado
} else {
console.log(montar.erro); // Erro
if (montar.erro === 'Erro na validação dos campos.') {
console.log(montar.validacao); // Imprime os erros de validação
}
}
console.log(montar)
})()
Retorno do exemplo:
{
"sucesso": true,
"id": "16768",
"link": "https://www.widepay.com/carne/148446-16768-4a28c1d1"
}Consultando um carnê
URL
https://api.widepay.com/v1/recebimentos/carnes/consultar
ATRIBUTOS DE ENVIO
| Atributo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| id | Não | String, Array | ID do carnê a ser consultado, pode ser um ou mais. Caso não seja passado o ID, será retornado os últimos carnês gerados |
ATRIBUTOS DE RETORNO
| Atributo | Descrição |
|---|---|
| total | Total de carnês retornados |
| carnes | Lista com os carnês encontrados |
Exemplo 14
Efetuando a consulta de um carnê
curl \
-X POST 'https://api.widepay.com/v1/recebimentos/carnes/consultar' \
-u '148446:800440511285a9b0808ea85a94f3dd62' \
-d 'id=16758'<?php
require_once('../src/WidePay.php'); // Caminho para o SDK
$wp = new WidePay('148446', '800440511285a9b0808ea85a94f3dd62'); // ID e token da carteira
$consultar = $wp->api('recebimentos/carnes/consultar', array(
'id' => '16758'
));
if ($consultar->sucesso) {
echo $consultar->carnes[0]['id']; // ID do carnê
echo $consultar->carnes[0]['status']; // Status do carnê
print_r($consultar->carnes[0]); // Imprime todos os dados do carnê
} else {
echo $consultar->erro; // Erro
} const moment = require("moment");
const WidePay = require("wide-pay-node");
const config = {
widePayId: '406218',
widePayToken: 'c257c157c07f397dfdf5496258b33d86'
};
const options = {
id: '16758'
};
(async () => {
const widePay = new WidePay(config.widePayId, config.widePayToken);
const consultar = await widePay.api('/recebimentos/carnes/consultar', options)
if (consultar.sucesso) {
console.log(consultar.carnes[0]['id']); // ID do carnê
console.log(consultar.carnes[0]['status']); // Status do carnê
console.log(consultar.carnes[0]); // Imprime todos os dados do carnê
} else {
console.log(consultar.erro); // Erro
}
console.log(consultar)
})()
Retorno do exemplo:
{
"sucesso": true,
"total": "1",
"carnes": [
{
"id": "16758",
"cliente": "Lívia Pontarolo Almeida",
"pessoa": "Física",
"cpf": "463.384.662-02",
"cnpj": null,
"email": "emaildalivia@gmail.com",
"telefone": "67 98888-0000",
"endereco": {
"rua": "Rua Primeiro de Julho",
"numero": "192",
"complemento": "Sala 25",
"bairro": "Vila Carvalho",
"cep": "79005-610",
"cidade": "Campo Grande",
"estado": "MS"
},
"itens": [
{
"descricao": "Descrição item 1",
"valor": "20",
"quantidade": "2",
"desconto": "4.99"
},
{
"descricao": "Descrição item 2",
"valor": "10.5",
"quantidade": "1",
"desconto": "0"
}
],
"referencia": "Fatura 12345",
"valor": "40.51",
"dividir": "Não",
"parcelas": "6",
"notificacao": "http://www.minhaaplicacao.com/script-notificacao.php",
"vencimento": "2018-04-10",
"criacao": "2018-01-17 15:33:41",
"status": "Pendente",
"cobrancas": [
{
"id": "53433",
"status": "Recebido manualmente",
"recebimento": "2021-01-02",
"vencimento": "2021-01-23",
"valor": "40.51",
"recebido": "40.51",
},
{
"id": "56223",
"status": "Recebido manualmente",
"recebimento": "2021-02-02",
"vencimento": "2021-02-30",
"valor": "42",
"recebido": "40.51",
}
],
"historico": [
{
"status": "Ativo",
"data": "2018-01-17 15:33:41"
},
{
"status": "Pendente",
"data": "2018-05-11 00:41:49"
},
{
"status": "Ativo",
"data": "2018-05-23 05:46:09"
}
],
"comentario": null,
"favorito": null
}
]
}Cancelando um carnê
URL
https://api.widepay.com/v1/recebimentos/carnes/cancelar
ATRIBUTOS DE ENVIO
| Atributo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| id | Sim | String, Array | ID do carnê a ser cancelado, pode ser um ou mais |
ATRIBUTOS DE RETORNO
| Atributo | Descrição |
|---|---|
| total | Total de carnês afetados |
Exemplo 15
Efetuando o cancelamento de um carnê
curl \
-X POST 'https://api.widepay.com/v1/recebimentos/carnes/cancelar' \
-u '148446:800440511285a9b0808ea85a94f3dd62' \
-d 'id=16700'<?php
require_once('../src/WidePay.php'); // Caminho para o SDK
$wp = new WidePay('148446', '800440511285a9b0808ea85a94f3dd62'); // ID e token da carteira
$cancelar = $wp->api('recebimentos/carnes/cancelar', array(
'id' => '16700'
));
if ($cancelar->sucesso) {
echo $cancelar->total; // Total de carnês afetados
} else {
echo $cancelar->erro; // Erro
} const WidePay = require("wide-pay-node");
const config = {
widePayId: '406218',
widePayToken: 'c257c157c07f397dfdf5496258b33d86'
};
const options = {
id: '16758'
};
(async () => {
const widePay = new WidePay(config.widePayId, config.widePayToken);
const cancelar = await widePay.api('/recebimentos/carnes/cancelar', options)
if (cancelar.sucesso) {
console.log(cancelar.total); // Total de carnês afetados
} else {
console.log(cancelar.erro); // Erro
}
console.log(cancelar)
})()
Retorno do exemplo:
{
"sucesso": true,
"total": 1
}Exemplo 16
Efetuando o cancelamento de dois ou mais carnês
curl \
-X POST 'https://api.widepay.com/v1/recebimentos/carnes/cancelar' \
-u '148446:800440511285a9b0808ea85a94f3dd62' \
-d 'id[0]=16700' \
-d 'id[1]=16701'<?php
require_once('../src/WidePay.php'); // Caminho para o SDK
$wp = new WidePay('148446', '800440511285a9b0808ea85a94f3dd62'); // ID e token da carteira
$cancelar = $wp->api('recebimentos/carnes/cancelar', array(
'id' => array('16700', '16701')
));
if ($cancelar->sucesso) {
echo $cancelar->total; // Total de carnês afetados
} else {
echo $cancelar->erro; // Erro
} const WidePay = require("wide-pay-node");
const config = {
widePayId: '406218',
widePayToken: 'c257c157c07f397dfdf5496258b33d86'
};
const options = {
id: ['16758','10293']
};
(async () => {
const widePay = new WidePay(config.widePayId, config.widePayToken);
const cancelar = await widePay.api('/recebimentos/carnes/cancelar', options)
if (cancelar.sucesso) {
console.log(cancelar.total); // Total de carnês afetados
} else {
console.log(cancelar.erro); // Erro
}
console.log(cancelar)
})()
Retorno do exemplo:
{
"sucesso": true,
"total": 2
}Recebendo notificação do carnê
As notificações servem para que você seja informado de uma alteração de status do carnê. Dessa forma você poderá, por exemplo, identificar um pagamento e fazer os procedimentos de liquidação no seu sistema ou aplicação.
As notificações são enviadas quando um carnê possui uma URL de notificação definida na criação, ou, se não estiver definida, o sistema envia a notificação para a URL informada nas configurações do Wide Pay.
O envio da notificação é feito via POST via o parâmetro notificacao, que conterá o ID numérico da notificação que será usado para fazer a consulta dos dados do carnê. Também virá o parâmetro carteira, contendo o ID da carteira dona do carnê.
URL
https://api.widepay.com/v1/recebimentos/carnes/notificacao
ATRIBUTOS DE ENVIO
| Atributo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| id | Sim | Numérico | ID da notificação a ser consultada |
ATRIBUTOS DE RETORNO
| Atributo | Descrição |
|---|---|
| carne | Objeto com dados do carnê |
Exemplo 17
Efetuando a consulta de uma notificação
curl \
-X POST 'https://api.widepay.com/v1/recebimentos/carnes/notificacao' \
-u '148446:800440511285a9b0808ea85a94f3dd62' \
-d 'id='<?php
require_once('../src/WidePay.php'); // Caminho para o SDK
$wp = new WidePay('148446', '800440511285a9b0808ea85a94f3dd62'); // ID e token da carteira
$notificacao = $wp->api('recebimentos/carnes/notificacao', array(
'id' => $_POST["notificacao"] // ID da notificação recebido do Wide Pay via POST
));
if ($notificacao->sucesso) {
echo $notificacao->carne['id']; // ID do carnê
echo $notificacao->carne['status']; // Status do carnê
print_r($notificacao->carne); // Imprime todos os dados do carnê
} else {
echo $notificacao->erro; // Erro
} const WidePay = require("wide-pay-node");
const config = {
widePayId: '406218',
widePayToken: 'c257c157c07f397dfdf5496258b33d86'
};
const options = {
id: request.body.notificacao
};
(async () => {
const widePay = new WidePay(config.widePayId, config.widePayToken);
const notificacao = await widePay.api('/recebimentos/carnes/notificacaor', options)
if (notificacao.sucesso) {
console.log(notificacao.carne['id']); // ID do carnê
console.log(notificacao.carne['status']); // Status do carnê
console.log(notificacao.carne); // Imprime todos os dados do carnê
} else {
console.log(notificacao.erro); // Erro
}
console.log(notificacao)
})()
Retorno do exemplo:
{
"sucesso": true,
"carne": {
"id": "16758",
"cliente": "Lívia Pontarolo Almeida",
"pessoa": "Física",
"cpf": "463.384.662-02",
"cnpj": null,
"email": "emaildalivia@gmail.com",
"telefone": "67 98888-0000",
"endereco": {
"rua": "Rua Primeiro de Julho",
"numero": "192",
"complemento": "Sala 25",
"bairro": "Vila Carvalho",
"cep": "79005-610",
"cidade": "Campo Grande",
"estado": "MS"
},
"itens": [
{
"descricao": "Descrição item 1",
"valor": "20",
"quantidade": "2",
"desconto": "4.99"
},
{
"descricao": "Descrição item 2",
"valor": "10.5",
"quantidade": "1",
"desconto": "0"
}
],
"referencia": "Fatura 12345",
"valor": "40.51",
"dividir": "Não",
"parcelas": "6",
"notificacao": "http://www.minhaaplicacao.com/script-notificacao.php",
"vencimento": "2018-04-10",
"criacao": "2018-01-17 15:33:41",
"status": "Pendente",
"cobrancas": [
{
"id": "53433",
"recebimento": "2021-01-02",
"vencimento": "2021-01-23",
"valor": "40.51",
"recebido": "40.51",
},
{
"id": "56223",
"recebimento": "2021-02-02",
"vencimento": "2021-02-30",
"valor": "42",
"recebido": "40.51",
}
],
"historico": [
{
"status": "Ativo",
"data": "2021-01-01 15:33:41"
},
{
"status": "Pendente",
"data": "2021-01-01 00:41:49"
},
{
"status": "Ativo",
"data": "2021-01-02 05:46:09"
}
],
"comentario": null,
"favorito": null
}
}