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.

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.

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 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."
    }
  ]
}

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 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.

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 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
email Não E-mail -
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
ATRIBUTOS DE RETORNO
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"
  }
}

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
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
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
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>"
}

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 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ça
  • recebido Valor recebido
  • tarifa Valor da tarifa descontada pelo Wide Pay
  • recebimento Data do recebimento
  • compensacao Data de compensação do valor recebido
  • status Status atual da cobrança
  • detalhamento Detalhes do recebimento
  • historico Datas de alteração do status

Retorno 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
    }
  ]
}

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 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
}

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 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
}

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 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
  }
}

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
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
email Não E-mail -
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
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 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"]
}

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 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"
}

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 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
    }
  ]
}

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 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
}

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 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
  }
}