Wide Pay API
Documentação
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.
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.
Também é possível utilizar os recursos de pagamento de contas, recargas de celular, transferências bancárias, transferências entre contas Wide Pay e transferências para cartões pré-pagos.
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.
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.
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 atributo validacao
, 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 atributo execucao
, com o detalhamento dos erros, conforme o exemplo abaixo:
{
"sucesso": false,
"erro": "Erro na execução da solicitação.",
"execucao": [
{
"id": "8FA0E7B48E882379",
"erro": "Cobrança não encontrada."
},
{
"id": "5C5C051E86177A22",
"erro": "A cobrança já está cancelada."
}
]
}
Nos exemplos que você encontrará na documentação, usaremos o cURL e os códigos compatíveis com as bibliotecas disponíveis.
Mande um e-mail para contato@widepay.com em caso de dúvidas ou sugestões de melhorias e integrações da API.
Em cobranças, você pode realizar recebimentos via boleto ou cartão de crédito.
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 cartão | Cobrança criada e aguardando pagamento |
Cancelado | Boleto e cartão | Cobrança cancelada pelo solicitante |
Contestado | Boleto e cartão | Quando o pagador faz uma contestação do pagamento ao Wide Pay |
Em análise | Boleto e cartão | Após o pagamento, a cobrança pode ser submetida a uma análise antifraude |
Estornado | Cartão | Quando a cobrança é estornada pelo solicitante |
Recebido | Boleto e cartão | Pagamento recebido |
Recebido manualmente | Boleto e cartão | Pagamento recebido manualmente |
Recusado | Cartão | Pagamento recusado pela administradora de cartão ou pela análise antifraude |
Vencido | Boleto e cartão | Um dia após o vencimento caso não haja o pagamento, o status é alterado |
Caso queira testar a alteração de status em uma carteira em ambiente de teste, você poderá pagar uma cobrança via cartão de crédito. Valores até R$ 100,00 retornará Recusado, acima de R$ 100,00 retornará Recebido.
https://api.widepay.com/v1/recebimentos/cobrancas/adicionar
Atributo | Obrigatório | Tipo | Descrição |
---|---|---|---|
forma | Sim | Definido | Forma de recebimento: Boleto e/ou Cartão |
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 |
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 |
redirecionamento | Não | URL | URL que o sistema redirecionará quando houver o pagamento e utilizado somente se o atributo forma for Cartão |
vencimento | Condicional | Data | Obrigatório, se o atributo forma for Boleto |
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 |
marketplace | Não | Array | Regras da divisão por marketplace, máximo de itens: 5. Se não definido, utilizará o valor definido no Wide Pay |
marketplace[][carteira] | Não | Numérico | ID da carteira para transferência |
marketplace[][valor] | Não | Decimal | Porcentagem da transferência, casas decimais: 2, valor máximo: 100.00 |
marketplace[][item] | Não | Numérico | Utilizado para que a regra de divisão seja calculada em cima de um item da cobrança |
boleto | Não | Objeto | Parâmetros opcionais de configuração do boleto, utilizado somente se o atributo forma for Boleto |
boleto[desconto] | Não | Decimal | Desconto para pagamento por boleto até o vencimento, casas decimais: 2, não pode ultrapassar 50% do valor da cobrança |
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 |
Atributo | Descrição |
---|---|
id | ID da cobrança gerada |
link | Link de pagamento da cobrança |
boleto | Caso a forma de pagamento seja boleto, 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=Cartão' \
-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'
<?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' => 'Cartão',
'cliente' => 'Lívia Pontarolo Almeida',
'pessoa' => 'Física',
'cpf' => '463.384.662-02',
'itens' => array(
array(
'descricao' => 'Descrição item 1',
'valor' => 22.50
)
)
));
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: 'Cartão',
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,Cartão' \
-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 'redirecionamento=http://www.minhaaplicacao.com/script-redirecionamento.php' \
-d 'vencimento=2017-08-10' \
-d 'enviar=E-mail' \
-d 'mensagem=Mensagem personalizada no e-mail' \
-d 'marketplace[0][carteira]=10500' \
-d 'marketplace[0][valor]=10' \
-d 'marketplace[0][item]=0' \
-d 'marketplace[1][carteira]=10800' \
-d 'marketplace[1][valor]=5' \
-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,Cartão',
'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',
'redirecionamento' => 'http://www.minhaaplicacao.com/script-redirecionamento.php',
'vencimento' => '2017-08-10',
'enviar' => 'E-mail',
'mensagem' => 'Mensagem personalizada no e-mail',
'marketplace' => array(
array(
'carteira' => 10500,
'valor' => 10,
'item' => 0
),
array(
'carteira' => 10800,
'valor' => 5
)
),
'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: 'Cartão,Boleto',
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',
redirecionamento: 'http://www.minhaaplicacao.com/script-redirecionamento.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": "70FB7FB597743802",
"link": "https://www.widepay.com/cobranca/406218-70FB7FB597743802",
"pdf": "https://www.widepay.com/cobranca/406218-70FB7FB597743802.pdf",
"boleto": {
"parametros": {
"banco": "001",
"agencia": "6993-0",
"conta": "17282-0",
"convenio": "3188299",
"carteira": "17",
"variacao": "019",
"numero": "1"
},
"codigo": "00190.00009 03188.299006 00000.001172 2 83560000004501"
}
}
Lembramos que para obter os dados do boleto de uma cobrança, a forma de recebimento da mesma deve ser Boleto
.
https://api.widepay.com/v1/recebimentos/cobrancas/boleto
Atributo | Obrigatório | Tipo | Descrição |
---|---|---|---|
id | Sim | String | ID da cobrança |
atualizar | Não | Definido | Atualiza automaticamente a data do boleto caso esteja vencido, pode ser Não ou Sim , valor padrão: Sim |
vencimento | Não | Data | Atualiza a data de vencimento, disponível somente se o atributo atualizar for Sim |
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 |
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 |
codigo | Código de barras 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=8AF962B49E3920BB' \
-d 'atualizar=Sim' \
-d 'html=Sim' \
-d 'carne=Não'
<?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' => '8AF962B49E3920BB',
'atualizar' => 'Sim',
'html' => 'Sim',
'carne' => 'Não'
));
if ($boleto->sucesso) {
print_r($boleto->parametros); // Imprime os parâmetros de configuração do boleto
echo $boleto->codigo; // Código de barras 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'
};
(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.codigo); // Código de barras 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"
},
"codigo": "03399.81276 22000.000004 00001.901016 1 73280000002250",
"html": "<table>...</table>"
}
https://api.widepay.com/v1/recebimentos/cobrancas/consultar
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 |
Atributo | Descrição |
---|---|
total | Total de cobranças retornadas |
cobrancas | Lista com as cobranças encontradas |
Exemplo 4
Efetuando a consulta de uma cobrança
curl \
-X POST 'https://api.widepay.com/v1/recebimentos/cobrancas/consultar' \
-u '148446:800440511285a9b0808ea85a94f3dd62' \
-d 'id=264C51BE984C7718'
<?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' => '264C51BE984C7718'
));
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:
valor
Valor total da cobrançarecebido
Valor recebidotarifa
Valor da tarifa descontada pelo Wide Payrecebimento
Data do recebimentocompensacao
Data de compensação do valor recebidostatus
Status atual da cobrançadetalhamento
Detalhes do recebimentohistorico
Datas de alteração do statusRetorno de um exemplo de cobrança que está aguardando pagamento:
{
"sucesso": true,
"total": "1",
"cobrancas": [
{
"id": "264C51BE984C7718",
"cobranca": null,
"carne": null,
"assinatura": null,
"forma": "Boleto,Cartão",
"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",
"redirecionamento": "http://www.minhaaplicacao.com/script-redirecionamento.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": "264C51BE984C7718",
"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,
"redirecionamento": 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
}
]
}
Retorno de um exemplo de cobrança recebida por cartão de crédito:
{
"sucesso": true,
"total": "1",
"cobrancas": [
{
"id": "264C51BE984C7718",
"cobranca": null,
"carne": null,
"assinatura": null,
"forma": "Cartão",
"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": "51.75",
"quantidade": "1",
"desconto": "0"
}
],
"referencia": null,
"valor": "51.75",
"recebido": "51.75",
"tarifa": "2.91",
"notificacao": null,
"redirecionamento": null,
"vencimento": null,
"recebimento": "2017-06-20 14:20:12",
"compensacao": "2017-07-20",
"criacao": "2017-06-10 09:34:28",
"status": "Recebido",
"detalhamento": {
"bandeira": "MasterCard",
"cartao": "9080",
"parcelas": "1",
"fatura": "NomeLoja",
"tarifa": {
"fixa": 0.35,
"porcentagem": 2.56
}
},
"duplicado": null,
"compensado": "Sim",
"historico": [
{
"status": "Aguardando",
"data": "2017-06-10 09:34:28"
},
{
"status": "Recebido",
"data": "2017-06-20 14:20:12"
}
],
"comentario": null,
"favorito": null
}
]
}
https://api.widepay.com/v1/recebimentos/cobrancas/cancelar
Atributo | Obrigatório | Tipo | Descrição |
---|---|---|---|
id | Sim | String, Array | ID da cobrança a ser cancelada, pode ser um ou mais |
Atributo | Descrição |
---|---|
total | Total de cobranças afetadas |
Exemplo 5
Efetuando o cancelamento de uma cobrança
curl \
-X POST 'https://api.widepay.com/v1/recebimentos/cobrancas/cancelar' \
-u '148446:800440511285a9b0808ea85a94f3dd62' \
-d 'id=8AF962B49E3920BB'
<?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' => '8AF962B49E3920BB'
));
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 6
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]=8AF962B49E3920BB' \
-d 'id[1]=922FEDBE9835857A'
<?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('8AF962B49E3920BB', '922FEDBE9835857A')
));
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', '922FEDBE9835857A'],
};
(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
}
https://api.widepay.com/v1/recebimentos/cobrancas/manual
Atributo | Obrigatório | Tipo | Descrição |
---|---|---|---|
id | Sim | String, Array | ID da cobrança a ser recebida, pode ser um ou mais |
Atributo | Descrição |
---|---|
total | Total de cobranças afetadas |
Exemplo 7
Efetuando o recebimento manual de uma cobrança
curl \
-X POST 'https://api.widepay.com/v1/recebimentos/cobrancas/manual' \
-u '148446:800440511285a9b0808ea85a94f3dd62' \
-d 'id=8AF962B49E3920BB'
<?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' => '8AF962B49E3920BB'
));
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 8
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]=8AF962B49E3920BB' \
-d 'id[1]=922FEDBE9835857A'
<?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('8AF962B49E3920BB', '922FEDBE9835857A')
));
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
}
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.
https://api.widepay.com/v1/recebimentos/cobrancas/notificacao
Atributo | Obrigatório | Tipo | Descrição |
---|---|---|---|
id | Sim | Numérico | ID da notificação a ser consultada |
Atributo | Descrição |
---|---|
cobranca | Objeto com dados da cobrança |
Exemplo 9
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": "9F15771E9FA3AFEF",
"cobranca": null,
"carne": null,
"assinatura": null,
"forma": "Cartão",
"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",
"redirecionamento": null,
"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
}
}
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 |
https://api.widepay.com/v1/recebimentos/carnes/adicionar
Atributo | Obrigatório | Tipo | Descrição |
---|---|---|---|
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 |
marketplace | Não | Array | Regras da divisão por marketplace, máximo de itens: 5. Se não definido, utilizará o valor definido no Wide Pay |
marketplace[][carteira] | Não | Numérico | ID da carteira para transferência |
marketplace[][valor] | Não | Decimal | Porcentagem da transferência, casas decimais: 2, valor máximo: 100.00 |
marketplace[][item] | Não | Numérico | Utilizado para que a regra de divisão seja calculada em cima de um item da cobrança |
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 |
Atributo | Descrição |
---|---|
id | ID do carnê gerado |
link | Link de pagamento do carnê |
cobrancas | Lista com os IDS das cobranças geradas |
Exemplo 10
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 11
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 'marketplace[0][carteira]=10500' \
-d 'marketplace[0][valor]=10' \
-d 'marketplace[0][item]=0' \
-d 'marketplace[1][carteira]=10800' \
-d 'marketplace[1][valor]=5' \
-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',
'marketplace' => array(
array(
'carteira' => 10500,
'valor' => 10,
'item' => 0
),
array(
'carteira' => 10800,
'valor' => 5
)
),
'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',
marketplace: [
{
carteira: 10500,
valor: 10,
item: 0
}, {
carteira: 10800,
valor: 5
}
],
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",
"cobrancas": ["387A98B52D924091","15CBD6BFCD924091","3A769A152392EA9B","4A22ACB5CD924A91","2E7966BF23924A91","94C8C9B52D92E091"]
}
Com esse método você tem a possibilidade de montar um carnê a partir dos IDS de cobranças já geradas.
https://api.widepay.com/v1/recebimentos/carnes/montar
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 |
Atributo | Descrição |
---|---|
id | ID do carnê gerado |
link | Link de pagamento do carnê |
Exemplo 12
Efetuando a montagem de um carnê
curl \
-X POST 'https://api.widepay.com/v1/recebimentos/carnes/montar' \
-u '148446:800440511285a9b0808ea85a94f3dd62' \
-d 'cobrancas[0]=5F151D278C9DDC80' \
-d 'cobrancas[1]=7CF34C1FF5E842B0' \
-d 'cobrancas[2]=6AB79C5F626436A8'
<?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('5F151D278C9DDC80', '7CF34C1FF5E842B0', '6AB79C5F626436A8')
));
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: ['5F151D278C9DDC80', '7CF34C1FF5E842B0', '6AB79C5F626436A8']
};
(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"
}
https://api.widepay.com/v1/recebimentos/carnes/consultar
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 |
Atributo | Descrição |
---|---|
total | Total de carnês retornados |
carnes | Lista com os carnês encontrados |
Exemplo 13
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": "8FA0DABF16210EC1",
"status": "Recebido manualmente",
"recebimento": "2021-01-02",
"vencimento": "2021-01-23",
"valor": "40.51",
"recebido": "40.51",
},
{
"id": "5C8C1E1F16C20E2B",
"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
}
]
}
https://api.widepay.com/v1/recebimentos/carnes/cancelar
Atributo | Obrigatório | Tipo | Descrição |
---|---|---|---|
id | Sim | String, Array | ID do carnê a ser cancelado, pode ser um ou mais |
Atributo | Descrição |
---|---|
total | Total de carnês afetados |
Exemplo 14
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 15
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
}
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ê.
https://api.widepay.com/v1/recebimentos/carnes/notificacao
Atributo | Obrigatório | Tipo | Descrição |
---|---|---|---|
id | Sim | Numérico | ID da notificação a ser consultada |
Atributo | Descrição |
---|---|
carne | Objeto com dados do carnê |
Exemplo 16
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": "8FA0DABF16210EC1",
"recebimento": "2021-01-02",
"vencimento": "2021-01-23",
"valor": "40.51",
"recebido": "40.51",
},
{
"id": "5C8C1E1F16C20E2B",
"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
}
}