Create Billing
POST {{url_contbank}}/billings/accounts/:account_id
Endpoint para criação de uma nova cobrança.
O account_id deve ser enviado na URL.
O X-Current-Identity deve ser preenchido no Header da requisição.
Request Schema
| Campo | Descrição |
|---|---|
| billing_method | Indica o tipo da cobrança. Os valores aceitos são : BOLETO ou PIX. Campo obrigatório. |
| account.branch | Agência da conta que está criando a nova cobrança. Campo obrigatório. |
| account.number | Número da conta de quem está criando a nova cobrança. Campo obrigatório. |
| amount | Valor da cobrança em Reais (BRL). Atualmente, se o billing_method for BOLETO, os valores aceitos devem estar entre R$ 5,00 e R$ 120.000,00. Para cobrança via PIX não há restrição de valores. Campo obrigatório. |
| due_date | Data de vencimento da cobrança. A data limite de pagamento de uma cobrança via BOLETO, por padrão, é de 60 dias após esta data de vencimento indicada. Para PIX, o campo due_date indica a data limite de pagamento. Campo obrigatório. |
| description | Descrição da cobrança. Este valor será apresentado no PDF da cobrança. Campo opcional, mas recomendado para que o seu cliente tenha um maior esclarescimento do que trata-se a cobrança em questão. |
| payer | São os dados de quem está sendo cobrado, ou seja, do responsável pelo pagamento. Campo obrigatório. |
| payer.name | Nome ou Razão Social do pagador. |
| payer.trade_name | Campo opcional. Utilizado quando o pagador possui nome fantasia. |
| payer.address | Campo obrigatório. Caso não tenha alguma informação obrigatória do pagador, deixe não envie este objeto que iremos assumir o endereço do Contbank como padrão. |
| payer.address.zip | Campo obrigatório. Código postal do endereço do pagador. |
| payer.address.street | Campo obrigatório. Rua do endereço do pagador. |
| payer.address.neighborhood | Campo obrigatório. Bairro do endereço do pagador. |
| payer.address.city | Campo obrigatório. Cidade do endereço do pagador. |
| payer.address.state | Campo obrigatório. UF do endereço do pagador. |
| payer.email | Campo opcional. E-mail do pagador. Quando informado, enviaremos lembretes de vencimento e/ou confirmação do pagamento da cobrança. |
| payer.phone | Campo opcional. Telefone celular do pagador. Quando informado, enviaremos SMS ao número indicado, lembrando do vencimento e/ou confirmando o recebimento do pagamento da cobrança. OBSERVAÇÃO : Por padrão o disparo via SMS está desativado. Procure o time comercial do Contbank para ativação. |
| close_payment | Trata-se da data para encerramento da cobrança. Se o billingmethod for PIX, este campo é desconsiderado, pois a data de encerramento da cobrança será considerada como sendo a data do campo duedate. Campo opcional e válido apenas para billingmethod BOLETO. Se o billingmethod for PIX, este campo é desconsiderado. |
| closepaymentdays | Quantidade de dias para encerramento da cobrança. Campo opcional e válido apenas para billingmethod BOLETO. Se o billingmethod for PIX, este campo é desconsiderado. |
| discount_value | Valor da Taxa de desconto que será aplicado ao valor da cobrança quando ocorrer compensação até 1 (um) dia antes da data de vencimento. Campo opcional e válido apenas para billingmethod BOLETO. Se o billingmethod for PIX este campo é desconsiderado, pois não há a possibilidade de aplicação de desconto para este formato de cobrança. |
| discount_day | Dias para aplicação do desconto, quando a cobrança é antecipada. Campo opcional e válido apenas para billingmethod BOLETO. Se o billingmethod for PIX este campo é desconsiderado. |
| discount_type | Referente ao tipo de desconto a ser aplicado, quando a cobrança é antecipada. Valores aceitos : CURRENCY ou PERCENT. Campo opcional e válido apenas para billingmethod BOLETO. Se o billingmethod for PIX este campo é desconsiderado. |
| fine_value | Valor referente a multa. Aplicado quando pago após o vencimento. Campo opcional e válido apenas para billingmethod BOLETO. Se o billingmethod for PIX este campo é desconsiderado, pois não há a possibilidade de aplicação de multa para este formato de cobrança. |
| fine_type | Referente ao tipo da a ser aplicada. Valores aceitos : PERCENT ou CURRENCY. Campo opcional e válido apenas para billingmethod BOLETO. Se o billingmethod for PIX este campo é desconsiderado. |
| fine_day | Refere-se à quantidade de dias pós vencimento, para aplicação da multa. Campo opcional e válido apenas para billingmethod BOLETO. Se o billingmethod for PIX este campo é desconsiderado. |
| interest_value | Valor referente aos juros mensais. Aplicado quando pago após o vencimento. Campo opcional e válido apenas para billingmethod BOLETO. Se o billingmethod for PIX este campo é desconsiderado, pois não há a possibilidade de aplicação de juros para este formato de cobrança. |
| interest_day | Refere-se à quantidade de dias necessários, pós vencimento para aplicação dos juros mensais. Campo opcional e válido apenas para billingmethod BOLETO. Se o billingmethod for PIX este campo é desconsiderado. |
| interest_type | Campo opcional. Referente ao tipo de aplicação dos juros mensais. Valores aceitos : PERCENT ou CURRENCY. Campo opcional e válido apenas para billingmethod BOLETO. Se o billingmethod for PIX este campo é desconsiderado. |
| totalofinstallments | Campo opcional. Deve ser informado apenas quando for uma cobrança recorrente. Indica a quantidade de vezes/meses em que a cobrança será emitida. As emissões seguintes serão efetuadas nos meses subsequentes ao do primeiro vencimento (o informado no campo due_date). |
| partner.fee_rate | Campo opcional. Taxa percentual que será aplicada sob o valor pago. Esta taxa será destinada como crédito ao Parceiro, sendo debitada do cliente emitente. Semelhante ao fee_value. |
| partner.fee_value | Campo opcional. Taxa monetária (em R$) que será aplicada. Esta taxa será destinada como crédito ao Parceiro, sendo debitada do cliente emitente. Semelhante ao fee_rate. |
| long_looping | Campo opcional e válido apenas para billingmethod BOLETO. Se o billingmethod for PIX este campo é desconsiderado. Ao enviar a requisição com o valor false, a API retornará imediatamente a solicitação de criação de boleto e não aguardará o tempo de registro do mesmo. Utilização Recomendada: Valor true: Permite que a API aguarde o tempo necessário para o registro completo do boleto antes de retornar a resposta. Valor false: Recomendado para integrações avançadas. Ao optar por false, os parceiros devem acompanhar as mudanças de status do boleto através do webhook associado à API. Isso permitirá que atualizações sobre o status do boleto sejam recebidas em tempo real, sem esperar pela confirmação na resposta da requisição. Nota: É crucial que a integração esteja preparada para gerenciar as atualizações de status por meio do webhook correspondente ao valor falsepara garantir o acompanhamento preciso dos boletos criados. |
| ispixqrcodefilerequired | Flag para indicar a necessidade de retornar o Pix QR Code no formato de imagem png. Quando enviada como falsea imagem não é retornada. Campo opcional. Caso seja emitida uma cobrança PIX e este campo não seja enviado, iremos assumir o valor como false. |
Response Schema
| Campo | Descrição |
|---|---|
| current_identity | É o CPF/CNPJ do usuário que gerou a cobrança. |
| account | São os dados da conta que gerou a cobrança. |
| status | Pode ser PENDING(cobrança ainda sendo registrada), REGISTERED(cobrança já registrada e aguardando o pagamento), CANCELED(cobrança cancelada) ou SETTLED(cobrança paga/quitada). |
| close_payment | Indica a data limite que o pagamento é aceito. Após esta data, não é mais possível receber o pagamento da cobrança, sendo a mesma automaticamente cancelada. Para cobranças do tipo PIX este campo será retornado com o mesmo valor do due_date. |
| billingmethodrelated | Objeto que irá conter demais dados pertinentes ao tipo de cobrança (billing_method) que foi solicitado. |
| billingmethodrelated.pix_id | ID de referência do PIX vinculado a cobrança solicitada. É apenas um ID de controle e não é preciso externar ao seu cliente. |
| billingmethodrelated.pixencodedvalue | Este campo é retornado apenas para cobranças com o billingmethod indicado como PIX. Refere-se ao valor em base64 do PIX Copia e Cola. Para retornar ao seu cliente, você deve converter o valor de base64 para texto/string. Se preferir, já retornamos no campo billingmethodrelated.pixcopy_paste o valor decodificado. |
| billingmethodrelated.pixencodedfile | Este campo é retornado apenas para cobranças com o billingmethod indicado como PIX. Refere-se a imagem do QRCode no formato PNG. Essa opção será retornada apenas quando a flag ispixqrcodefile_required estiver indicada como trueno payload, pois esta opção pode ocasionar um tempo de retorno, mesmo em milissegundos, maior. |
| billingmethodrelated.pixcopypaste | Este campo é retornado apenas para cobranças com o billingmethod indicado como PIX. Refere-se ao valor string (campo pixencoded_value decodificado) do PIX Copia e Cola. |
| billingmethodrelated.boleto_id | Este campo é retornado apenas para cobranças com o billing_method indicado como PIX. ID de referência do BOLETO vinculado a cobrança solicitada. É apenas um ID de controle e não é preciso externar ao seu cliente. |
| discounts | Objeto que contém os valores de descontos a serem aplicados. Este campo é retornado apenas para cobranças com o billing_method indicado como BOLETO. |
| fine | Objeto que contém os valores de multa a serem aplicados. Este campo é retornado apenas para cobranças com o billing_method indicado como BOLETO. |
| interest | Objeto que contém os valores de juros a serem aplicados. Este campo é retornado apenas para cobranças com o billing_method indicado como BOLETO. |
| status_history | Histórico dos status que a cobrança percorreu. Trata-se de um array. O status atual da cobrança é desconsiderada no histórico. |
| created_by | ID do usuário que realizou a requisição de criação da cobrança. Ela é vinculada a credencial de acesso. |
Request Body
{"billing_method"=>"BOLETO", "account"=>{"branch"=>"{{branch_number}}", "number"=>"{{account_number}}"}, "amount"=>20.0, "due_date"=>"2023-02-01T00:00:00.0000000-03:00", "description"=>"Descrição do boleto", "payer"=>{"name"=>"Nome do Pagador do Boleto", "trade_name"=>"Nome do Pagador do Boleto", "identifier"=>"70043708013", "address"=>{"zip"=>"01301100", "street"=>"Rua da Consolação, 1000 Apto XYZ", "neighborhood"=>"Bairro Consolação", "city"=>"São Paulo", "state"=>"SP"}, "email"=>"email_da_notificacao@contbank.com", "phone"=>{"country_code"=>"55", "phone_number"=>"11999999999"}}, "discount_rate"=>15, "fine_rate"=>2, "interest_rate"=>1.75, "total_of_installments"=>2, "partner"=>{"fee_rate"=>0, "fee_value"=>2.5}, "long_looping"=>true}
HEADERS
| Key | Datatype | Required | Description |
|---|---|---|---|
X-Current-Identity | number | CPF/CNPJ do usuário que está gerando a nova cobrança. |