# QI Tech — Banking-as-a-Service › Pagamento de boletos Documentação da QI Tech em texto corrido, para colar em um LLM. Fonte: https://docs.qitech.com.br 54 página(s). Índice: - Cancelar agendamento em lote de pagamento (/documentation/baas/cobranca/2fa_v2/agendamento/cancelar_agendamento_em_lote_de_pagamento) - Confirmar Agendamento de Boleto Bancário (/documentation/baas/cobranca/2fa_v2/agendamento/confirmar_agendamento_de_boleto_bancario) - Confirmação de Pagamento de Fatura de Recolhimento (/documentation/baas/cobranca/2fa_v2/agendamento/confirmar_agendamento_de_fatura_de_recolhimento) - Confirmar agendamento em lote de boleto bancário (/documentation/baas/cobranca/2fa_v2/agendamento/confirmar_agendamento_em_lote_de_boleto_bancario) - Confirmar agendamento em lote de fatura de recolhimento (/documentation/baas/cobranca/2fa_v2/agendamento/confirmar_agendamento_em_lote_de_fatura_de_recolhimento) - Consultar lote de agendamento de pagamento (/documentation/baas/cobranca/2fa_v2/agendamento/consultar_lote_de_agendamento_de_pagamento) - Listar lotes de agendamento de pagamento (/documentation/baas/cobranca/2fa_v2/agendamento/listar_lotes_de_agendamento_de_pagamento) - Reenviar Token Autenticação de Dois Fatores de Agendamento de Boleto Bancário (/documentation/baas/cobranca/2fa_v2/agendamento/reenviar_token_de_agendamento_boleto_bancario) - Reenviar Token Autenticação de Dois Fatores de Agendamento de Fatura de Recolhimento (/documentation/baas/cobranca/2fa_v2/agendamento/reenviar_token_de_agendamento_de_fatura_de_recolhimento) - Reenviar token de autenticação de dois fatores de agendamento em lote de boleto bancário (/documentation/baas/cobranca/2fa_v2/agendamento/reenviar_token_de_agendamento_em_lote_de_boleto_bancario) - Reenviar token de autenticação de dois fatores de agendamento em lote de fatura de recolhimento (/documentation/baas/cobranca/2fa_v2/agendamento/reenviar_token_de_agendamento_em_lote_de_fatura_de_recolhimento) - Solicitar Agendamento de Pagamento de Boleto Bancário com Autenticação de Dois Fatores (2FA) (/documentation/baas/cobranca/2fa_v2/agendamento/solicitar_agendamento_de_boleto_bancario) - Solicitar Agendamento de Pagamento de Facutara de Recolhimento com Autenticação de Dois Fatores (2FA) (/documentation/baas/cobranca/2fa_v2/agendamento/solicitar_agendamento_de_pagamento_de_fatura_de_recolhimento) - Solicitar agendamento em lote de boleto bancário com autenticação de dois fatores (2FA) (/documentation/baas/cobranca/2fa_v2/agendamento/solicitar_agendamento_em_lote_de_boleto_bancario) - Solicitar agendamento em lote de fatura de recolhimento com autenticação de dois fatores (2FA) (/documentation/baas/cobranca/2fa_v2/agendamento/solicitar_agendamento_em_lote_de_fatura_de_recolhimento) - Confirmação de lote de pagamento de boleto bancário (/documentation/baas/cobranca/2fa_v2/confirmacao_de_lote_de_boleto_bancario) - Confirmação de lote de pagamento de fatura de recolhimento (convênio/tributo) (/documentation/baas/cobranca/2fa_v2/confirmacao_de_lote_de_fatura_de_recolhimento) - Confirmação de Pagamento de Boleto Bancário (/documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_boleto_bancario) - Confirmação de Pagamento de Fatura de Recolhimento (/documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_fatura_de_recolhimento) - Introdução a Autenticação de Dois Fatores (/documentation/baas/cobranca/2fa_v2/introducao_ao_pagamento_2fa) - Solicitação de pagamento de Boleto Bancário com Autenticação de Dois Fatores (/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_boleto_bancario) - Solicitação de Pagamento de Fatura de Recolhimento com Autenticação de Dois Fatores (/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_fatura_de_recolhimento) - Reenviar Token Autenticação de Dois Fatores de Pagamentos de Boleto Bancário (/documentation/baas/cobranca/2fa_v2/solicitacao_de_reenvio_de_token_de_boleto_bancario) - Reenviar Token de Autenticação de Dois Fatores para Pagamentos de Fatura de Recolhimento (/documentation/baas/cobranca/2fa_v2/solicitacao_de_reenvio_de_token_de_fatura_de_recolhimento) - Reenviar token de confirmação de lote de pagamento de boleto bancário (/documentation/baas/cobranca/2fa_v2/solicitacao_de_reenvio_de_token_de_lote_de_boleto_bancario) - Reenviar token de confirmação de lote de pagamento de fatura de recolhimento (convênio/tributo) (/documentation/baas/cobranca/2fa_v2/solicitacao_de_reenvio_de_token_de_lote_de_fatura_de_recolhimento) - Solicitar pagamento em lote de boleto bancário com autenticação de dois fatores (/documentation/baas/cobranca/2fa_v2/solicitar_pagamento_lote_de_boleto_bancario_com_confirmacao_de_lote) - Solicitar pagamento em lote de boleto bancário com autenticação de dois fatores (/documentation/baas/cobranca/2fa_v2/solicitar_pagamento_lote_de_boleto_bancario_sem_confirmacao_de_lote) - Solicitar pagamento em lote de fatura de recolhimento (convênio/tributo) com autenticação de dois fatores (/documentation/baas/cobranca/2fa_v2/solicitar_pagamento_lote_de_fatura_de_recolhimento_com_confirmacao_de_lote) - Solicitar pagamento em lote de fatura de recolhimento (convênio/tributo) com autenticação de dois fatores (/documentation/baas/cobranca/2fa_v2/solicitar_pagamento_lote_de_fatura_de_recolhimento_sem_confirmacao_de_lote) - Validação de token de lote de pagamento de boleto bancário (/documentation/baas/cobranca/2fa_v2/validacao_de_token_de_lote_de_boleto_bancario) - Validação de token de lote de pagamento de fatura de recolhimento (convênio/tributo) (/documentation/baas/cobranca/2fa_v2/validacao_de_token_de_lote_de_fatura_de_recolhimento) - Agendar Pagamento de Boleto Bancário (/documentation/baas/cobranca/agendamento/agendar_pagamento_de_boleto_bancario) - Agendar Pagamento de Fatura de Recolhimento (convênio/tributo) (/documentation/baas/cobranca/agendamento/agendar_pagamento_de_fatura_de_recolhimento) - Cancelar Agendamento (/documentation/baas/cobranca/agendamento/cancelar_agendamento) - Consultar Agendamento (/documentation/baas/cobranca/agendamento/consultar_agendamento) - Listar Agendamentos (/documentation/baas/cobranca/agendamento/listar_agendamentos) - Solicitar agendamento em lote de boleto bancário (/documentation/baas/cobranca/agendamento/solicitar_agendamento_em_lote_de_boleto_bancario) - Solicitar agendamento em lote de fatura de recolhimento (/documentation/baas/cobranca/agendamento/solicitar_agendamento_em_lote_de_fatura_de_recolhimento) - Confirmação de lote de pagamento de boleto bancário (/documentation/baas/cobranca/confirmacao_de_lote_de_boleto_bancario) - Confirmação de lote de pagamento de fatura de recolhimento (convênio/tributo) (/documentation/baas/cobranca/confirmacao_de_lote_de_fatura_de_recolhimento) - Consulta de Boleto Bancário (/documentation/baas/cobranca/consultar_boleto_bancario) - Consulta de Fatura de Recolhimento (/documentation/baas/cobranca/consultar_fatura_de_recolhimento) - Consultar lote de pagamento (/documentation/baas/cobranca/consultar_lote_de_pagamento) - Listar lotes de pagamento (/documentation/baas/cobranca/listar_lotes_de_pagamento) - Listar Pagamentos (/documentation/baas/cobranca/listar_pagamentos) - Realizar Pagamento de Boleto Bancário (/documentation/baas/cobranca/pagar_boleto_bancario) - Realizar Pagamento de Fatura de Recolhimento (convênio/tributo) (/documentation/baas/cobranca/pagar_fatura_de_recolhimento) - Simulação de cenários (/documentation/baas/cobranca/simulacao_de_cenarios) - Solicitar Pagamento em Lote de Boleto Bancário (/documentation/baas/cobranca/solicitar_pagamento_lote_de_boleto_bancario_com_confirmacao_de_lote) - Solicitar Pagamento em Lote de Boleto Bancário (/documentation/baas/cobranca/solicitar_pagamento_lote_de_boleto_bancario_sem_confirmacao_de_lote) - Solicitar Pagamento em Lote de Fatura de Recolhimento (convênio/tributo) (/documentation/baas/cobranca/solicitar_pagamento_lote_de_fatura_de_recolhimento_com_confirmacao_de_lote) - Solicitar Pagamento em Lote de Fatura de Recolhimento (convênio/tributo) (/documentation/baas/cobranca/solicitar_pagamento_lote_de_fatura_de_recolhimento_sem_confirmacao_de_lote) - Webhooks (/documentation/baas/cobranca/webhooks) --- # Cancelar agendamento em lote de pagamento URL: /documentation/baas/cobranca/2fa_v2/agendamento/cancelar_agendamento_em_lote_de_pagamento Este endpoint permite cancelar um lote de agendamento de pagamentos enquanto o lote estiver em status cancelável. :::info Boleto bancário É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central. ::: :::info Fatura de recolhimento Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta. ::: ## Request ### Request Endpoint ENDPOINT /account/ ACCOUNT_KEY /batch_payment_schedule/ BATCH_PAYMENT_SCHEDULE_KEY /cancel MÉTODO PATCH ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |-----------------------|-------|--------------------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | | `batch_payment_key` * | uuid4 | Chave única de identificação do lote de agendamento. | 36 | ## Response ### Success Response STATUS 200 Response Body: Lote de agendamento cancelado ```json { "batch_payment_schedule_key": "a3214093-e51c-55e2-b5d3-60244475b3fb", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f", "total_amount": 1357.3, "batch_payment_schedule_status": "canceled", "payment_type": "bank_slip" } ``` ### Response Body Params | Campo | Tipo | Descrição | |--------------------------------|--------|-----------| | `batch_payment_schedule_key` * | uuid4 | Chave única de identificação do lote de agendamento. | | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `account_key` * | uuid4 | Chave da conta debitada. | | `total_amount` * | number | Soma dos valores dos itens do lote. | | `batch_payment_schedule_status` * | [enum](#enumeradores-batch_payment_schedule_status) | Status do lote após a solicitação de cancelamento. | | `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. | ### Enumeradores batch_payment_schedule_status | Enumerador | Descrição | |------------------------|---------------------------| | `pending_2fa_approval` | Pendente de aprovação 2FA | | `scheduled` | Agendado | | `rejected` | Rejeitado | | `canceled` | Cancelado | | `error` | Erro ao agendar | ### Enumeradores payment_type | Enumerador | Descrição | |-------------------|------------------------| | `bank_slip` | Boleto bancário | | `collection_slip` | Fatura de recolhimento | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|-------------|----------------------------------------------|--------------------------------------------------------| | 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação | | 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. | | 404 | BIP000083 | Not Found | Batch payment not found by batch payment key.| Lote de pagamentos não encontrado pela chave do lote. | | 400 | BIP000085 | Bad Request | Batch payment status is not pending approval.| Status do lote de pagamentos não é de aprovação pendente. | --- # Confirmar Agendamento de Boleto Bancário URL: /documentation/baas/cobranca/2fa_v2/agendamento/confirmar_agendamento_de_boleto_bancario Este endpoint permite realizar a confirmação do agendamento de pagamento de um boleto bancário. :::info Boleto bancário É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central. ::: ## Request ENDPOINT /account/ ACCOUNT_KEY /payment_schedule/ PAYMENT_SCHEDULE_KEY /bank_slip/validate_token MÉTODO PATCH ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | | `payment_schedule_key` * | uuid4 | Chave única de identificação do agendamento. | 36 | Request Body: Confirmação de agendamento de boleto bancário ```json { "token": "329adf" } ``` ### Body Params | Campo | Tipo | Descrição | |---------------------|---------------|-----------------------------------| | `token` * | string | Código de autenticação enviado ao aprovador de movimentações da conta | ## Response ### Success Response STATUS 200 Response Body: Agendamento confirmado ```json { "payment_schedule_key":"c4325104-d60b-44f3-aae4-49155564a2ea", "request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189", "payer_name":"COOPERATIVA INDUSTRIAL MURILO", "payer_document_number":"00037025000160", "source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f", "paid_amount":1050.1, "payment_date":"2024-04-03", "payment_type":"bank_slip", "bank_slip": { "bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a", "barcode":"00193967000009910000000003615574000000002417", "digitable_line":"00190000090361557400500000024174396700000991000", "payer_name":"COOPERATIVA TESTE", "payer_document_number":"00037025000160", "beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA", "beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA", "beneficiary_document_number":"52069937000117", "beneficiary_bank_ispb":"00000000", "guarantor_name":null, "guarantor_document_number":null, "expiration_date":"2024-03-29", "max_payment_data": "2026-03-29", "partial_payment_indicator":"allowed", "registered_payment_amount":9029.0, "nominal_amount":9910.0, "total_amount":10129.1, "rebate_amount":0.0, "discount_amount":0.0, "fine_amount":0.0, "interest_amount":219.1 }, "collection_slip":null, "payment_schedule_status":"scheduled" } ``` ### Response Body Params | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------------------------| | `payment_key` * | uuid4 | Chave única de identificação do pagamento. | | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente. | | `payer_name` * | string | Nome do pagador efetivo. | | `payer_document_number` * | string | Número do documento do pagador efetivo (CPF/CNPJ). | | `source_account_key` * | uuid4 | Chave da conta debitada. | | `paid_amount` * | number | Valor pago efetivamente. | | `payment_date` * | string | Data do pagamento. | | `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. | | `bank_slip` | [object](#objeto-bank_slip) | Boleto bancário. | | `collection_slip` | object | Fatura de recolhimento. | | `payment_schedule_status` * | [enum](#enumeradores-payment_schedule_status) | Status do agendamento. | ### Enumeradores payment_type | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | :::danger Aviso O enumerador `collection_slip` não se aplica para o fluxo de boletos bancários, assim como o objeto collection_slip que sempre será nulo. ::: ### Enumeradores payment_schedule_status | Enumerador | Descrição | |---------------------|------------------------------------------------------------------| | `pending_2fa_approval` | Agendamento pendente de autenticação de dois fatores (2FA) | | `scheduled` | Pagamento agendado com sucesso | | `executed` | O agendamento foi executado com sucesso e o pagamento referente ao agendamento gerado | | `rejected` | O agendamento foi rejeitado e nenhum pagamento foi gerado | | `canceled` | Agendamento cancelado | | `error` | Erro ao realizar o agendamento | ### Objeto bank_slip | Campo | Tipo | Descrição | |-----------------------------------|---------|-----------------------------------| | `barcode` * | string | Código de barras. | | `digitable_line` * | string | Linha digitável. | | `payer_name` * | string | Nome do pagador.| | `payer_document_number` * | string | Número do documento do pagador (CPF/CNPJ). | | `beneficiary_name` * | string | Nome do beneficiário. | | `beneficiary_trading_name` | string | Nome fantasia do beneficiário. | | `beneficiary_document_number` * | string | Número do documento do beneficiário (CPF/CNPJ). | | `beneficiary_bank_ispb` * | string | Código ispb do banco do beneficiário. | | `guarantor_name` | string | Nome do sacador avalista. | | `guarantor_document_number` | string | Número do documento do sacador avalista (CPF/CNPJ). | | `expiration_date` * | string | Data de vencimento. | | `max_payment_date` * | string | Data máxima de pagamento. | | `partial_payment_indicator` * | [enum](#enumeradores-partial_payment_indicator) | Indicador de pagamento parcial. | | `registered_payment_amount` | string | Valor total de pagamento registrado. | | `nominal_amount` * | number | Valor original. | | `total_amount` * | number | Valor total. | | `rebate_amount` * | number | Valor do batimento. | | `discount_amount` * | number | Valor do desconto. | | `fine_amount` * | number | Valor da multa. | | `interest_amount` * | number | Valor do juros. | ### Enumeradores partial_payment_indicator | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `allowed` | string | Permitido | | `not_allowed` | string | Não permitido | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação | | 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. | | 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. | | 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. | | 400 | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. | | 400 | BIP000022 | Bad Request | Bank slip payment service is closed. | Serviço de pagamento de boleto está fechado. | | 400 | BIP000023 | Bad Request | The source account has insufficient balance. Payment cannot be made. | A conta de origem possui saldo insuficiente. Pagamento não pode ser realizado. | | 400 | BIP000025 | Bad Request | It was not possible to pay the bank slip at this time. Please verify your information and, if necessary, contact us for assistance. | Não foi possível pagar o boleto neste momento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para assistência. | | 400 | BIP000028 | Bad Request | The source account has blocked balance. Payment cannot be made. | A conta de origem possui saldo em conta bloqueado. Pagamento não pode ser realizado. | | 404 | BIP000056 | Not Found | Payment not found. | Pagamento não encontrado. | | 400 | BIP000057 | Bad Request | Payment status is not pending approval. | Status de pagamento não é de aprovação pendente. | | 400 | BIP000058 | Bad Request | Error while validating verification token | Erro ao validar token de verificação | | 400 | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Número de tentativas de validação de token de verificação excedido. | | 400 | BIP000060 | Bad Request | Verification token expired. | Token de verificação expirado. | | 400 | BIP000061 | Bad Request | Verification token validation failed. | Falha na validação do token de verificação. | | 400 | BIP000062 | Bad Request | Payment type is not bank slip. | Tipo de pagamento não é boleto. | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. | --- # Confirmação de Pagamento de Fatura de Recolhimento URL: /documentation/baas/cobranca/2fa_v2/agendamento/confirmar_agendamento_de_fatura_de_recolhimento Este endpoint permite realizar a confirmação do pagamento de faturas de recolhimento. :::info Fatura de recolhimento Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgão públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta. ::: ## Request ### Request Endpoint ENDPOINT /account/ ACCOUNT_KEY /payment_schedule/ PAYMENT_SCHEDULE_KEY /collection_slip/validate_token MÉTODO PATCH ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | | `payment_schedule_key` * | uuid4 | Chave única de identificação do agendamento. | 36 | Request Body: Confirmação de agendamento de fatura de recolhimento ```json { "token": "329adf" } ``` ### Body Params | Campo | Tipo | Descrição | |---------------------|---------------|-----------------------------------| | `token` * | string | Código de autenticação enviado ao aprovador de movimentações da conta | ## Response ### Success Response STATUS 200 Response Body: Agendamento confirmado ```json { "payment_schedule_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a", "request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9", "payer_name": "COOPERATIVA INDUSTRIAL MURILO", "payer_document_number": "62069937000118", "source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72", "paid_amount": 1389.21, "payment_date": "2024-04-30", "payment_type": "collection_slip", "bank_slip": null, "collection_slip": { "barcode": null, "digitable_line": "836200000138892100450006762142420244046000010192", "collection_name": "CIA ULTRAGAZ SA-COD", "collection_document_number": "00394460005887", "expiration_date": "2024-04-15", "total_amount": 1389.21 }, "payment_status": "scheduled" } ``` ### Response Body Params | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------------------------| | `payment_key` * | uuid4 | Chave única de identificação do pagamento. | | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente. | | `payer_name` * | string | Nome do pagador efetivo. | | `payer_document_number` * | string | Número do documento do pagador efetivo (CPF/CNPJ). | | `source_account_key` * | uuid4 | Chave da conta debitada. | | `paid_amount` * | number | Valor pago efetivamente. | | `payment_date` * | string | Data do pagamento. | | `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. | | `bank_slip` | object | Boleto bancário. | | `collection_slip` | [object](#objeto-collection_slip) | Fatura de recolhimento. | | `payment_schedule_status` * | [enum](#enumeradores-payment_schedule_status) | Status do agendamento. | ### Enumeradores payment_type | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | :::danger Aviso O enumerador `bank_slip` não se aplica para o fluxo de faturas de recolhimento, assim como o objeto bank_slip que sempre será nulo. ::: ### Enumeradores payment_schedule_status | Enumerador | Descrição | |---------------------|------------------------------------------------------------------| | `pending_2fa_approval` | Agendamento pendente de autenticação de dois fatores (2FA) | | `scheduled` | Pagamento agendado com sucesso | | `executed` | O agendamento foi executado com sucesso e o pagamento referente ao agendamento gerado | | `rejected` | O agendamento foi rejeitado e nenhum pagamento foi gerado | | `canceled` | Agendamento cancelado | | `error` | Erro ao realizar o agendamento | ### Objeto collection_slip | Campo | Tipo | Descrição | |-----------------------------------|---------|-----------------------------------| | `barcode` | string | Código de barras. | | `digitable_line` | string | Linha digitável. | | `collection_name` * | string | Nome do convênio.| | `collection_document_number` | string | Número de documento do convênio (CPF/CNPJ).| | `expiration_date` * | string | Data de vencimento. | | `total_amount` * | number | Valor total. | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação | | 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. | | 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. | | 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. | | 400 | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |s | 400 | BIP000023 | Bad Request | The source account has insufficient balance. Payment cannot be made. | A conta de origem possui saldo insuficiente. Pagamento não pode ser realizado. | | 400 | BIP000028 | Bad Request | The source account has blocked balance. Payment cannot be made. | A conta de origem possui saldo em conta bloqueado. Pagamento não pode ser realizado. | | 400 | BIP000036 | Bad Request | Covenant slip overdue. | Fatura de recolhimento vencida. | | 400 | BIP000038 | Bad Request | Outside of covenant payment hours. | Fora do horário de pagamento do convênio. | | 400 | BIP000044 | Bad Request | It was not possible to pay the collection slip at this time. Please verify your information and, if necessary, contact us for assistance. | Não foi possível pagar a fatura de recolhimento neste momento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para assistência. | | 400 | BIP000045 | Bad Request | Collection slip payment service is closed. | Serviço de pagamento de fatura de recolhimento está fechado. | | 404 | BIP000056 | Not Found | Payment not found. | Pagamento não encontrado. | | 400 | BIP000057 | Bad Request | Payment status is not pending approval. | Status de pagamento não é de aprovação pendente. | | 400 | BIP000058 | Bad Request | Error while validating verification token | Erro ao validar token de verificação | | 400 | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Número de tentativas de validação de token de verificação excedido. | | 400 | BIP000060 | Bad Request | Verification token expired. | Token de verificação expirado. | | 400 | BIP000061 | Bad Request | Verification token validation failed. | Falha na validação do token de verificação. | | 400 | BIP000063 | Bad Request | Payment type is not collection slip. | Tipo de pagamento não é fatura de recolhimento. | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. | --- # Confirmar agendamento em lote de boleto bancário URL: /documentation/baas/cobranca/2fa_v2/agendamento/confirmar_agendamento_em_lote_de_boleto_bancario Este endpoint permite validar o token de autenticação de dois fatores (2FA) de um lote de agendamento de boletos bancários em `batch_payment_schedule_status` **`pending_2fa_approval`**. :::info Boleto bancário É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payment/schedule_bank_slip/ BATCH_PAYMENT_SCHEDULE_KEY /validate_token MÉTODO PATCH ### Request Path Params | Campo | Tipo | Descrição | Caracteres | | --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- | | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | | `batch_payment_schedule_key` * | uuid4 | Chave única de identificação do lote de agendamento. | 36 | Request Body: Validação de token do lote de agendamento ```json { "token": "329adf" } ``` ### Body Params | Campo | Tipo | Descrição | Caracteres | | ------- | ------ | ---------------------------------------------------------------------------------------------------------------- | ---------- | | `token` | string | Código de autenticação enviado ao aprovador de movimentações da conta | 6 | ## Response ### Success Response STATUS 200 Response Body: Lote de agendamento confirmado ```json { "batch_payment_schedule_key": "c4325104-d60b-44f3-aae4-49155564a2ea", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f", "total_amount": 1357.3, "batch_payment_schedule_status": "scheduled", "payment_type": "bank_slip" } ``` ### Response Body Params | Campo | Tipo | Descrição | | ----------------------- | ------ | --------- | | `batch_payment_schedule_key` * | uuid4 | Chave única de identificação do agendamento em lote. | | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `account_key` * | uuid4 | Chave da conta debitada. | | `total_amount` * | number | Soma dos valores dos itens do lote. | | `batch_payment_schedule_status` * | [enum](#enumeradores-batch_payment_schedule_status) | Status do lote de agendamento após a validação do token. | | `payment_type` * | string | Tipo do pagamento; para este fluxo, espera-se `bank_slip`. | ### Enumeradores batch_payment_schedule_status | Enumerador | Descrição | |---------------|---------------| | `pending_2fa_approval` | Pendente de aprovação 2FA | | `scheduled` | Agendado | | `rejected` | Rejeitado | | `error` | Erro ao agendar | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | | ----------- | --------- | ----------- | --------------------------------------------- | ---------------------------------------------------------------- | | 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação | | 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. | | 400 | BIP000058 | Bad Request | Error while validating verification token | Erro ao validar token de verificação | | 400 | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Número de tentativas de validação de token de verificação excedido. | | 400 | BIP000060 | Bad Request | Verification token expired. | Token de verificação expirado. | | 400 | BIP000061 | Bad Request | Verification token validation failed. | Falha na validação do token de verificação. | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. | | 404 | BIP000083 | Not Found | Batch payment not found by batch payment key. | Lote de pagamentos não encontrado pela chave do lote. | | 400 | BIP000085 | Bad Request | Batch payment status is not pending approval. | Status do lote de pagamentos não é de aprovação pendente. | | 400 | BIP000086 | Bad Request | A token is required for SMS or email validation. | Um token é necessário para validação via SMS ou email. | --- # Confirmar agendamento em lote de fatura de recolhimento URL: /documentation/baas/cobranca/2fa_v2/agendamento/confirmar_agendamento_em_lote_de_fatura_de_recolhimento Este endpoint permite validar o token de autenticação de dois fatores (2FA) de um lote de agendamento de faturas de recolhimento em `batch_payment_schedule_status` **`pending_2fa_approval`**. :::info Fatura de recolhimento Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payment/schedule_collection_slip/ BATCH_PAYMENT_SCHEDULE_KEY /validate_token MÉTODO PATCH ### Request Path Params | Campo | Tipo | Descrição | Caracteres | | --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- | | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | | `batch_payment_schedule_key` * | uuid4 | Chave única de identificação do lote de agendamento. | 36 | Request Body: Validação de token do lote de agendamento ```json { "token": "329adf" } ``` ### Body Params | Campo | Tipo | Descrição | Caracteres | | ------- | ------ | ---------------------------------------------------------------------------------------------------------------- | ---------- | | `token` | string | Código de autenticação enviado ao aprovador de movimentações da conta | 6 | ## Response ### Success Response STATUS 200 Response Body: Lote de agendamento confirmado ```json { "batch_payment_schedule_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a", "request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9", "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72", "total_amount": 1939.31, "batch_payment_schedule_status": "scheduled", "payment_type": "collection_slip" } ``` ### Response Body Params | Campo | Tipo | Descrição | | ----------------------- | ------ | --------- | | `batch_payment_schedule_key` * | uuid4 | Chave única de identificação do agendamento em lote. | | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `account_key` * | uuid4 | Chave da conta debitada. | | `total_amount` * | number | Soma dos valores dos itens do lote. | | `batch_payment_schedule_status` * | [enum](#enumeradores-batch_payment_schedule_status) | Status do lote de agendamento após a validação do token. | | `payment_type` * | string | Tipo do pagamento; para este fluxo, espera-se `collection_slip`. | ### Enumeradores batch_payment_schedule_status | Enumerador | Descrição | |---------------|---------------| | `pending_2fa_approval` | Pendente de aprovação 2FA | | `scheduled` | Agendado | | `rejected` | Rejeitado | | `error` | Erro ao agendar | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | | ----------- | --------- | ----------- | --------------------------------------------- | ---------------------------------------------------------------- | | 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação | | 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. | | 400 | BIP000058 | Bad Request | Error while validating verification token | Erro ao validar token de verificação | | 400 | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Número de tentativas de validação de token de verificação excedido. | | 400 | BIP000060 | Bad Request | Verification token expired. | Token de verificação expirado. | | 400 | BIP000061 | Bad Request | Verification token validation failed. | Falha na validação do token de verificação. | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. | | 404 | BIP000083 | Not Found | Batch payment not found by batch payment key. | Lote de pagamentos não encontrado pela chave do lote. | | 400 | BIP000085 | Bad Request | Batch payment status is not pending approval. | Status do lote de pagamentos não é de aprovação pendente. | | 400 | BIP000086 | Bad Request | A token is required for SMS or email validation. | Um token é necessário para validação via SMS ou email. | --- # Consultar lote de agendamento de pagamento URL: /documentation/baas/cobranca/2fa_v2/agendamento/consultar_lote_de_agendamento_de_pagamento Este endpoint retorna o resumo do lote de agendamento e a lista paginada dos agendamentos que o compõem (boletos bancários ou faturas de recolhimento). Para localizar `batch_payment_schedule_key`, utilize [Listar lotes de agendamento de pagamento](./listar_lotes_de_agendamento_de_pagamento.md). :::info Boleto bancário É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central. ::: :::info Fatura de recolhimento Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/ ACCOUNT_KEY /schedule/ BATCH_PAYMENT_SCHEDULE_KEY MÉTODO GET ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |-----------------------------|-------|----------------------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | | `batch_payment_schedule_key` * | uuid4 | Chave única de identificação do lote de agendamento. | 36 | ### Request Query String Params | Campo | Tipo | Descrição | |-------------|--------|-------------------------------------------------------------------------------| | `page` | string | Número da página dos itens em `payment_schedules.data`. 1 por padrão. | | `page_size` | string | Tamanho da página dos itens em `payment_schedules.data`. 30 por padrão e valor máximo. | ## Response ### Success Response STATUS 200 Response Body: Detalhes do lote de agendamento ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "total_scheduled": 10, "total_pending": 0, "total_error": 0, "total_amount": 1357.3, "batch_payment_schedule_status": "scheduled", "payment_schedules": { "pagination": { "current_page": 1, "rows_per_page": 30 }, "data": [ { "payment_schedule_key": "c4325104-d60b-44f3-aae4-49155564a2ea", "request_control_key": "b713b2f6-2f48-4d18-b0c9-7186e4edf189", "payer_name": "COOPERATIVA INDUSTRIAL MURILO", "payer_document_number": "00037025000160", "source_account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f", "paid_amount": 1050.1, "payment_date": "2024-04-03", "payment_type": "bank_slip", "bank_slip": { "bank_slip_key": "95080ffd-3ac5-48d7-b3fe-659e4aaba81a", "barcode": "00193967000009910000000003615574000000002417", "digitable_line": "00190000090361557400500000024174396700000991000", "payer_name": "COOPERATIVA TESTE", "payer_document_number": "00037025000160", "beneficiary_name": "TESTE EQUIPAMENTOS E SERVICOS LTDA", "beneficiary_trading_name": "TESTE EQUIPAMENTOS E SERVICOS LTDA", "beneficiary_document_number": "52069937000117", "beneficiary_bank_ispb": "00000000", "guarantor_name": null, "guarantor_document_number": null, "expiration_date": "2024-03-29", "max_payment_date": "2026-03-29", "partial_payment_indicator": "allowed", "registered_payment_amount": 9029.0, "nominal_amount": 9910.0, "total_amount": 10129.1, "rebate_amount": 0.0, "discount_amount": 0.0, "fine_amount": 0.0, "interest_amount": 219.1 }, "collection_slip": null, "payment_schedule_status": "scheduled", "error_reason": null } ] } } ``` ### Response Body Params | Campo | Tipo | Descrição | |--------------------------------|------------------------------------------|---------------------------------------------------------------| | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `total_scheduled` * | int | Quantidade de itens do lote agendados com sucesso. | | `total_pending` * | int | Quantidade de itens ainda pendentes no lote. | | `total_error` * | int | Quantidade de itens com erro no lote. | | `total_amount` * | number | Valor total do lote. | | `batch_payment_schedule_status` * | [enum](#enumeradores-batch_payment_schedule_status) | Status do lote de agendamento. | | `payment_schedules` * | [object](#objeto-payment_schedules) | Lista paginada dos agendamentos do lote. | ### Objeto payment_schedules | Campo | Tipo | Descrição | |----------------|------------------------------|----------------------------------------------------------| | `pagination` * | [object](#objeto-pagination) | Paginação da lista de agendamentos do lote. | | `data` * | array | Itens do lote (agendamentos individuais). | Cada elemento de `payment_schedules.data` contém: | Campo | Tipo | Descrição | |--------------------------|--------------------------------------|--------------------------------------------------------------------------------| | `payment_schedule_key` * | uuid4 | Chave única de identificação do agendamento. | | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente para o item do lote. | | `payer_name` * | string | Nome do pagador efetivo. | | `payer_document_number` *| string | Número de documento do pagador efetivo (CPF/CNPJ). | | `source_account_key` * | uuid4 | Chave da conta debitada. | | `paid_amount` * | number | Valor agendado para pagamento. | | `payment_date` * | string | Data do agendamento. | | `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. | | `bank_slip` | [object](#objeto-bank_slip) | Boleto bancário. Pode ser `null` quando `payment_type` for `collection_slip`. | | `collection_slip` | [object](#objeto-collection_slip) | Fatura de recolhimento. Pode ser `null` quando `payment_type` for `bank_slip`.| | `payment_schedule_status` * | [enum](#enumeradores-payment_schedule_status) | Status do agendamento. | | `error_reason` | string | Motivo do erro, quando aplicável; caso contrário `null`. | ### Objeto pagination | Campo | Tipo | Descrição | |------------------|------|-------------------------------------| | `current_page` * | int | Página atual retornada. | | `rows_per_page` *| int | Quantidade de registros por página. | ### Enumeradores payment_type | Enumerador | Descrição | |-------------------|------------------------| | `bank_slip` | Boleto bancário | | `collection_slip` | Fatura de recolhimento | ### Enumeradores payment_schedule_status | Enumerador | Descrição | |------------------------|------------------------------------------------------------------| | `pending_2fa_approval` | Agendamento pendente de autenticação de dois fatores (2FA) | | `scheduled` | Pagamento agendado com sucesso | | `executed` | O agendamento foi executado com sucesso e o pagamento foi gerado | | `rejected` | O agendamento foi rejeitado e nenhum pagamento foi gerado | | `canceled` | Agendamento cancelado | | `error` | Erro ao realizar o agendamento | ### Enumeradores batch_payment_schedule_status | Enumerador | Descrição | |------------------------|---------------------------| | `pending_2fa_approval` | Pendente de aprovação 2FA | | `scheduled` | Agendado | | `rejected` | Rejeitado | | `canceled` | Cancelado | | `error` | Erro ao agendar | ### Objeto bank_slip | Campo | Tipo | Descrição | |--------------------------------|-------------------------------------------------|-----------------------------------------------------| | `bank_slip_key` * | uuid4 | Chave única de identificação do boleto bancário. | | `barcode` * | string | Código de barras. | | `digitable_line` * | string | Linha digitável. | | `payer_name` * | string | Nome do pagador. | | `payer_document_number` * | string | Número de documento do pagador (CPF/CNPJ). | | `beneficiary_name` * | string | Nome do beneficiário. | | `beneficiary_trading_name` | string | Nome fantasia do beneficiário. | | `beneficiary_document_number` *| string | Número de documento do beneficiário (CPF/CNPJ). | | `beneficiary_bank_ispb` * | string | Código ispb do banco do beneficiário. | | `guarantor_name` | string | Nome do sacador avalista. | | `guarantor_document_number` | string | Número de documento do sacador avalista (CPF/CNPJ). | | `expiration_date` * | string | Data de vencimento. | | `max_payment_date` * | string | Data máxima de pagamento. | | `partial_payment_indicator` * | [enum](#enumeradores-partial_payment_indicator) | Indicador de pagamento parcial. | | `registered_payment_amount` | number | Valor total de pagamento registrado. | | `nominal_amount` * | number | Valor original. | | `total_amount` * | number | Valor total. | | `rebate_amount` * | number | Valor do abatimento. | | `discount_amount` * | number | Valor do desconto. | | `fine_amount` * | number | Valor da multa. | | `interest_amount` * | number | Valor dos juros. | ### Enumeradores partial_payment_indicator | Enumerador | Descrição | |---------------|---------------| | `allowed` | Permitido | | `not_allowed` | Não permitido | ### Objeto collection_slip | Campo | Tipo | Descrição | |--------------------------------|--------|---------------------------------------------| | `barcode` * | string | Código de barras. | | `digitable_line` * | string | Linha digitável. | | `collection_name` * | string | Nome do convênio. | | `collection_document_number` * | string | Número de documento do convênio (CPF/CNPJ). | | `expiration_date` * | string | Data de vencimento. | | `total_amount` * | number | Valor total. | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|-------------|-----------------------------------------------------------------|----------------------------------------------------------------| | 400 | BIP000027 | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. | | 404 | BIP000083 | Not Found | Batch payment not found by batch payment key. | Lote de pagamentos não encontrado pela chave do lote. | --- # Listar lotes de agendamento de pagamento URL: /documentation/baas/cobranca/2fa_v2/agendamento/listar_lotes_de_agendamento_de_pagamento Este endpoint retorna os lotes de agendamento de pagamentos de boletos bancários e faturas de recolhimento associados à conta, com suporte a filtros e paginação. :::info Boleto bancário É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central. ::: :::info Fatura de recolhimento Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/ ACCOUNT_KEY /schedules MÉTODO GET ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | ### Request Query String Params | Campo | Tipo | Descrição | |--------------------------------|-------------|-----------------------------------| | `request_control_key` | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `batch_payment_schedule_key` | uuid4 | Chave única de identificação do lote de agendamento. | | `payment_type` | [enum](#enumeradores-payment_type) | Tipo do pagamento do lote. | | `batch_payment_schedule_status`| [enum](#enumeradores-batch_payment_schedule_status) | Status do lote de agendamento. | | `date_from` | string | Data inicial. Formato `YYYY-MM-DD`. | | `date_to` | string | Data final. Formato `YYYY-MM-DD`. | | `page` | string | Número da página requisitada. 1 por padrão. | | `page_size` | string | Tamanho da página requisitada na consulta. 30 por padrão e valor máximo. | ### Enumeradores payment_type | Enumerador | Tipo | Descrição | |-------------------|--------|------------------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | ### Enumeradores batch_payment_schedule_status | Enumerador | Descrição | |------------------------|------------------------------------| | `pending_2fa_approval` | Pendente de aprovação 2FA | | `scheduled` | Agendado | | `rejected` | Rejeitado | | `canceled` | Cancelado | | `error` | Erro ao agendar | ## Response ### Success Response STATUS 200 Response Body: Listagem de lotes de agendamento ```json { "pagination": { "current_page": 1, "rows_per_page": 30 }, "data": [ { "batch_payment_schedule_key": "a3214093-e51c-55e2-b5d3-60244475b3fb", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "batch_payment_schedule_status": "scheduled", "payment_type": "bank_slip", "total_scheduled": 10, "total_pending": 0, "total_error": 0, "total_amount": 1357.3 } ] } ``` ### Response Body Params | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------| | `pagination` * | [object](#objeto-pagination) | Informações de paginação da consulta. | | `data` * | array | Lista de lotes encontrados. | Cada elemento de `data` contém: | Campo | Tipo | Descrição | |---------------------------------|---------|-----------------------------------| | `batch_payment_schedule_key` * | uuid4 | Chave única de identificação do lote de agendamento. | | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `batch_payment_schedule_status` * | [enum](#enumeradores-batch_payment_schedule_status-1) | Status atual do lote de agendamento. | | `payment_type` * | [enum](#enumeradores-payment_type-1) | Tipo do pagamento do lote. | | `total_scheduled` * | int | Quantidade de itens do lote agendados com sucesso. | | `total_pending` * | int | Quantidade de itens ainda pendentes no lote. | | `total_error` * | int | Quantidade de itens com erro no lote. | | `total_amount` * | number | Valor total do lote. | ### Objeto pagination | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------| | `current_page` * | int | Página atual retornada. | | `rows_per_page` * | int | Quantidade de registros por página. | ### Enumeradores payment_type | Enumerador | Descrição | |-------------------|------------------------| | `bank_slip` | Boleto bancário | | `collection_slip` | Fatura de recolhimento | ### Enumeradores batch_payment_schedule_status | Enumerador | Descrição | |------------------------|---------------------------| | `pending_2fa_approval` | Pendente de aprovação 2FA | | `scheduled` | Agendado | | `rejected` | Rejeitado | | `canceled` | Cancelado | | `error` | Erro ao agendar | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 400 | BIP000026 | Bad Request | Invalid payment date format. The correct format is YYYY-MM-DD. | Formato de data de pagamento inválido. O formato correto é YYYY-MM-DD. | | 400 | BIP000027 | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. | | 400 | BIP000047 | Bad Request | Invalid payment type. | Tipo de pagamento inválido. | --- # Reenviar Token Autenticação de Dois Fatores de Agendamento de Boleto Bancário URL: /documentation/baas/cobranca/2fa_v2/agendamento/reenviar_token_de_agendamento_boleto_bancario Este endpoint permite realizar o reenvio do token de autenticação de agendamento de Boletos Bancários. :::info Boleto bancário É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central. ::: ## Request ENDPOINT /account/ ACCOUNT_KEY /payment_schedule/ PAYMENT_SCHEDULE_KEY /bank_slip/resend_token MÉTODO PATCH ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | | `payment_schedule_key` * | uuid4 | Chave única de identificação do agendamento. | 36 | ### Body Params | Campo | Tipo | Descrição | Caracteres | |----------------|--------|-------------------------------------------------------------------------------------------|------------| | `contact_type` | enumerator | Forma de envio do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** | :::info Informação Caso não seja enviado um `contact_type`, o token será enviado da forma solicitada originalmente. ::: | Enumerador | Descrição | |------------|---------------------------------------------------| | **sms** | Envio por Mensagem de Texto para telefone celular | | **email** | Envio por correio eletrônico | ## Response ### Success Response STATUS 200 Response Body: Token reenviado com sucesso ```json { "payment_schedule_key":"c4325104-d60b-44f3-aae4-49155564a2ea", "request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189", "payer_name":"COOPERATIVA INDUSTRIAL MURILO", "payer_document_number":"00037025000160", "source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f", "paid_amount":1050.1, "payment_date":"2024-04-03", "payment_type":"bank_slip", "bank_slip": { "bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a", "barcode":"00193967000009910000000003615574000000002417", "digitable_line":"00190000090361557400500000024174396700000991000", "payer_name":"COOPERATIVA TESTE", "payer_document_number":"00037025000160", "beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA", "beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA", "beneficiary_document_number":"52069937000117", "beneficiary_bank_ispb":"00000000", "guarantor_name":null, "guarantor_document_number":null, "expiration_date":"2024-03-29", "max_payment_data": "2026-03-29", "partial_payment_indicator":"allowed", "registered_payment_amount":9029.0, "nominal_amount":9910.0, "total_amount":10129.1, "rebate_amount":0.0, "discount_amount":0.0, "fine_amount":0.0, "interest_amount":219.1 }, "collection_slip":null, "payment_schedule_status":"pending_2fa_approval" } ``` ### Response Body Params | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------------------------| | `payment_key` * | uuid4 | Chave única de identificação do pagamento. | | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente. | | `payer_name` * | string | Nome do pagador efetivo. | | `payer_document_number` * | string | Número documento do pagador efetivo (CPF/CNPJ). | | `source_account_key` * | uuid4 | Chave da conta debitada. | | `transaction_key` * | uuid4 | Chave da transação do pagamento. | | `transaction_revert_key` | uuid4 | Chave da transação de reversão do pagamento. | | `paid_amount` * | number | Valor pago efetivamente. | | `payment_date` * | string | Data do pagamento. | | `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. | | `bank_slip` | [object](#objeto-bank_slip) | Boleto bancário. | | `collection_slip` | object | Fatura de recolhimento. | | `payment_schedule_status` * | [enum](#enumeradores-payment_schedule_status) | Status do agendamento. | ### Enumeradores payment_type | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | :::danger Aviso O enumerador `collection_slip` não se aplica para o fluxo de boletos bancários, assim como o objeto collection_slip que sempre será nulo. ::: ### Enumeradores payment_schedule_status | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `pending_2fa_approval` | string | pendente de aprovação de dois fatores | ### Objeto bank_slip | Campo | Tipo | Descrição | |-----------------------------------|---------|-----------------------------------| | `barcode` * | string | Código de barras. | | `digitable_line` * | string | Linha digitável. | | `payer_name` * | string | Nome do pagador.| | `payer_document_number` * | string | Número de documento do pagador (CPF/CNPJ). | | `beneficiary_name` * | string | Nome do beneficiário. | | `beneficiary_trading_name` | string | Nome fantasia do beneficiário. | | `beneficiary_document_number` * | string | Número de documento do beneficiário (CPF/CNPJ). | | `beneficiary_bank_ispb` * | string | Código ispb do banco do beneficiário. | | `guarantor_name` | string | Nome do sacador avalista. | | `guarantor_document_number` | string | Número de documento do sacador avalista (CPF/CNPJ). | | `expiration_date` * | string | Data de vencimento. | | `max_payment_date` * | string | Data máxima de pagamento. | | `partial_payment_indicator` * | [enum](#enumeradores-partial_payment_indicator) | Indicador de pagamento parcial. | | `registered_payment_amount` | string | Valor total de pagamento registrado. | | `nominal_amount` * | number | Valor original. | | `total_amount` * | number | Valor total. | | `rebate_amount` * | number | Valor do abatimento. | | `discount_amount` * | number | Valor do desconto. | | `fine_amount` * | number | Valor da multa. | | `interest_amount` * | number | Valor do juros. | ### Enumeradores partial_payment_indicator | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `allowed` | string | Permitido | | `not_allowed` | string | Não permitido | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação | | 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. | | 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. | | 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. | | 400 | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. | | 404 | BIP000056 | Not Found | Payment not found. | Pagamento não encontrado. | | 400 | BIP000057 | Bad Request | Payment status is not pending approval. | Status de pagamento não é de aprovação pendente. | | 400 | BIP000062 | Bad Request | Payment type is not bank slip. | Tipo de pagamento não é boleto. | | 400 | BIP000064 | Bad Request | Error resending verification token | Erro ao reenviar token de verificação | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. | --- # Reenviar Token Autenticação de Dois Fatores de Agendamento de Fatura de Recolhimento URL: /documentation/baas/cobranca/2fa_v2/agendamento/reenviar_token_de_agendamento_de_fatura_de_recolhimento Este endpoint permite realizar o reenvio do token de autenticação de agendamento de Faturas de Recolhimento. :::info Fatura de recolhimento Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgão públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta. ::: ## Request ENDPOINT /account/ ACCOUNT_KEY /payment_schedule/ PAYMENT_SCHEDULE_KEY /collection_slip/resend_token MÉTODO PATCH ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | | `payment_schedule_key` * | uuid4 | Chave única de identificação do agendamento. | 36 | ## Response ### Success Response STATUS 200 Response Body: Token reenviado com sucesso ```json { "payment_schedule_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a", "request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9", "payer_name": "COOPERATIVA INDUSTRIAL MURILO", "payer_document_number": "62069937000118", "source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72", "paid_amount": 1389.21, "payment_date": "2024-04-30", "payment_type": "collection_slip", "bank_slip": null, "collection_slip": { "barcode": null, "digitable_line": "836200000138892100450006762142420244046000010192", "collection_name": "CIA ULTRAGAZ SA-COD", "collection_document_number": "00394460005887", "expiration_date": "2024-04-15", "total_amount": 1389.21 }, "payment_schedule_status": "pending_2fa_approval" } ``` ### Response Body Params | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------| | `payment_key` * | uuid4 | Chave única de identificação do pagamento. | | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente. | | `payer_name` * | string | Nome do pagador efetivo.| | `payer_document_number` * | string | Número de documento do pagador efetivo (CPF/CNPJ). | | `source_account_key` * | uuid4 | Chave da conta debitada. | | `transaction_key` * | uuid4 | Chave da transação do pagamento. | | `transaction_revert_key` | uuid4 | Chave da transação de reversão do pagamento. | | `paid_amount` * | number | Valor pago efetivamente. | | `payment_date` * | string | Data do pagamento. | | `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. | | `bank_slip` | object | Boleto bancário. | | `collection_slip` | [object](#objeto-collection_slip) | Fatura de recolhimento. | | `payment_schedule_status` * | [enum](#enumeradores-payment_schedule_status) | Status do pagamento. | ### Enumeradores payment_type | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | :::danger Aviso O enumerador `bank_slip` não se aplica para o fluxo de faturas de recolhimento, assim como o objeto bank_slip que sempre será nulo. ::: ### Enumeradores payment_schedule_status | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `pending_2fa_approval` | string | pendente de aprovação de dois fatores | ### Objeto collection_slip | Campo | Tipo | Descrição | |-----------------------------------|---------|-----------------------------------| | `barcode` | string | Código de barras. | | `digitable_line` | string | Linha digitável. | | `collection_name` * | string | Nome do convênio.| | `collection_document_number` | string | Número de documento do convênio (CPF/CNPJ).| | `expiration_date` * | string | Data de vencimento. | | `total_amount` * | number | Valor total. | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação | | 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. | | 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. | | 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. | | 400 | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. | | 404 | BIP000056 | Not Found | Payment not found. | Pagamento não encontrado. | | 400 | BIP000057 | Bad Request | Payment status is not pending approval. | Status de pagamento não é de aprovação pendente. | | 400 | BIP000063 | Bad Request | Payment type is not collection slip. | Tipo de pagamento não é fatura de recolhimento. | | 400 | BIP000064 | Bad Request | Error resending verification token | Erro ao reenviar token de verificação | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. | --- # Reenviar token de autenticação de dois fatores de agendamento em lote de boleto bancário URL: /documentation/baas/cobranca/2fa_v2/agendamento/reenviar_token_de_agendamento_em_lote_de_boleto_bancario Este endpoint permite **reenviar** o token de autenticação de dois fatores (2FA) para um lote de agendamento de boletos bancários que esteja em `batch_payment_schedule_status` **`pending_2fa_approval`**. :::info Boleto bancário É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payment/schedule_bank_slip/ BATCH_PAYMENT_SCHEDULE_KEY /resend_token MÉTODO PATCH ### Request Path Params | Campo | Tipo | Descrição | Caracteres | | --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- | | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | | `batch_payment_schedule_key` * | uuid4 | Chave única de identificação do lote de agendamento. | 36 | ### Request Body Request Body (opcional) ```json { "contact_type": "sms" } ``` ### Body Params | Campo | Tipo | Descrição | Caracteres | | -------------- | ---------- | --------------------------------------- | ------------------------------------------------------- | | `contact_type` | enumerator | Forma de envio do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** | :::info Informação Caso não seja enviado um `contact_type`, o token será enviado da forma solicitada originalmente no agendamento do lote (`tfa_info.contact_type`). ::: ### Enumerador contact_type | Enumerador | Descrição | | ---------- | ------------------------------------------------- | | **sms** | Envio por mensagem de texto para telefone celular | | **email** | Envio por correio eletrônico | ## Response ### Success Response STATUS 200 Response Body: Token reenviado com sucesso ```json { "batch_payment_schedule_key": "c4325104-d60b-44f3-aae4-49155564a2ea", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f", "total_amount": 1357.3, "batch_payment_schedule_status": "pending_2fa_approval", "payment_type": "bank_slip" } ``` ### Response Body Params | Campo | Tipo | Descrição | | ----------------------- | ------ | --------- | | `batch_payment_schedule_key` * | uuid4 | Chave única de identificação do agendamento em lote. | | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `account_key` * | uuid4 | Chave da conta debitada. | | `total_amount` * | number | Soma dos valores dos itens do lote. | | `batch_payment_schedule_status` * | string | Após o reenvio, o lote permanece aguardando validação do token (`pending_2fa_approval`). | | `payment_type` * | string | Tipo do pagamento; para este fluxo, espera-se `bank_slip`. | Em seguida, utilize [Confirmar agendamento em lote de boleto bancário](./confirmar_agendamento_em_lote_de_boleto_bancario.md) para concluir o 2FA. ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | | ----------- | --------- | ----------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação | | 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. | | 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. | | 400 | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Número de tentativas de validação de token de verificação excedido. | | 400 | BIP000064 | Bad Request | Error resending verification token | Erro ao reenviar token de verificação | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. | | 404 | BIP000083 | Not Found | Batch payment not found by batch payment key. | Lote de pagamentos não encontrado pela chave do lote. | | 400 | BIP000085 | Bad Request | Batch payment status is not pending approval. | Status do lote de pagamentos não é de aprovação pendente. | --- # Reenviar token de autenticação de dois fatores de agendamento em lote de fatura de recolhimento URL: /documentation/baas/cobranca/2fa_v2/agendamento/reenviar_token_de_agendamento_em_lote_de_fatura_de_recolhimento Este endpoint permite **reenviar** o token de autenticação de dois fatores (2FA) para um lote de agendamento de faturas de recolhimento que esteja em `batch_payment_schedule_status` **`pending_2fa_approval`**. :::info Fatura de recolhimento Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payment/schedule_collection_slip/ BATCH_PAYMENT_SCHEDULE_KEY /resend_token MÉTODO PATCH ### Request Path Params | Campo | Tipo | Descrição | Caracteres | | --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- | | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | | `batch_payment_schedule_key` * | uuid4 | Chave única de identificação do lote de agendamento. | 36 | ### Request Body Request Body (opcional) ```json { "contact_type": "sms" } ``` ### Body Params | Campo | Tipo | Descrição | Caracteres | | -------------- | ---------- | --------------------------------------- | ------------------------------------------------------- | | `contact_type` | enumerator | Forma de envio do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** | :::info Informação Caso não seja enviado um `contact_type`, o token será enviado da forma solicitada originalmente no agendamento do lote (`tfa_info.contact_type`). ::: ### Enumerador contact_type | Enumerador | Descrição | | ---------- | ------------------------------------------------- | | **sms** | Envio por mensagem de texto para telefone celular | | **email** | Envio por correio eletrônico | ## Response ### Success Response STATUS 200 Response Body: Token reenviado com sucesso ```json { "batch_payment_schedule_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a", "request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9", "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72", "total_amount": 1939.31, "batch_payment_schedule_status": "pending_2fa_approval", "payment_type": "collection_slip" } ``` ### Response Body Params | Campo | Tipo | Descrição | | ----------------------- | ------ | --------- | | `batch_payment_schedule_key` * | uuid4 | Chave única de identificação do agendamento em lote. | | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `account_key` * | uuid4 | Chave da conta debitada. | | `total_amount` * | number | Soma dos valores dos itens do lote. | | `batch_payment_schedule_status` * | string | Após o reenvio, o lote permanece aguardando validação do token (`pending_2fa_approval`). | | `payment_type` * | string | Tipo do pagamento; para este fluxo, espera-se `collection_slip`. | Em seguida, utilize [Confirmar agendamento em lote de fatura de recolhimento](./confirmar_agendamento_em_lote_de_fatura_de_recolhimento.md) para concluir o 2FA. ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | | ----------- | --------- | ----------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação | | 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. | | 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. | | 400 | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Número de tentativas de validação de token de verificação excedido. | | 400 | BIP000064 | Bad Request | Error resending verification token | Erro ao reenviar token de verificação | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. | | 404 | BIP000083 | Not Found | Batch payment not found by batch payment key. | Lote de pagamentos não encontrado pela chave do lote. | | 400 | BIP000085 | Bad Request | Batch payment status is not pending approval. | Status do lote de pagamentos não é de aprovação pendente. | --- # Solicitar Agendamento de Pagamento de Boleto Bancário com Autenticação de Dois Fatores (2FA) URL: /documentation/baas/cobranca/2fa_v2/agendamento/solicitar_agendamento_de_boleto_bancario Este endpoint permite realizar a solicitação de agendamento de pagamento de boletos bancários. A solicitação deve ser realizado após a consulta, utilizando as informações retornadas para garantir o funcionamento correto do fluxo, evitando falhas durante o processo. :::info Boleto bancário É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central. ::: ## Request ENDPOINT /account/ ACCOUNT_KEY /payment_schedule/bank_slip MÉTODO POST ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | Request Body: Solicitação de agendamento com linha digitável ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "digitable_line": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8, "payment_date": "2024-03-30", "tfa_info": { "approver_document_number": "98765432100", "contact_type": "email" } } ``` Request Body: Solicitação de agendamento com código de barras ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "barcode": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8, "payment_date": "2024-03-30", "tfa_info": { "approver_document_number": "98765432100", "contact_type": "email" } } ``` ### Body Params | Campo | Tipo | Descrição | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente. | | `barcode` | string | Código de barras. | | `digitable_line` | string | Linha digitável. | | `payment_amount` * | number | Valor a ser pago. | | `payment_date` * | string | Data do agendamento. | | `tfa_info` * | [object](#objeto-tfa_info) | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato. | :::danger Aviso O `payment_amount` deve sempre igual ao `total_amount` retornado na consulta do boleto bancário caso o pagamento parcial não seja permitido para o boleto bancário. Para títulos em que o pagamento parcial é permitido, o cliente pode escolher o `payment_amount`, desde que a soma do mesmo com o `registered_payment_amount` do boleto bancário não seja superior que o `total_amount`. ::: ### Objeto tfa_info | Campo | Tipo | Descrição | |-----------------------------|---------|-----------------------------------| | `approver_document_number`* | string | Número de documento da pessoa aprovadora da conta. | | `contact_type`* | enumerator | Forma de envio do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** | | Enumerador | Descrição | |------------|---------------------------------------------------| | **sms** | Envio por Mensagem de Texto para telefone celular | | **email** | Envio por correio eletrônico | ## Response ### Success Response STATUS 201 Response Body: Agendamento pendente de aprovação de dois fatores ```json { "payment_schedule_key":"c4325104-d60b-44f3-aae4-49155564a2ea", "request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189", "payer_name":"COOPERATIVA INDUSTRIAL MURILO", "payer_document_number":"00037025000160", "source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f", "paid_amount":1050.1, "payment_date":"2024-04-03", "payment_type":"bank_slip", "bank_slip": { "barcode":"00193967000009910000000003615574000000002417", "digitable_line":"00190000090361557400500000024174396700000991000", "payer_name":"COOPERATIVA TESTE", "payer_document_number":"00037025000160", "beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA", "beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA", "beneficiary_document_number":"52069937000117", "beneficiary_bank_ispb":"00000000", "guarantor_name":null, "guarantor_document_number":null, "expiration_date":"2024-03-29", "max_payment_data": "2026-03-29", "partial_payment_indicator":"allowed", "registered_payment_amount":9029.0, "nominal_amount":9910.0, "total_amount":10129.1, "rebate_amount":0.0, "discount_amount":0.0, "fine_amount":0.0, "interest_amount":219.1 }, "collection_slip":null, "payment_schedule_status":"pending_2fa_approval" } ``` ### Response Body Params | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------------------------| | `payment_key` * | uuid4 | Chave única de identificação do pagamento. | | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente. | | `payer_name` * | string | Nome do pagador efetivo. | | `payer_document_number` * | string | Número do documento do pagador efetivo (CPF/CNPJ). | | `source_account_key` * | uuid4 | Chave da conta debitada. | | `transaction_key` * | uuid4 | Chave da transação do pagamento. | | `transaction_revert_key` | uuid4 | Chave da transação de reversão do pagamento. | | `paid_amount` * | number | Valor pago efetivamente. | | `payment_date` * | string | Data do agendamento. | | `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. | | `bank_slip` | [object](#objeto-bank_slip) | Boleto bancário. | | `collection_slip` | object | Fatura de recolhimento. | | `payment_schedule_status` * | [enum](#enumeradores-payment_schedule_status) | Status do agendamento. | ### Enumeradores payment_type | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | :::danger Aviso O enumerador `collection_slip` não se aplica para o fluxo de boletos bancários, assim como o objeto collection_slip que sempre será nulo. ::: ### Enumeradores payment_schedule_status | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `pending_2fa_approval` | string | pendente de aprovação de dois fatores | ### Objeto bank_slip | Campo | Tipo | Descrição | |-----------------------------------|---------|-----------------------------------| | `barcode` * | string | Código de barras. | | `digitable_line` * | string | Linha digitável. | | `payer_name` * | string | Nome do pagador.| | `payer_document_number` * | string | Número do documento do pagador (CPF/CNPJ). | | `beneficiary_name` * | string | Nome do beneficiário. | | `beneficiary_trading_name` | string | Nome fantasia do beneficiário. | | `beneficiary_document_number` * | string | Número do documento do beneficiário (CPF/CNPJ). | | `beneficiary_bank_ispb` * | string | Código ispb do banco do beneficiário. | | `guarantor_name` | string | Nome do sacador avalista. | | `guarantor_document_number` | string | Número do documento do sacador avalista (CPF/CNPJ). | | `expiration_date` * | string | Data de vencimento. | | `max_payment_date` * | string | Data máxima de pagamento. | | `partial_payment_indicator` * | [enum](#enumeradores-partial_payment_indicator) | Indicador de pagamento parcial. | | `registered_payment_amount` | string | Valor total de pagamento registrado. | | `nominal_amount` * | number | Valor original. | | `total_amount` * | number | Valor total. | | `rebate_amount` * | number | Valor do abatimento. | | `discount_amount` * | number | Valor do desconto. | | `fine_amount` * | number | Valor da multa. | | `interest_amount` * | number | Valor do juros. | ### Enumeradores partial_payment_indicator | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `allowed` | string | Permitido | | `not_allowed` | string | Não permitido | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 400 | BIP000001 | Bad Request | The barcode or digitable line must have 44 or 47 characters. | O código de barras ou linha digitável deve ter 44 ou 47 caracteres. | | 400 | BIP000002 | Bad Request | The bill sent does not correspond to a bank slip. | A conta enviado não corresponde a um boleto bancário. | | 400 | BIP000003 | Bad Request | The digitable line sent is invalid. | A linha digitável enviada é inválida. | | 404 | BIP000004 | Not Found | The bank slip was not found. | O boleto não foi encontrado. | | 400 | BIP000005 | Bad Request | It was not possible to consult the bank slip at this time. Please try again in a few minutes. | Não foi possível consultar o boleto neste momento. Por favor, tente novamente em alguns minutos. | | 400 | BIP000006 | Bad Request | Bank slip already written off | Boleto já baixado | | 400 | BIP000007 | Bad Request | Bank slip blocked for payment | Boleto bloqueado para pagamento | | 400 | BIP000008 | Bad Request | Bank slip already paid | Boleto já pago | | 400 | BIP000009 | Bad Request | Invalid bank slip. Please consult issuing bank | Boleto inválido. Favor consultar banco emissor | | 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação | | 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. | | 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. | | 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. | | 400 | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. | | 400 | BIP000015 | Bad Request | Payment date is greater than the maximum payment date. | A data de pagamento é maior que a data máxima de pagamento. | | 400 | BIP000016 | Bad Request | Payment date is smaller than the calculation date. | A data de pagamento é menor que a data de cálculo. | | 400 | BIP000017 | Bad Request | Invalid payment amount. | Valor de pagamento inválido. | | 400 | BIP000018 | Bad Request | Partial payment is not allowed. | Pagamento parcial não é permitido. | | 400 | BIP000019 | Bad Request | The payment amount is greater than the available amount. | O valor do pagamento é maior que o valor disponível. | | 400 | BIP000020 | Bad Request | All partial payments for this bank slip have already been made. | Todos os pagamentos parciais deste boleto já foram realizados. | | 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. | | 403 | BIP000052 | Forbidden | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta | | 400 | BIP000053 | Bad Request | Error getting approver data | Erro ao obter dados do aprovador | | 400 | BIP000054 | Bad Request | TFA info required | Informações de TFA necessárias | | 400 | BIP000055 | Bad Request | Error sending verification token | Erro ao enviar token de verificação | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. | ## Ambiente de Sandbox Em nosso ambiente de sandbox, disponibilizamos linhas digitáveis mockadas para a simulação de pagamentos bem-sucedidos e testes de cenários de erro. | Linha digitável | |-----------------| | 00190000090361557400500000024174396700000991000 | | 00190000090282802601919212747174596760001294161 | | 23793390014000000455277000249001596900000103995 | | 75691434020137513680900001040013196770002417240 | | 21390001171200000570700168167484796770000148206 | | 34191090083273252027893634770007296690012513600 | | 42297048060005815702500130494123896770000239491 | | 07090010287045349010776686070590896770001160123 | | 74891123702849020818918378871083196690000050000 | | 23792374119000209350986000372408496610000122810 | --- # Solicitar Agendamento de Pagamento de Facutara de Recolhimento com Autenticação de Dois Fatores (2FA) URL: /documentation/baas/cobranca/2fa_v2/agendamento/solicitar_agendamento_de_pagamento_de_fatura_de_recolhimento Este endpoint permite realizar a solicitação de agendamento de pagamento de faturas de recolhimento com autenticação de dois fatores. A solicitação deve ser realizado após a consulta, utilizando as informações retornadas para garantir o funcionamento correto do fluxo, evitando falhas durante o processo. :::info Fatura de recolhimento Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgão públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta. ::: ## Request ENDPOINT /account/ ACCOUNT_KEY /payment_schedule/collection_slip MÉTODO POST ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | Request Body: Solicitação de com linha digitável ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "digitable_line": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8, "payment_date": "2024-03-30", "tfa_info": { "approver_document_number": "98765432100", "contact_type": "email" } } ``` Request Body: Solicitação de agendamento com código de barras ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "barcode": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8, "payment_date": "2024-03-30", "tfa_info": { "approver_document_number": "98765432100", "contact_type": "email" } } ``` ### Body Params | Campo | Tipo | Descrição | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente. | | `barcode` | string | Código de barras. | | `digitable_line` | string | Linha digitável. | | `payment_amount` * | number | Valor a ser pago. | | `tfa_info` * | [object](#objeto-tfa_info) | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato. | :::danger Aviso O `payment_amount` deve sempre igual ao `total_amount` retornado na consulta do boleto bancário. ::: ### Objeto tfa_info | Campo | Tipo | Descrição | |-----------------------------|---------|-----------------------------------| | `approver_document_number`* | string | Número de documento da pessoa aprovadora da conta (CPF/CNPJ). | | `contact_type`* | enumerator | Forma de envio do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** | | Enumerador | Descrição | |------------|---------------------------------------------------| | **sms** | Envio por Mensagem de Texto para telefone celular | | **email** | Envio por correio eletrônico | ## Response ### Success Response STATUS 201 Response Body: Agendamento pendente de aprovação de dois fatores ```json { "payment_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a", "request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9", "payer_name": "COOPERATIVA INDUSTRIAL MURILO", "payer_document_number": "62069937000118", "source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72", "paid_amount": 1389.21, "payment_date": "2024-04-30", "payment_type": "collection_slip", "bank_slip": null, "collection_slip": { "barcode": null, "digitable_line": "836200000138892100450006762142420244046000010192", "collection_name": "CIA ULTRAGAZ SA-COD", "collection_document_number": "00394460005887", "expiration_date": "2024-04-15", "total_amount": 1389.21 }, "payment_schedule_status": "pending_2fa_approval" } ``` ### Response Body Params | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------------------------| | `payment_key` * | uuid4 | Chave única de identificação do pagamento. | | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente. | | `payer_name` * | string | Nome do pagador efetivo. | | `payer_document_number` * | string | Documento do pagador efetivo (CPF/CNPJ). | | `source_account_key` * | uuid4 | Chave da conta debitada. | | `transaction_key` * | uuid4 | Chave da transação do pagamento. | | `transaction_revert_key` | uuid4 | Chave da transação de reversão do pagamento. | | `paid_amount` * | number | Valor pago efetivamente. | | `payment_date` * | string | Data do agendamento. | | `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. | | `bank_slip` | object | Boleto bancário. | | `collection_slip` | [object](#objeto-collection_slip) | Fatura de recolhimento. | | `payment_schedule_status` * | [enum](#enumeradores-payment_schedule_status) | Status do agendamento. | ### Enumeradores payment_type | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | :::danger Aviso O enumerador `bank_slip` não se aplica para o fluxo de faturas de recolhimento, assim como o objeto bank_slip que sempre será nulo. ::: ### Enumeradores payment_schedule_status | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `pending_2fa_approval` | string | pendente de aprovação de dois fatores | ### Objeto collection_slip | Campo | Tipo | Descrição | |-----------------------------------|---------|-----------------------------------| | `barcode` | string | Código de barras. | | `digitable_line` | string | Linha digitável. | | `collection_name` * | string | Nome do convênio.| | `collection_document_number` | string | Número de documento do convênio (CPF/CNPJ).| | `expiration_date` * | string | Data de vencimento. | | `total_amount` * | number | Valor total. | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 400 | BIP000032 | Bad Request | The bill sent does not correspond to a collection slip. | A conta enviada não corresponde a uma fatura de recolhimento. | | 400 | BIP000033 | Bad Request | The barcode or digitable line of the collection slip must have 44 or 48 characters. | O código de barras ou linha digitável da fatura de recolhimento deve ter 44 ou 48 caracteres. | | 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação | | 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. | | 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. | | 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. | | 400 | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. | | 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. | | 400 | BIP000028 | Bad Request | The source account has blocked balance. Payment cannot be made. | A conta de origem possui saldo em conta bloqueado. Pagamento não pode ser realizado. | | 400 | BIP000034 | Bad Request | Collection slip already paid. | Fatura de recolhimento já paga. | | 400 | BIP000035 | Bad Request | Covenant slip invalid barcode. | Código de barras da fatura de recolhimento inválido. | | 400 | BIP000036 | Bad Request | Covenant slip overdue. | Fatura de recolhimento vencida. | | 400 | BIP000037 | Bad Request | Error in collection slip consultation. | Erro na consulta da fatura de recolhimento. | | 400 | BIP000038 | Bad Request | Outside of covenant payment hours. | Fora do horário de pagamento do convênio. | | 400 | BIP000039 | Bad Request | Collection slip not accepted. | Fatura de recolhimento não aceita. | | 400 | BIP000040 | Bad Request | Minimum advance not reached. | Mínimo de dias de adiantamento não atingido. | | 400 | BIP000041 | Bad Request | Max payment amount exceeded. | Valor máximo de pagamento excedido. | | 400 | BIP000044 | Bad Request | It was not possible to pay the collection slip at this time. Please verify your information and, if necessary, contact us for assistance. | Não foi possível pagar a fatura de recolhimento neste momento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para assistência. | | 403 | BIP000052 | Forbidden | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta | | 400 | BIP000053 | Bad Request | Error getting approver data | Erro ao obter dados do aprovador | | 400 | BIP000054 | Bad Request | TFA info required | Informações de TFA necessárias | | 400 | BIP000055 | Bad Request | Error sending verification token | Erro ao enviar token de verificação | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. | ## Ambiente de Sandbox Em nosso ambiente de sandbox, disponibilizamos linhas digitáveis mockadas para a simulação de pagamentos bem-sucedidos e testes de cenários de erro. | Linha digitável | |---| | 828300000007411100972013905080001546763201900028 | | 838000000009235700481007241345219112001474229880 | | 848000000006308600802021201071261517689002201070 | | 858200000015000000643025703477209504800448091020 | | 858500000037350000643217212883260006147448091022 | --- # Solicitar agendamento em lote de boleto bancário com autenticação de dois fatores (2FA) URL: /documentation/baas/cobranca/2fa_v2/agendamento/solicitar_agendamento_em_lote_de_boleto_bancario Este endpoint permite solicitar o **agendamento em lote** de boletos bancários em uma única requisição, com autenticação de dois fatores quando aplicável. :::info Boleto bancário É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments_schedule/batch_bank_slip MÉTODO POST ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | Request Body: Agendamento em lote de boletos bancários ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "bank_slip_payment_schedules": [ { "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd", "digitable_line": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8, "payment_date": "2026-04-10" }, { "request_control_key": "d8a26b54-323a-4924-0aed-e4fe6e4e4c0e", "barcode": "00190000090361557400500000024174396700000991000", "payment_amount": 200.5, "payment_date": "2026-04-15" } ], "tfa_info": { "approver_document_number": "98765432100", "contact_type": "email" } } ``` ### Body Params | Campo | Tipo | Descrição | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `bank_slip_payment_schedules` * | array | Lista de agendamentos de boleto bancário. Limite de **1000** itens por requisição. | | `tfa_info` * | [object](#objeto-tfa_info) | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato. | Cada elemento de `bank_slip_payment_schedules` deve conter: | Campo | Tipo | Descrição | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente para aquele item do lote. | | `barcode` | string | Código de barras. | | `digitable_line` | string | Linha digitável. | | `payment_amount` * | number | Valor a ser pago. | | `payment_date` * | string | Data do agendamento do item. | :::danger Aviso Para cada item, o `payment_amount` deve seguir as regras do título retornadas na consulta do boleto bancário. Se o pagamento parcial não for permitido, o valor deve corresponder ao total atualizado do título. ::: ### Objeto tfa_info | Campo | Tipo | Descrição | |-----------------------------|---------|-----------------------------------| | `approver_document_number`* | string | Número de documento da pessoa aprovadora da conta (CPF/CNPJ). | | `contact_type`* | enumerator | Forma de envio do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** | | Enumerador | Descrição | |------------|---------------------------------------------------| | **sms** | Envio por mensagem de texto para telefone celular | | **email** | Envio por correio eletrônico | ## Response ### Success Response STATUS 202 Response Body: Lote de agendamento pendente de aprovação de dois fatores ```json { "batch_payment_schedule_key": "c4325104-d60b-44f3-aae4-49155564a2ea", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f", "total_amount": 1357.3, "batch_payment_schedule_status": "pending_2fa_approval", "payment_type": "bank_slip" } ``` ### Response Body Params | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------| | `batch_payment_schedule_key` * | uuid4 | Chave única de identificação do agendamento em lote. | | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `account_key` * | uuid4 | Chave da conta debitada. | | `total_amount` * | number | Soma dos valores (`payment_amount`) dos itens do lote. | | `batch_payment_schedule_status` * | [enum](#enumeradores-batch_payment_schedule_status) | Status do lote de agendamento após a solicitação. | | `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. | ### Enumeradores batch_payment_schedule_status | Enumerador | Descrição | |---------------|---------------| | `pending_2fa_approval` | Pendente de aprovação 2FA | | `scheduled` | Agendado | | `rejected` | Rejeitado | | `error` | Erro ao agendar | ### Enumeradores payment_type | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | :::danger Aviso O enumerador `collection_slip` não se aplica ao fluxo de agendamento em lote de boletos bancários deste endpoint; para este caso, espera-se `payment_type` com valor `bank_slip`. ::: ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação | | 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. | | 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. | | 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. | | 400 | BIP000052 | Bad Request | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta | | 400 | BIP000053 | Bad Request | Error getting approver data | Erro ao obter dados do aprovador | | 400 | BIP000054 | Bad Request | TFA info required | Informações de TFA necessárias | | 400 | BIP000055 | Bad Request | Error sending verification token | Erro ao enviar token de verificação | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. | --- # Solicitar agendamento em lote de fatura de recolhimento com autenticação de dois fatores (2FA) URL: /documentation/baas/cobranca/2fa_v2/agendamento/solicitar_agendamento_em_lote_de_fatura_de_recolhimento Este endpoint permite solicitar o **agendamento em lote** de faturas de recolhimento (convênio/tributo) em uma única requisição, com autenticação de dois fatores quando aplicável. :::info Fatura de recolhimento Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments_schedule/batch_collection_slip MÉTODO POST ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | Request Body: Agendamento em lote de faturas de recolhimento ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "collection_slip_payment_schedules": [ { "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd", "digitable_line": "836200000138892100450006762142420244046000010192", "payment_amount": 1389.21, "payment_date": "2026-04-10" }, { "request_control_key": "d8a26b54-323a-4924-0aed-e4fe6e4e4c0e", "barcode": "836200000138892100450006762142420244046000010192", "payment_amount": 550.10, "payment_date": "2026-04-15" } ], "tfa_info": { "approver_document_number": "98765432100", "contact_type": "email" } } ``` ### Body Params | Campo | Tipo | Descrição | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `collection_slip_payment_schedules` * | array | Lista de agendamentos de fatura de recolhimento. Limite de **1000** itens por requisição. | | `tfa_info` * | [object](#objeto-tfa_info) | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato. | Cada elemento de `collection_slip_payment_schedules` deve conter: | Campo | Tipo | Descrição | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente para aquele item do lote. | | `barcode` | string | Código de barras. | | `digitable_line` | string | Linha digitável. | | `payment_amount` * | number | Valor a ser pago. | | `payment_date` * | string | Data do agendamento do item. | ### Objeto tfa_info | Campo | Tipo | Descrição | |-----------------------------|---------|-----------------------------------| | `approver_document_number`* | string | Número de documento da pessoa aprovadora da conta (CPF/CNPJ). | | `contact_type`* | enumerator | Forma de envio do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** | | Enumerador | Descrição | |------------|---------------------------------------------------| | **sms** | Envio por mensagem de texto para telefone celular | | **email** | Envio por correio eletrônico | ## Response ### Success Response STATUS 202 Response Body: Lote de agendamento pendente de aprovação de dois fatores ```json { "batch_payment_schedule_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a", "request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9", "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72", "total_amount": 1939.31, "batch_payment_schedule_status": "pending_2fa_approval", "payment_type": "collection_slip" } ``` ### Response Body Params | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------| | `batch_payment_schedule_key` * | uuid4 | Chave única de identificação do agendamento em lote. | | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `account_key` * | uuid4 | Chave da conta debitada. | | `total_amount` * | number | Soma dos valores (`payment_amount`) dos itens do lote. | | `batch_payment_schedule_status` * | [enum](#enumeradores-batch_payment_schedule_status) | Status do lote de agendamento após a solicitação. | | `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. | ### Enumeradores batch_payment_schedule_status | Enumerador | Descrição | |---------------|---------------| | `pending_2fa_approval` | Pendente de aprovação 2FA | | `scheduled` | Agendado | | `rejected` | Rejeitado | | `error` | Erro ao agendar | ### Enumeradores payment_type | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | :::danger Aviso O enumerador `bank_slip` não se aplica ao fluxo de agendamento em lote de faturas de recolhimento deste endpoint; para este caso, espera-se `payment_type` com valor `collection_slip`. ::: ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 400 | BIP000032 | Bad Request | The bill sent does not correspond to a collection slip. | A conta enviada não corresponde a uma fatura de recolhimento. | | 400 | BIP000033 | Bad Request | The barcode or digitable line of the collection slip must have 44 or 48 characters. | O código de barras ou linha digitável da fatura de recolhimento deve ter 44 ou 48 caracteres. | | 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação | | 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. | | 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. | | 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. | | 403 | BIP000052 | Forbidden | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta | | 400 | BIP000053 | Bad Request | Error getting approver data | Erro ao obter dados do aprovador | | 400 | BIP000054 | Bad Request | TFA info required | Informações de TFA necessárias | | 400 | BIP000055 | Bad Request | Error sending verification token | Erro ao enviar token de verificação | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. | --- # Confirmação de lote de pagamento de boleto bancário URL: /documentation/baas/cobranca/2fa_v2/confirmacao_de_lote_de_boleto_bancario Este documento descreve a **mesma rota** de [Confirmação de lote de pagamento de boleto bancário](../confirmacao_de_lote_de_boleto_bancario.md) quando a operação exige **autenticação de dois fatores (2FA)** na etapa de confirmação: o corpo da requisição deve incluir **`tfa_info`** junto com `batch_status: approved` ou `batch_status: rejected`. Em seguida, o lote pode ficar em `pending_2fa_approval` (aprovação) ou `pending_2fa_rejection` (rejeição) até a **validação do token**. :::info Boleto bancário É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/payment/batch_bank_slip/**PAYMENT_BATCH_KEY**/confirmation MÉTODO PATCH ### Request Path Params | Campo | Tipo | Descrição | Caracteres | | --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- | | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | | `payment_batch_key` * | uuid4 | Chave única de identificação do lote (`batch_payment_key` retornado na criação do lote). | 36 | ### Request Body **Request Body: Rejeição do lote (com `tfa_info`)** ```json { "batch_status": "rejected", "tfa_info": { "approver_document_number": "98765432100", "contact_type": "email" } } ``` **Request Body: Aprovação do lote (com `tfa_info`)** ```json { "batch_status": "approved", "tfa_info": { "approver_document_number": "98765432100", "contact_type": "email" } } ``` ### Body Params | Campo | Tipo | Descrição | | ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `batch_status` * | string | Decisão sobre o lote. Valores: `approved` (seguir com o processamento) ou `rejected` (cancelar o lote). Ver [enumerador batch_confirmation_status](#enumerador-batch_confirmation_status). | | `tfa_info` | object | Obrigatório neste fluxo com `batch_status: approved` ou `batch_status: rejected`; informe aprovador e canal de envio do token em [objeto tfa_info](#objeto-tfa_info). | ### Enumerador batch_confirmation_status | Valor | Descrição | | ---------- | ------------------------------------------------------------- | | `approved` | Aprovar o lote e continuar o fluxo de processamento. | | `rejected` | Rejeitar o lote; não há processamento assíncrono dos boletos. | ### Objeto tfa_info | Campo | Tipo | Descrição | | ---------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `approver_document_number` * | string | Documento (CPF) da pessoa aprovadora que receberá o token. Obrigatório quando `tfa_info` é enviado. | | `contact_type` * | string | Canal para envio do token (por exemplo `sms` ou `email`), conforme regras da operação e cadastro. Obrigatório quando `tfa_info` é enviado. | ## Response O status HTTP e o campo `batch_status` na resposta dependem da decisão enviada e de o fluxo exigir validação do token após esta chamada. ### Resposta: lote rejeitado — pendência de validação do token (2FA) STATUS 202 Quando `batch_status` no corpo da requisição é `rejected` e a requisição inclui `tfa_info`, a API responde com **202**. O lote fica aguardando validação do token; o corpo retorna `batch_status` como `pending_2fa_rejection`. Após a validação do token, a decisão de rejeição é aplicada. **Response Body: Lote aguardando validação do token (decisão de rejeição)** ```json { "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f", "total_amount": 1357.3, "batch_status": "pending_2fa_approval", "payment_type": "bank_slip" } ``` ### Resposta: lote aprovado — pendência de validação do token (2FA) STATUS 202 Quando `batch_status` no corpo é `approved` e a requisição inclui `tfa_info`, a API responde com **202**. O lote fica aguardando validação do token; o corpo retorna `batch_status` como `pending_2fa_approval`. Os passos seguintes (envio do código, validação e reenvio) estão em [Validação de token de lote de pagamento de boleto bancário](./validacao_de_token_de_lote_de_boleto_bancario.md) e [Reenviar token de confirmação de lote de pagamento de boleto bancário](./solicitacao_de_reenvio_de_token_de_lote_de_boleto_bancario.md). **Response Body: Lote aguardando validação do token** ```json { "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f", "total_amount": 1357.3, "batch_status": "pending_2fa_rejection", "payment_type": "bank_slip" } ``` ### Response Body Params | Campo | Tipo | Descrição | | ----------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `batch_payment_key` * | uuid4 | Chave única de identificação do pagamento em lote. | | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `account_key` * | uuid4 | Chave da conta debitada. | | `total_amount` * | number | Soma dos valores dos itens do lote. | | `batch_status` * | string | Nesta chamada, o lote permanece em `pending_2fa_approval` (aprovação) ou `pending_2fa_rejection` (rejeição) até a validação do token. Após a validação, o status final reflete a decisão enviada na confirmação (`approved` ou `rejected`). | | `payment_type` * | string | Tipo do pagamento; para este fluxo, espera-se `bank_slip`. | ### Error Response STATUS 4XX **Response Body** ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | | ----------- | --------- | ----------- | --------------------------------------------- | ----------------------------------------------------- | | 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. | | 400 | BIP000050 | Bad Request | Requester configuration does not exist | Configuração do requester não existe. | | 400 | BIP000054 | Bad Request | TFA info required. | Informações de TFA necessárias. | | 404 | BIP000083 | Not Found | Batch payment not found by batch payment key. | Lote de pagamentos não encontrado pela chave do lote. | | 400 | BIP000084 | Bad Request | Batch payment status is not pending. | O status do lote de pagamentos não está pendente. | --- # Confirmação de lote de pagamento de fatura de recolhimento (convênio/tributo) URL: /documentation/baas/cobranca/2fa_v2/confirmacao_de_lote_de_fatura_de_recolhimento Este documento descreve a **mesma rota** de [Confirmação de lote de pagamento de fatura de recolhimento (convênio/tributo)](../confirmacao_de_lote_de_fatura_de_recolhimento.md) quando a operação exige **autenticação de dois fatores (2FA)** na etapa de confirmação: o corpo da requisição deve incluir **`tfa_info`** junto com `batch_status: approved` ou `batch_status: rejected`. Em seguida, o lote pode ficar em `pending_2fa_approval` (aprovação) ou `pending_2fa_rejection` (rejeição) até a **validação do token**. :::info Fatura de recolhimento Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um boleto bancário apresenta. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/payment/batch_collection_slip/**PAYMENT_BATCH_KEY**/confirmation MÉTODO PATCH ### Request Path Params | Campo | Tipo | Descrição | Caracteres | | --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- | | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | | `payment_batch_key` * | uuid4 | Chave única de identificação do lote (`batch_payment_key` retornado na criação do lote). | 36 | ### Request Body **Request Body: Rejeição do lote (com `tfa_info`)** ```json { "batch_status": "rejected", "tfa_info": { "approver_document_number": "98765432100", "contact_type": "email" } } ``` **Request Body: Aprovação do lote (com `tfa_info`)** ```json { "batch_status": "approved", "tfa_info": { "approver_document_number": "98765432100", "contact_type": "email" } } ``` ### Body Params | Campo | Tipo | Descrição | | ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `batch_status` * | string | Decisão sobre o lote. Valores: `approved` (seguir com o processamento) ou `rejected` (cancelar o lote). Ver [enumerador batch_confirmation_status](#enumerador-batch_confirmation_status). | | `tfa_info` | object | Obrigatório neste fluxo com `batch_status: approved` ou `batch_status: rejected`; informe aprovador e canal de envio do token em [objeto tfa_info](#objeto-tfa_info). | ### Enumerador batch_confirmation_status Valores aceitos no corpo da requisição para `batch_status`: | Valor | Descrição | | ---------- | ----------------------------------------------------------------------------- | | `approved` | Aprovar o lote e continuar o fluxo de processamento. | | `rejected` | Rejeitar o lote; não há processamento assíncrono das faturas de recolhimento. | ### Objeto tfa_info | Campo | Tipo | Descrição | | ---------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `approver_document_number` * | string | Documento (CPF) da pessoa aprovadora que receberá o token. Obrigatório quando `tfa_info` é enviado. | | `contact_type` * | string | Canal para envio do token (por exemplo `sms` ou `email`), conforme regras da operação e cadastro. Obrigatório quando `tfa_info` é enviado. | ## Response O status HTTP e o campo `batch_status` na resposta dependem da decisão enviada e de o fluxo exigir validação do token após esta chamada. ### Resposta: lote rejeitado — pendência de validação do token (2FA) STATUS 202 Quando `batch_status` no corpo da requisição é `rejected` e a requisição inclui `tfa_info`, a API responde com **202**. O lote fica aguardando validação do token; o corpo retorna `batch_status` como `pending_2fa_rejection`. Após a validação do token, a decisão de rejeição é aplicada. **Response Body: Lote aguardando validação do token (decisão de rejeição)** ```json { "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72", "total_amount": 2778.42, "batch_status": "pending_2fa_rejection", "payment_type": "collection_slip" } ``` ### Resposta: lote aprovado — pendência de validação do token (2FA) STATUS 202 Quando `batch_status` no corpo é `approved` e a requisição inclui `tfa_info`, a API responde com **202**. O lote fica aguardando validação do token; o corpo retorna `batch_status` como `pending_2fa_approval`. Os passos seguintes estão em [Validação de token de lote de pagamento de fatura de recolhimento (convênio/tributo)](./validacao_de_token_de_lote_de_fatura_de_recolhimento.md) e [Reenviar token de confirmação de lote de pagamento de fatura de recolhimento (convênio/tributo)](./solicitacao_de_reenvio_de_token_de_lote_de_fatura_de_recolhimento.md). **Response Body: Lote aguardando validação do token** ```json { "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72", "total_amount": 2778.42, "batch_status": "pending_2fa_rejection", "payment_type": "collection_slip" } ``` ### Response Body Params | Campo | Tipo | Descrição | | ----------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `batch_payment_key` * | uuid4 | Chave única de identificação do pagamento em lote. | | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `account_key` * | uuid4 | Chave da conta debitada. | | `total_amount` * | number | Soma dos valores dos itens do lote. | | `batch_status` * | string | Nesta chamada, o lote permanece em `pending_2fa_approval` (aprovação) ou `pending_2fa_rejection` (rejeição) até a validação do token. Após a validação, o status final reflete a decisão enviada na confirmação (`approved` ou `rejected`). | | `payment_type` * | string | Tipo do pagamento; para este fluxo, espera-se `collection_slip`. | ### Error Response STATUS 4XX **Response Body** ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | | ----------- | --------- | ----------- | --------------------------------------------- | ----------------------------------------------------- | | 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. | | 400 | BIP000050 | Bad Request | Requester configuration does not exist | Configuração do requester não existe. | | 400 | BIP000054 | Bad Request | TFA info required. | Informações de TFA necessárias. | | 404 | BIP000083 | Not Found | Batch payment not found by batch payment key. | Lote de pagamentos não encontrado pela chave do lote. | | 400 | BIP000084 | Bad Request | Batch payment status is not pending. | O status do lote de pagamentos não está pendente. | --- # Confirmação de Pagamento de Boleto Bancário URL: /documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_boleto_bancario Este endpoint permite realizar a confirmação do pagamento de boleto bancário. :::info Boleto bancário É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central. ::: ## Request ### Request Endpoint ENDPOINT /account/ ACCOUNT_KEY /payment/ PAYMENT_KEY /bank_slip/validate_token MÉTODO PATCH ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | | `payment_key` * | uuid4 | Chave única de identificação do pagamento. | 36 | ### Autenticação via Email e SMS Request Body: Confirmação de pagamento de boleto bancário ```json { "token": "329adf" } ``` ### Autenticação via Dispositivo Para aprovar e finalizar a autenticação via dispositivo, a requisição deve ser enviada com um payload vazio. A validação ocorre internamente, sem necessidade de informações adicionais no corpo da requisição. É importante destacar que este endpoint só deve ser utilizado após a [solicitação de transação](./solicitacao_de_pagamento_de_boleto_bancario.md) ter sido iniciada. Request Body: Confirmação de pagamento de boleto bancário ```json { } ``` ### Body Params | Campo | Tipo | Descrição | Caracteres | |-----------|--------|-----------------------------------------------------------------------|------------| | `token` | string | Código de autenticação enviado ao aprovador de movimentações da conta **obrigatório para TFA via SMS ou e-mail**| 6 | ## Response ### Success Response STATUS 200 Response Body: Pagamento executado ```json { "payment_key":"c4325104-d60b-44f3-aae4-49155564a2ea", "request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189", "payer_name":"COOPERATIVA INDUSTRIAL MURILO", "payer_document_number":"00037025000160", "source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f", "transaction_key":"4e80070a-a0bb-4be2-8178-55fbd73a3704", "transaction_revert_key":null, "paid_amount":1050.1, "payment_date":"2024-04-03", "payment_type":"bank_slip", "bank_slip": { "bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a", "barcode":"00193967000009910000000003615574000000002417", "digitable_line":"00190000090361557400500000024174396700000991000", "payer_name":"COOPERATIVA TESTE", "payer_document_number":"00037025000160", "beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA", "beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA", "beneficiary_document_number":"52069937000117", "beneficiary_bank_ispb":"00000000", "guarantor_name":null, "guarantor_document_number":null, "expiration_date":"2024-03-29", "max_payment_data": "2026-03-29", "partial_payment_indicator":"allowed", "registered_payment_amount":9029.0, "nominal_amount":9910.0, "total_amount":10129.1, "rebate_amount":0.0, "discount_amount":0.0, "fine_amount":0.0, "interest_amount":219.1 }, "collection_slip":null, "payment_status":"executed" } ``` STATUS 202 Response Body: Pagamento pendente de execução ```json { "payment_key":"c4325104-d60b-44f3-aae4-49155564a2ea", "request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189", "payer_name":"COOPERATIVA INDUSTRIAL MURILO", "payer_document_number":"00037025000160", "source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f", "transaction_key":"4e80070a-a0bb-4be2-8178-55fbd73a3704", "transaction_revert_key":null, "paid_amount":1050.1, "payment_date":"2024-04-03", "payment_type":"bank_slip", "bank_slip": { "bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a", "barcode":"00193967000009910000000003615574000000002417", "digitable_line":"00190000090361557400500000024174396700000991000", "payer_name":"COOPERATIVA TESTE", "payer_document_number":"00037025000160", "beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA", "beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA", "beneficiary_document_number":"52069937000117", "beneficiary_bank_ispb":"00000000", "guarantor_name":null, "guarantor_document_number":null, "expiration_date":"2024-03-29", "max_payment_data": "2026-03-29", "partial_payment_indicator":"allowed", "registered_payment_amount":9029.0, "nominal_amount":9910.0, "total_amount":10129.1, "rebate_amount":0.0, "discount_amount":0.0, "fine_amount":0.0, "interest_amount":219.1 }, "collection_slip":null, "payment_status": "pending_execution" } ``` :::info Informação Caso seja retornado **HTTP Status 202** com o campo `payment_status` com valor **pending_execution**, o pagamento não deve ser retentado. Este pagamento será processado assincronamente. É necessário verificar o status da transferência por meio da consulta de pagamento, ou aguardar envio do webhook de pagamento pendente descrito na [página de webhooks](/documentation/baas/cobranca/webhooks). ::: ### Response Body Params | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------| | `payment_key` * | uuid4 | Chave única de identificação do pagamento. | | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente. | | `payer_name` * | string | Nome do pagador efetivo.| | `payer_document_number` * | string | Número do documento do pagador efetivo (CPF/CNPJ). | | `source_account_key` * | uuid4 | Chave da conta debitada. | | `transaction_key` * | uuid4 | Chave da transação do pagamento. | | `transaction_revert_key` | uuid4 | Chave da transação de reversão do pagamento. | | `paid_amount` * | number | Valor pago efetivamente. | | `payment_date` * | string | Data do pagamento. | | `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. | | `bank_slip` | [object](#objeto-bank_slip) | Boleto bancário. | | `collection_slip` | object | Fatura de recolhimento. | | `payment_status` * | [enum](#enumeradores-payment_status) | Status do pagamento. | ### Enumeradores payment_type | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | :::danger Aviso O enumerador `collection_slip` não se aplica para o fluxo de boletos bancários, assim como o objeto collection_slip que sempre será nulo. ::: ### Enumeradores payment_status | Enumerador | Descrição | |---------------|---------------| | `pending_execution` | Pendente de execução | | `executed` | Executado | | `reverted` | Revertido | | `rejected` | Rejeitado | | `error` | Erro | :::danger Aviso Para pagamentos aonde a QI não receber uma resposta da CIP em até dois minutos, o pagamento será retornado com o status `pending_execution`. Após a QI receber a resposta da CIP, será enviado para o cliente o webhook de pagamento pendente descrito na [página de webhooks](/documentation/baas/cobranca/webhooks). ::: ### Objeto bank_slip | Campo | Tipo | Descrição | |-----------------------------------|---------|-----------------------------------| | `barcode` * | string | Código de barras. | | `digitable_line` * | string | Linha digitável. | | `payer_name` * | string | Nome do pagador.| | `payer_document_number` * | string | Número do documento do pagador (CPF/CNPJ). | | `beneficiary_name` * | string | Nome do beneficiário. | | `beneficiary_trading_name` | string | Nome fantasia do beneficiário. | | `beneficiary_document_number` * | string | Número do documento do beneficiário (CPF/CNPJ). | | `beneficiary_bank_ispb` * | string | Código ispb do banco do beneficiário. | | `guarantor_name` | string | Nome do sacador avalista. | | `guarantor_document_number` | string | Número do documento do sacador avalista (CPF/CNPJ). | | `expiration_date` * | string | Data de vencimento. | | `max_payment_date` * | string | Data máxima de pagamento. | | `partial_payment_indicator` * | [enum](#enumeradores-partial_payment_indicator) | Indicador de pagamento parcial. | | `registered_payment_amount` | string | Valor total de pagamento registrado. | | `nominal_amount` * | number | Valor original. | | `total_amount` * | number | Valor total. | | `rebate_amount` * | number | Valor do batimento. | | `discount_amount` * | number | Valor do desconto. | | `fine_amount` * | number | Valor da multa. | | `interest_amount` * | number | Valor do juros. | ### Enumeradores partial_payment_indicator | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `allowed` | string | Permitido | | `not_allowed` | string | Não permitido | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação | | 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. | | 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. | | 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. | | 400 | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. | | 400 | BIP000022 | Bad Request | Bank slip payment service is closed. | Serviço de pagamento de boleto está fechado. | | 400 | BIP000023 | Bad Request | The source account has insufficient balance. Payment cannot be made. | A conta de origem possui saldo insuficiente. Pagamento não pode ser realizado. | | 400 | BIP000025 | Bad Request | It was not possible to pay the bank slip at this time. Please verify your information and, if necessary, contact us for assistance. | Não foi possível pagar o boleto neste momento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para assistência. | | 400 | BIP000028 | Bad Request | The source account has blocked balance. Payment cannot be made. | A conta de origem possui saldo em conta bloqueado. Pagamento não pode ser realizado. | | 400 | BIP000029 | Bad Request | Bank slip payment write off rejected. | Baixa de pagamento de boleto rejeitada. | | 404 | BIP000056 | Not Found | Payment not found. | Pagamento não encontrado. | | 400 | BIP000057 | Bad Request | Payment status is not pending approval. | Status de pagamento não é de aprovação pendente. | | 400 | BIP000058 | Bad Request | Error while validating verification token | Erro ao validar token de verificação | | 400 | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Número de tentativas de validação de token de verificação excedido. | | 400 | BIP000060 | Bad Request | Verification token expired. | Token de verificação expirado. | | 400 | BIP000061 | Bad Request | Verification token validation failed. | Falha na validação do token de verificação. | | 400 | BIP000062 | Bad Request | Payment type is not bank slip. | Tipo de pagamento não é boleto. | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. | | 400 | BIP000086 | Bad Request | A token is required for SMS or email validation. | Um token é necessário para validação via SMS ou email. | --- # Confirmação de Pagamento de Fatura de Recolhimento URL: /documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_fatura_de_recolhimento Este endpoint permite realizar a confirmação do pagamento de faturas de recolhimento. :::info Fatura de recolhimento Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgão públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta. ::: ## Request ### Request Endpoint ENDPOINT /account/ ACCOUNT_KEY /payment/ PAYMENT_KEY /collection_slip/validate_token MÉTODO PATCH ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | | `payment_key` * | uuid4 | Chave única de identificação do pagamento. | 36 | ### Autenticação via Email e SMS Request Body: Confirmação de pagamento de fatura de recolhimento ```json { "token": "329adf" } ``` ### Autenticação via Dispositivo Para aprovar e finalizar a autenticação via dispositivo, a requisição deve ser enviada com um payload vazio. A validação ocorre internamente, sem necessidade de informações adicionais no corpo da requisição. É importante destacar que este endpoint só deve ser utilizado após a [solicitação de transação](./solicitacao_de_pagamento_de_fatura_de_recolhimento.md) ter sido iniciada. Request Body: Confirmação de pagamento de fatura de recolhimento ```json { } ``` ### Body Params | Campo | Tipo | Descrição | Caracteres | |-----------|--------|-----------------------------------------------------------------------|------------| | `token` | string | Código de autenticação enviado ao aprovador de movimentações da conta **obrigatório para TFA via SMS ou e-mail**| 6 | ## Response ### Success Response STATUS 200 Response Body: Pagamento executado ```json { "payment_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a", "request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9", "payer_name": "COOPERATIVA INDUSTRIAL MURILO", "payer_document_number": "62069937000118", "source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72", "transaction_key": "fc9ccfd0-2f21-4207-9772-69238be74152", "transaction_revert_key": null, "paid_amount": 1389.21, "payment_date": "2024-04-30", "payment_type": "collection_slip", "bank_slip": null, "collection_slip": { "barcode": null, "digitable_line": "836200000138892100450006762142420244046000010192", "collection_name": "CIA ULTRAGAZ SA-COD", "collection_document_number": "00394460005887", "expiration_date": "2024-04-15", "total_amount": 1389.21 }, "payment_status": "executed" } ``` ### Response Body Params | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------| | `payment_key` * | uuid4 | Chave única de identificação do pagamento. | | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente. | | `payer_name` * | string | Nome do pagador efetivo.| | `payer_document_number` * | string | Número do documento do pagador efetivo (CPF/CNPJ). | | `source_account_key` * | uuid4 | Chave da conta debitada. | | `transaction_key` * | uuid4 | Chave da transação do pagamento. | | `transaction_revert_key` | uuid4 | Chave da transação de reversão do pagamento. | | `paid_amount` * | number | Valor pago efetivamente. | | `payment_date` * | string | Data do pagamento. | | `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. | | `bank_slip` | object | Boleto bancário. | | `collection_slip` | [object](#objeto-collection_slip) | Fatura de recolhimento. | | `payment_status` * | [enum](#enumeradores-payment_status) | Status do pagamento. | ### Enumeradores payment_type | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | :::danger Aviso O enumerador `bank_slip` não se aplica para o fluxo de faturas de recolhimento, assim como o objeto bank_slip que sempre será nulo. ::: ### Enumeradores payment_status | Enumerador | Descrição | |---------------|---------------| | `executed` | Executado | | `reverted` | Revertido | | `rejected` | Rejeitado | | `error` | Erro | ### Objeto collection_slip | Campo | Tipo | Descrição | |-----------------------------------|---------|-----------------------------------| | `barcode` | string | Código de barras. | | `digitable_line` | string | Linha digitável. | | `collection_name` * | string | Nome do convênio.| | `collection_document_number` | string | Número de documento do convênio (CPF/CNPJ).| | `expiration_date` * | string | Data de vencimento. | | `total_amount` * | number | Valor total. | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação | | 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. | | 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. | | 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. | | 400 | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |s | 400 | BIP000023 | Bad Request | The source account has insufficient balance. Payment cannot be made. | A conta de origem possui saldo insuficiente. Pagamento não pode ser realizado. | | 400 | BIP000028 | Bad Request | The source account has blocked balance. Payment cannot be made. | A conta de origem possui saldo em conta bloqueado. Pagamento não pode ser realizado. | | 400 | BIP000034 | Bad Request | Collection slip already paid. | Fatura de recolhimento já paga. | | 400 | BIP000036 | Bad Request | Covenant slip overdue. | Fatura de recolhimento vencida. | | 400 | BIP000038 | Bad Request | Outside of covenant payment hours. | Fora do horário de pagamento do convênio. | | 400 | BIP000044 | Bad Request | It was not possible to pay the collection slip at this time. Please verify your information and, if necessary, contact us for assistance. | Não foi possível pagar a fatura de recolhimento neste momento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para assistência. | | 400 | BIP000045 | Bad Request | Collection slip payment service is closed. | Serviço de pagamento de fatura de recolhimento está fechado. | | 404 | BIP000056 | Not Found | Payment not found. | Pagamento não encontrado. | | 400 | BIP000057 | Bad Request | Payment status is not pending approval. | Status de pagamento não é de aprovação pendente. | | 400 | BIP000058 | Bad Request | Error while validating verification token | Erro ao validar token de verificação | | 400 | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Número de tentativas de validação de token de verificação excedido. | | 400 | BIP000060 | Bad Request | Verification token expired. | Token de verificação expirado. | | 400 | BIP000061 | Bad Request | Verification token validation failed. | Falha na validação do token de verificação. | | 400 | BIP000063 | Bad Request | Payment type is not collection slip. | Tipo de pagamento não é fatura de recolhimento. | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. | | 400 | BIP000086 | Bad Request | A token is required for SMS or email validation. | Um token é necessário para validação via SMS ou email. | --- # Introdução a Autenticação de Dois Fatores URL: /documentation/baas/cobranca/2fa_v2/introducao_ao_pagamento_2fa Neste tipo de pagamento, é necessário a confirmação do pagamento via token enviado à pessoa com poderes de aprovação de movimentação na conta pagadora. A solicitação de pagamento por parceiros integradores configurados para a utilização de autenticação de dois fatores é realizada de forma similar ao descrito em [pagamento de boleto bancário](/documentation/baas/cobranca/pagar_boleto_bancario) e [pagamento de fatura de recolhimento](/documentation/baas/cobranca/pagar_fatura_de_recolhimento). A diferença ocorre na adição do objeto `tfa_info` na requisição, contendo informações sobre o aprovador da transferência e a forma de contato, e o status da solicitação no retorna da requisição. O status da solicitação sempre será retornado como **pending_2fa_approval**. ## Fluxo para uma pagamento com autorização O pagamento bem sucedido seguirá o seguinte fluxo de processos: - Realização da [solicitação de pagamento de boleto bancário](/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_boleto_bancario) ou [solicitação de pagamento de fatura de recolhimento](/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_fatura_de_recolhimento) e recebimento da resposta de forma síncrona com status de **pending_2fa_approval** e a `payment_key`. - O aprovador indicado receberá um `token` de 6 dígitos compostos por algarismos. - O requisitante realiza a [confirmação do pagamento de boleto bancário](/documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_boleto_bancario) ou [confirmação do pagamento de fatura de recolhimento](/documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_fatura_de_recolhimento) com a `payment_key` e o `token`. - O pagamento será concluída de forma síncrona. ## Observações - Cada pagamento possui um limite máximo de tentativas de validação do `token` de 5 vezes. Quando este limite é alcançado o pagamento será colocado em status de rejeitado (**rejected**) automaticamente. - Cada `token` possui duração máxima de 5 minutos. - Um pagamento pode ter seu `token` renovado e reenviado para o aprovador da conta. Este processo reinicia o tempo de 5 minutos e não reinicia o contador de tentativas inválidas. O `token` anterior torna-se inválido. - Uma vez aprovado o pagamento, este será concluído de forma síncrona. - O evento de notificação para o envio de `token` ao aprovador é **baas.token_validation.bill_payment.payment.single**. É possível [personalizar](/documentation/notificacoes/template) a mensagem enviada. - As formas de envio (`contact_type`) de token implementadas são por **sms** e **email**. --- # Solicitação de pagamento de Boleto Bancário com Autenticação de Dois Fatores URL: /documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_boleto_bancario Este endpoint permite realizar a solicitação de pagamento de boletos bancários. A solicitação deve ser realizado após a consulta, utilizando as informações retornadas para garantir o funcionamento correto do fluxo, evitando falhas durante o processo. :::info Boleto bancário É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central. ::: ## Request ### Request Endpoint ENDPOINT /account/ ACCOUNT_KEY /payment/bank_slip MÉTODO POST ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | ## Autenticação via Email e SMS Request Body: Solicitação de boleto bancário com linha digitável com TFA por SMS ou Email ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "digitable_line": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8, "tfa_info": { "approver_document_number": "98765432100", "contact_type": "email" } } ``` Request Body: Solicitação de boleto bancário com código de barras com TFA por SMS ou Email ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "barcode": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8, "tfa_info": { "approver_document_number": "98765432100", "contact_type": "email" } } ``` ## Autenticação via Dispositivo Além das formas já existentes de autenticação via **sms** e **email**, é possível autenticar a transação utilizando um dispositivo [previamente cadastrado](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). Nesse caso, o `session_id` deve ser obtido na **Device Scan** e enviado no `tfa_info`. Request Body: Solicitação de boleto bancário com linha digitável com TFA por Dispositivo ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "digitable_line": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8, "tfa_info": { "approver_document_number": "98765432100", "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72", "contact_type": "device" } } ``` Request Body: Solicitação de boleto bancário com código de barras com TFA por Dispositivo ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "barcode": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8, "tfa_info": { "approver_document_number": "98765432100", "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72", "contact_type": "device" } } ``` ### Body Params | Campo | Tipo | Descrição | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente. | | `barcode` | string | Código de barras. | | `digitable_line` | string | Linha digitável. | | `payment_amount` * | number | Valor a ser pago. | | `tfa_info` * | [object](#objeto-tfa_info) | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato. | :::danger Aviso O `payment_amount` deve sempre igual ao `total_amount` retornado na consulta do boleto bancário caso o pagamento parcial não seja permitido para o boleto bancário. Para títulos em que o pagamento parcial é permitido, o cliente pode escolher o `payment_amount`, desde que a soma do mesmo com o `registered_payment_amount` do boleto bancário não seja superior que o `total_amount`. ::: ### Objeto tfa_info | Campo | Tipo | Descrição | |-----------------------------------|---------|-----------------------------------| | `approver_document_number`* | string | Número de documento da pessoa aprovadora da conta (CPF/CNPJ). | | `session_id`| string | Chave única de identificação da sessão do dispositivo no formato UUID v4 (obrigatório para TFA via dispositivo). | 36 | | `contact_type`* | enumerator | Método de validação do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** | | Enumerador | Descrição | |------------|---------------------------------------------------| | **sms** | Envio por Mensagem de Texto para telefone celular | | **email** | Envio por correio eletrônico | | **device** | Validação por token do dispositivo | ## Response ### Success Response STATUS 201 Response Body: Pagamento pendente de aprovação de dois fatores ```json { "payment_key":"c4325104-d60b-44f3-aae4-49155564a2ea", "request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189", "payer_name":"COOPERATIVA INDUSTRIAL MURILO", "payer_document_number":"00037025000160", "source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f", "transaction_key":"4e80070a-a0bb-4be2-8178-55fbd73a3704", "transaction_revert_key":null, "paid_amount":1050.1, "payment_date":"2024-04-03", "payment_type":"bank_slip", "bank_slip": { "bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a", "barcode":"00193967000009910000000003615574000000002417", "digitable_line":"00190000090361557400500000024174396700000991000", "payer_name":"COOPERATIVA TESTE", "payer_document_number":"00037025000160", "beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA", "beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA", "beneficiary_document_number":"52069937000117", "beneficiary_bank_ispb":"00000000", "guarantor_name":null, "guarantor_document_number":null, "expiration_date":"2024-03-29", "max_payment_data": "2026-03-29", "partial_payment_indicator":"allowed", "registered_payment_amount":9029.0, "nominal_amount":9910.0, "total_amount":10129.1, "rebate_amount":0.0, "discount_amount":0.0, "fine_amount":0.0, "interest_amount":219.1 }, "collection_slip":null, "payment_status":"pending_2fa_approval" } ``` ### Response Body Params | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------| | `payment_key` * | uuid4 | Chave única de identificação do pagamento. | | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente. | | `payer_name` * | string | Nome do pagador efetivo.| | `payer_document_number` * | string | Número do documento do pagador efetivo (CPF/CNPJ). | | `source_account_key` * | uuid4 | Chave da conta debitada. | | `transaction_key` * | uuid4 | Chave da transação do pagamento. | | `transaction_revert_key` | uuid4 | Chave da transação de reversão do pagamento. | | `paid_amount` * | number | Valor pago efetivamente. | | `payment_date` * | string | Data do pagamento. | | `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. | | `bank_slip` | [object](#objeto-bank_slip) | Boleto bancário. | | `collection_slip` | object | Fatura de recolhimento. | | `payment_status` * | [enum](#enumeradores-payment_status) | Status do pagamento. | ### Enumeradores payment_type | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | :::danger Aviso O enumerador `collection_slip` não se aplica para o fluxo de boletos bancários, assim como o objeto collection_slip que sempre será nulo. ::: ### Enumeradores payment_status | Enumerador | Descrição | |---------------|---------------| | `pending_2fa_approval` | pendente de aprovação de dois fatores | ### Objeto bank_slip | Campo | Tipo | Descrição | |-----------------------------------|---------|-----------------------------------| | `barcode` * | string | Código de barras. | | `digitable_line` * | string | Linha digitável. | | `payer_name` * | string | Nome do pagador.| | `payer_document_number` * | string | Número do documento do pagador (CPF/CNPJ). | | `beneficiary_name` * | string | Nome do beneficiário. | | `beneficiary_trading_name` | string | Nome fantasia do beneficiário. | | `beneficiary_document_number` * | string | Número do documento do beneficiário (CPF/CNPJ). | | `beneficiary_bank_ispb` * | string | Código ispb do banco do beneficiário. | | `guarantor_name` | string | Nome do sacador avalista. | | `guarantor_document_number` | string | Número do documento do sacador avalista (CPF/CNPJ). | | `expiration_date` * | string | Data de vencimento. | | `max_payment_date` * | string | Data máxima de pagamento. | | `partial_payment_indicator` * | [enum](#enumeradores-partial_payment_indicator) | Indicador de pagamento parcial. | | `registered_payment_amount` | string | Valor total de pagamento registrado. | | `nominal_amount` * | number | Valor original. | | `total_amount` * | number | Valor total. | | `rebate_amount` * | number | Valor do abatimento. | | `discount_amount` * | number | Valor do desconto. | | `fine_amount` * | number | Valor da multa. | | `interest_amount` * | number | Valor do juros. | ### Enumeradores partial_payment_indicator | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `allowed` | string | Permitido | | `not_allowed` | string | Não permitido | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 400 | BIP000001 | Bad Request | The barcode or digitable line must have 44 or 47 characters. | O código de barras ou linha digitável deve ter 44 ou 47 caracteres. | | 400 | BIP000002 | Bad Request | The bill sent does not correspond to a bank slip. | A conta enviado não corresponde a um boleto bancário. | | 400 | BIP000003 | Bad Request | The digitable line sent is invalid. | A linha digitável enviada é inválida. | | 404 | BIP000004 | Not Found | The bank slip was not found. | O boleto não foi encontrado. | | 400 | BIP000005 | Bad Request | It was not possible to consult the bank slip at this time. Please try again in a few minutes. | Não foi possível consultar o boleto neste momento. Por favor, tente novamente em alguns minutos. | | 400 | BIP000006 | Bad Request | Bank slip already written off | Boleto já baixado | | 400 | BIP000007 | Bad Request | Bank slip blocked for payment | Boleto bloqueado para pagamento | | 400 | BIP000008 | Bad Request | Bank slip already paid | Boleto já pago | | 400 | BIP000009 | Bad Request | Invalid bank slip. Please consult issuing bank | Boleto inválido. Favor consultar banco emissor | | 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação | | 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. | | 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. | | 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. | | 400 | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. | | 400 | BIP000015 | Bad Request | Payment date is greater than the maximum payment date. | A data de pagamento é maior que a data máxima de pagamento. | | 400 | BIP000016 | Bad Request | Payment date is smaller than the calculation date. | A data de pagamento é menor que a data de cálculo. | | 400 | BIP000017 | Bad Request | Invalid payment amount. | Valor de pagamento inválido. | | 400 | BIP000018 | Bad Request | Partial payment is not allowed. | Pagamento parcial não é permitido. | | 400 | BIP000019 | Bad Request | The payment amount is greater than the available amount. | O valor do pagamento é maior que o valor disponível. | | 400 | BIP000020 | Bad Request | All partial payments for this bank slip have already been made. | Todos os pagamentos parciais deste boleto já foram realizados. | | 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. | | 403 | BIP000052 | Forbidden | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta | | 400 | BIP000053 | Bad Request | Error getting approver data | Erro ao obter dados do aprovador | | 400 | BIP000054 | Bad Request | TFA info required | Informações de TFA necessárias | | 400 | BIP000055 | Bad Request | Error sending verification token | Erro ao enviar token de verificação | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. | | 400 | BIP000079 | Bad Request | A session_id must be provided token | Uma session_id deve ser fornecida | ## Ambiente de Sandbox Em nosso ambiente de sandbox, disponibilizamos linhas digitáveis mockadas para a simulação de pagamentos bem-sucedidos e testes de cenários de erro. | Linha digitável | |-----------------| | 00190000090361557400500000024174396700000991000 | | 00190000090282802601919212747174596760001294161 | | 23793390014000000455277000249001596900000103995 | | 75691434020137513680900001040013196770002417240 | | 21390001171200000570700168167484796770000148206 | | 34191090083273252027893634770007296690012513600 | | 42297048060005815702500130494123896770000239491 | | 07090010287045349010776686070590896770001160123 | | 74891123702849020818918378871083196690000050000 | | 23792374119000209350986000372408496610000122810 | --- # Solicitação de Pagamento de Fatura de Recolhimento com Autenticação de Dois Fatores URL: /documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_fatura_de_recolhimento Este endpoint permite realizar a solicitação de pagamento de faturas de recolhimento com autenticação de dois fatores. A solicitação deve ser realizado após a consulta, utilizando as informações retornadas para garantir o funcionamento correto do fluxo, evitando falhas durante o processo. :::info Fatura de recolhimento Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgão públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta. ::: ## Request ### Request Endpoint ENDPOINT /account/ ACCOUNT_KEY /payment/collection_slip MÉTODO POST ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | ## Autenticação via Email e SMS Request Body: Solicitação de fatura de recolhimento com linha digitável com TFA por SMS ou Email ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "digitable_line": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8, "tfa_info": { "approver_document_number": "98765432100", "contact_type": "email" } } ``` Request Body: Solicitação de fatura de recolhimento com código de barras com TFA por SMS ou Email ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "barcode": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8, "tfa_info": { "approver_document_number": "98765432100", "contact_type": "email" } } ``` ## Autenticação via Dispositivo Além das formas já existentes de autenticação via **sms** e **email**, é possível autenticar a transação utilizando um dispositivo [previamente cadastrado](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). Nesse caso, o `session_id` deve ser obtido na **Device Scan** e enviado no `tfa_info`. Request Body: Solicitação de fatura de recolhimento com linha digitável com TFA por Dispositivo ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "digitable_line": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8, "tfa_info": { "approver_document_number": "98765432100", "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72", "contact_type": "device" } } ``` Request Body: Solicitação de fatura de recolhimento com código de barras com TFA por Dispositivo ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "barcode": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8, "tfa_info": { "approver_document_number": "98765432100", "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72", "contact_type": "device" } } ``` ### Body Params | Campo | Tipo | Descrição | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente. | | `barcode` | string | Código de barras. | | `digitable_line` | string | Linha digitável. | | `payment_amount` * | number | Valor a ser pago. | | `tfa_info` * | [object](#objeto-tfa_info) | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato. | :::danger Aviso O `payment_amount` deve sempre igual ao `total_amount` retornado na consulta do boleto bancário. ::: ### Objeto tfa_info | Campo | Tipo | Descrição | |-----------------------------------|---------|-----------------------------------| | `approver_document_number`* | string | Número de documento da pessoa aprovadora da conta (CPF/CNPJ). | | `session_id`| string | Chave única de identificação da sessão do dispositivo no formato UUID v4 (obrigatório para TFA via dispositivo). | 36 | | `contact_type`* | enumerator | Método de validação do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** | | Enumerador | Descrição | |------------|---------------------------------------------------| | **sms** | Envio por Mensagem de Texto para telefone celular | | **email** | Envio por correio eletrônico | | **device** | Validação por token do dispositivo | ## Response ### Success Response STATUS 201 Response Body: Pagamento pendente de aprovação de dois fatores ```json { "payment_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a", "request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9", "payer_name": "COOPERATIVA INDUSTRIAL MURILO", "payer_document_number": "62069937000118", "source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72", "transaction_key": "fc9ccfd0-2f21-4207-9772-69238be74152", "transaction_revert_key": null, "paid_amount": 1389.21, "payment_date": "2024-04-30", "payment_type": "collection_slip", "bank_slip": null, "collection_slip": { "barcode": null, "digitable_line": "836200000138892100450006762142420244046000010192", "collection_name": "CIA ULTRAGAZ SA-COD", "collection_document_number": "00394460005887", "expiration_date": "2024-04-15", "total_amount": 1389.21 }, "payment_status": "pending_2fa_approval" } ``` ### Response Body Params | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------| | `payment_key` * | uuid4 | Chave única de identificação do pagamento. | | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente. | | `payer_name` * | string | Nome do pagador efetivo.| | `payer_document_number` * | string | Documento do pagador efetivo (CPF/CNPJ). | | `source_account_key` * | uuid4 | Chave da conta debitada. | | `transaction_key` * | uuid4 | Chave da transação do pagamento. | | `transaction_revert_key` | uuid4 | Chave da transação de reversão do pagamento. | | `paid_amount` * | number | Valor pago efetivamente. | | `payment_date` * | string | Data do pagamento. | | `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. | | `bank_slip` | object | Boleto bancário. | | `collection_slip` | [object](#objeto-collection_slip) | Fatura de recolhimento. | | `payment_status` * | [enum](#enumeradores-payment_status) | Status do pagamento. | ### Enumeradores payment_type | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | :::danger Aviso O enumerador `bank_slip` não se aplica para o fluxo de faturas de recolhimento, assim como o objeto bank_slip que sempre será nulo. ::: ### Enumeradores payment_status | Enumerador | Descrição | |---------------|---------------| | `pending_2fa_approval` | pendente de aprovação de dois fatores | ### Objeto collection_slip | Campo | Tipo | Descrição | |-----------------------------------|---------|-----------------------------------| | `barcode` | string | Código de barras. | | `digitable_line` | string | Linha digitável. | | `collection_name` * | string | Nome do convênio.| | `collection_document_number` | string | Número de documento do convênio (CPF/CNPJ).| | `expiration_date` * | string | Data de vencimento. | | `total_amount` * | number | Valor total. | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 400 | BIP000032 | Bad Request | The bill sent does not correspond to a collection slip. | A conta enviada não corresponde a uma fatura de recolhimento. | | 400 | BIP000033 | Bad Request | The barcode or digitable line of the collection slip must have 44 or 48 characters. | O código de barras ou linha digitável da fatura de recolhimento deve ter 44 ou 48 caracteres. | | 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação | | 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. | | 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. | | 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. | | 400 | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. | | 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. | | 400 | BIP000028 | Bad Request | The source account has blocked balance. Payment cannot be made. | A conta de origem possui saldo em conta bloqueado. Pagamento não pode ser realizado. | | 400 | BIP000034 | Bad Request | Collection slip already paid. | Fatura de recolhimento já paga. | | 400 | BIP000035 | Bad Request | Covenant slip invalid barcode. | Código de barras da fatura de recolhimento inválido. | | 400 | BIP000036 | Bad Request | Covenant slip overdue. | Fatura de recolhimento vencida. | | 400 | BIP000037 | Bad Request | Error in collection slip consultation. | Erro na consulta da fatura de recolhimento. | | 400 | BIP000038 | Bad Request | Outside of covenant payment hours. | Fora do horário de pagamento do convênio. | | 400 | BIP000039 | Bad Request | Collection slip not accepted. | Fatura de recolhimento não aceita. | | 400 | BIP000040 | Bad Request | Minimum advance not reached. | Mínimo de dias de adiantamento não atingido. | | 400 | BIP000041 | Bad Request | Max payment amount exceeded. | Valor máximo de pagamento excedido. | | 400 | BIP000044 | Bad Request | It was not possible to pay the collection slip at this time. Please verify your information and, if necessary, contact us for assistance. | Não foi possível pagar a fatura de recolhimento neste momento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para assistência. | | 403 | BIP000052 | Forbidden | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta | | 400 | BIP000053 | Bad Request | Error getting approver data | Erro ao obter dados do aprovador | | 400 | BIP000054 | Bad Request | TFA info required | Informações de TFA necessárias | | 400 | BIP000055 | Bad Request | Error sending verification token | Erro ao enviar token de verificação | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. | | 400 | BIP000079 | Bad Request | A session_id must be provided token | Uma session_id deve ser fornecida | ## Ambiente de Sandbox Em nosso ambiente de sandbox, disponibilizamos linhas digitáveis mockadas para a simulação de pagamentos bem-sucedidos e testes de cenários de erro. | Linha digitável | |---| | 828300000007411100972013905080001546763201900028 | | 838000000009235700481007241345219112001474229880 | | 848000000006308600802021201071261517689002201070 | | 858200000015000000643025703477209504800448091020 | | 858500000037350000643217212883260006147448091022 | --- # Reenviar Token Autenticação de Dois Fatores de Pagamentos de Boleto Bancário URL: /documentation/baas/cobranca/2fa_v2/solicitacao_de_reenvio_de_token_de_boleto_bancario Este endpoint permite realizar o reenvio do token de autenticação de pagamentos de Boleto Bancário. :::info Boleto bancário É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central. ::: ## Request ### Request Endpoint ENDPOINT /account/ ACCOUNT_KEY /payment/ PAYMENT_KEY /bank_slip/resend_token MÉTODO PATCH ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |-----------------|-------|--------------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | | `payment_key` * | uuid4 | Chave única de identificação do pagamento. | 36 | ### Body Params | Campo | Tipo | Descrição | Caracteres | |----------------|------------|-----------------------------------------|---------------------------------------------------------| | `contact_type` | enumerator | Forma de envio do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** | :::info Informação Caso não seja enviado um `contact_type`, o token será enviado da forma solicitada originalmente. ::: | Enumerador | Descrição | |------------|---------------------------------------------------| | **sms** | Envio por Mensagem de Texto para telefone celular | | **email** | Envio por correio eletrônico | ## Response ### Success Response STATUS 200 Response Body: Token reenviado com sucesso ```json { "payment_key": "c4325104-d60b-44f3-aae4-49155564a2ea", "request_control_key": "b713b2f6-2f48-4d18-b0c9-7186e4edf189", "payer_name": "COOPERATIVA INDUSTRIAL MURILO", "payer_document_number": "00037025000160", "source_account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f", "transaction_key": "4e80070a-a0bb-4be2-8178-55fbd73a3704", "transaction_revert_key": null, "paid_amount": 1050.1, "payment_date": "2024-04-03", "payment_type": "bank_slip", "bank_slip": { "bank_slip_key": "95080ffd-3ac5-48d7-b3fe-659e4aaba81a", "barcode": "00193967000009910000000003615574000000002417", "digitable_line": "00190000090361557400500000024174396700000991000", "payer_name": "COOPERATIVA TESTE", "payer_document_number": "00037025000160", "beneficiary_name": "TESTE EQUIPAMENTOS E SERVICOS LTDA", "beneficiary_trading_name": "TESTE EQUIPAMENTOS E SERVICOS LTDA", "beneficiary_document_number": "52069937000117", "beneficiary_bank_ispb": "00000000", "guarantor_name": null, "guarantor_document_number": null, "expiration_date": "2024-03-29", "max_payment_data": "2026-03-29", "partial_payment_indicator": "allowed", "registered_payment_amount": 9029.0, "nominal_amount": 9910.0, "total_amount": 10129.1, "rebate_amount": 0.0, "discount_amount": 0.0, "fine_amount": 0.0, "interest_amount": 219.1 }, "collection_slip": null, "payment_status": "pending_2fa_approval" } ``` ### Response Body Params | Campo | Tipo | Descrição | |---------------------------|--------------------------------------|-----------------------------------------------------| | `payment_key` * | uuid4 | Chave única de identificação do pagamento. | | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente. | | `payer_name` * | string | Nome do pagador efetivo. | | `payer_document_number` * | string | Número documento do pagador efetivo (CPF/CNPJ). | | `source_account_key` * | uuid4 | Chave da conta debitada. | | `transaction_key` * | uuid4 | Chave da transação do pagamento. | | `transaction_revert_key` | uuid4 | Chave da transação de reversão do pagamento. | | `paid_amount` * | number | Valor pago efetivamente. | | `payment_date` * | string | Data do pagamento. | | `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. | | `bank_slip` | [object](#objeto-bank_slip) | Boleto bancário. | | `collection_slip` | object | Fatura de recolhimento. | | `payment_status` * | [enum](#enumeradores-payment_status) | Status do pagamento. | ### Enumeradores payment_type | Enumerador | Tipo | Descrição | |-------------------|--------|------------------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | :::danger Aviso O enumerador `collection_slip` não se aplica para o fluxo de boletos bancários, assim como o objeto collection_slip que sempre será nulo. ::: ### Enumeradores payment_status | Enumerador | Descrição | |------------------------|---------------------------------------| | `pending_2fa_approval` | pendente de aprovação de dois fatores | ### Objeto bank_slip | Campo | Tipo | Descrição | |---------------------------------|-------------------------------------------------|-----------------------------------------------------| | `barcode` * | string | Código de barras. | | `digitable_line` * | string | Linha digitável. | | `payer_name` * | string | Nome do pagador. | | `payer_document_number` * | string | Número de documento do pagador (CPF/CNPJ). | | `beneficiary_name` * | string | Nome do beneficiário. | | `beneficiary_trading_name` | string | Nome fantasia do beneficiário. | | `beneficiary_document_number` * | string | Número de documento do beneficiário (CPF/CNPJ). | | `beneficiary_bank_ispb` * | string | Código ispb do banco do beneficiário. | | `guarantor_name` | string | Nome do sacador avalista. | | `guarantor_document_number` | string | Número de documento do sacador avalista (CPF/CNPJ). | | `expiration_date` * | string | Data de vencimento. | | `max_payment_date` * | string | Data máxima de pagamento. | | `partial_payment_indicator` * | [enum](#enumeradores-partial_payment_indicator) | Indicador de pagamento parcial. | | `registered_payment_amount` | string | Valor total de pagamento registrado. | | `nominal_amount` * | number | Valor original. | | `total_amount` * | number | Valor total. | | `rebate_amount` * | number | Valor do abatimento. | | `discount_amount` * | number | Valor do desconto. | | `fine_amount` * | number | Valor da multa. | | `interest_amount` * | number | Valor do juros. | ### Enumeradores partial_payment_indicator | Enumerador | Tipo | Descrição | |---------------|--------|---------------| | `allowed` | string | Permitido | | `not_allowed` | string | Não permitido | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|-------------|----------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------| | 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação | | 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. | | 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. | | 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. | | 400 | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. | | 404 | BIP000056 | Not Found | Payment not found. | Pagamento não encontrado. | | 400 | BIP000057 | Bad Request | Payment status is not pending approval. | Status de pagamento não é de aprovação pendente. | | 400 | BIP000062 | Bad Request | Payment type is not bank slip. | Tipo de pagamento não é boleto. | | 400 | BIP000064 | Bad Request | Error resending verification token | Erro ao reenviar token de verificação | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. | --- # Reenviar Token de Autenticação de Dois Fatores para Pagamentos de Fatura de Recolhimento URL: /documentation/baas/cobranca/2fa_v2/solicitacao_de_reenvio_de_token_de_fatura_de_recolhimento Este endpoint permite realizar o reenvio do token de autenticação de pagamentos de faturas de recolhimento. :::info Fatura de recolhimento Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgão públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta. ::: ## Request ### Request Endpoint ENDPOINT /account/ ACCOUNT_KEY /payment/ PAYMENT_KEY /collection_slip/resend_token MÉTODO PATCH ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | | `payment_key` * | uuid4 | Chave única de identificação do pagamento. | 36 | ### Body Params | Campo | Tipo | Descrição | Caracteres | |----------------|--------|-------------------------------------------------------------------------------------------|------------| | `contact_type` | enumerator | Forma de envio do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** | :::info Informação Caso não seja enviado um `contact_type`, o token será enviado da forma solicitada originalmente. ::: | Enumerador | Descrição | |------------|---------------------------------------------------| | **sms** | Envio por Mensagem de Texto para telefone celular | | **email** | Envio por correio eletrônico | ## Response ### Success Response STATUS 200 Response Body: Token reenviado com sucesso ```json { "payment_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a", "request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9", "payer_name": "COOPERATIVA INDUSTRIAL MURILO", "payer_document_number": "62069937000118", "source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72", "transaction_key": "fc9ccfd0-2f21-4207-9772-69238be74152", "transaction_revert_key": null, "paid_amount": 1389.21, "payment_date": "2024-04-30", "payment_type": "collection_slip", "bank_slip": null, "collection_slip": { "barcode": null, "digitable_line": "836200000138892100450006762142420244046000010192", "collection_name": "CIA ULTRAGAZ SA-COD", "collection_document_number": "00394460005887", "expiration_date": "2024-04-15", "total_amount": 1389.21 }, "payment_status": "pending_2fa_approval" } ``` ### Response Body Params | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------| | `payment_key` * | uuid4 | Chave única de identificação do pagamento. | | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente. | | `payer_name` * | string | Nome do pagador efetivo.| | `payer_document_number` * | string | Número de documento do pagador efetivo (CPF/CNPJ). | | `source_account_key` * | uuid4 | Chave da conta debitada. | | `transaction_key` * | uuid4 | Chave da transação do pagamento. | | `transaction_revert_key` | uuid4 | Chave da transação de reversão do pagamento. | | `paid_amount` * | number | Valor pago efetivamente. | | `payment_date` * | string | Data do pagamento. | | `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. | | `bank_slip` | object | Boleto bancário. | | `collection_slip` | [object](#objeto-collection_slip) | Fatura de recolhimento. | | `payment_status` * | [enum](#enumeradores-payment_status) | Status do pagamento. | ### Enumeradores payment_type | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | :::danger Aviso O enumerador `bank_slip` não se aplica para o fluxo de faturas de recolhimento, assim como o objeto bank_slip que sempre será nulo. ::: ### Enumeradores payment_status | Enumerador | Descrição | |---------------|---------------| | `pending_2fa_approval` | pendente de aprovação de dois fatores | ### Objeto collection_slip | Campo | Tipo | Descrição | |-----------------------------------|---------|-----------------------------------| | `barcode` | string | Código de barras. | | `digitable_line` | string | Linha digitável. | | `collection_name` * | string | Nome do convênio.| | `collection_document_number` | string | Número de documento do convênio (CPF/CNPJ).| | `expiration_date` * | string | Data de vencimento. | | `total_amount` * | number | Valor total. | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação | | 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. | | 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. | | 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. | | 400 | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. | | 404 | BIP000056 | Not Found | Payment not found. | Pagamento não encontrado. | | 400 | BIP000057 | Bad Request | Payment status is not pending approval. | Status de pagamento não é de aprovação pendente. | | 400 | BIP000063 | Bad Request | Payment type is not collection slip. | Tipo de pagamento não é fatura de recolhimento. | | 400 | BIP000064 | Bad Request | Error resending verification token | Erro ao reenviar token de verificação | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. | --- # Reenviar token de confirmação de lote de pagamento de boleto bancário URL: /documentation/baas/cobranca/2fa_v2/solicitacao_de_reenvio_de_token_de_lote_de_boleto_bancario Este endpoint permite **reenviar** o token de autenticação de dois fatores (2FA) para um lote de boletos bancários que esteja aguardando validação do token. Um novo token é gerado e enviado ao aprovador. Se o **limite de tentativas de validação** do token tiver sido excedido, o reenvio pode não ser permitido. :::info Boleto bancário É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/payment/batch_bank_slip/**PAYMENT_BATCH_KEY**/resend_token MÉTODO PATCH ### Request Path Params | Campo | Tipo | Descrição | Caracteres | | --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- | | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | | `payment_batch_key` * | uuid4 | Chave única de identificação do lote (`batch_payment_key` retornado na criação do lote). | 36 | ### Request Body Request Body (opcional) ```json { "contact_type": "sms" } ``` ### Body Params | Campo | Tipo | Descrição | Caracteres | | -------------- | ---------- | --------------------------------------- | ------------------------------------------------------- | | `contact_type` | enumerator | Forma de envio do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** | :::info Informação Caso não seja enviado um `contact_type`, o token será enviado da forma solicitada originalmente (`tfa_info.contact_type`). ::: ### Enumerador contact_type | Enumerador | Descrição | | ---------- | ------------------------------------------------- | | **sms** | Envio por mensagem de texto para telefone celular | | **email** | Envio por correio eletrônico | ## Response ### Success Response STATUS 200 Response Body: Token reenviado com sucesso ```json { "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f", "total_amount": 1357.3, "batch_status": "pending_2fa_approval", "payment_type": "bank_slip" } ``` ### Response Body Params | Campo | Tipo | Descrição | | ----------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `batch_payment_key` * | uuid4 | Chave única de identificação do pagamento em lote. | | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `account_key` * | uuid4 | Chave da conta debitada. | | `total_amount` * | number | Soma dos valores dos itens do lote. | | `batch_status` * | string | Após o reenvio, o lote permanece aguardando validação do token. O ciclo de `batch_status` está alinhado ao descrito na documentação de **solicitação de pagamento em lote** fornecida à operação (enumeradores `batch_payment_status`). | | `payment_type` * | string | Tipo do pagamento; para este fluxo, espera-se `bank_slip`. | Em seguida, utilize [Validação de token de lote de pagamento de boleto bancário](./validacao_de_token_de_lote_de_boleto_bancario.md) para concluir o 2FA. ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | | ----------- | --------- | ----------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação | | 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. | | 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. | | 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. | | 400 | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. | | 400 | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Número de tentativas de validação de token de verificação excedido. | | 400 | BIP000064 | Bad Request | Error resending verification token | Erro ao reenviar token de verificação | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. | | 404 | BIP000083 | Not Found | Batch payment not found by batch payment key. | Lote de pagamentos não encontrado pela chave do lote. | | 400 | BIP000085 | Bad Request | Batch payment status is not pending approval. | Status do lote de pagamentos não é de aprovação pendente. | | 400 | BIP000086 | Bad Request | A token is required for SMS or email validation. | Um token é necessário para validação via SMS ou email. | --- # Reenviar token de confirmação de lote de pagamento de fatura de recolhimento (convênio/tributo) URL: /documentation/baas/cobranca/2fa_v2/solicitacao_de_reenvio_de_token_de_lote_de_fatura_de_recolhimento Este endpoint permite **reenviar** o token de autenticação de dois fatores (2FA) para um lote de faturas de recolhimento que esteja aguardando validação do token. Um novo token é gerado e enviado ao aprovador. Se o **limite de tentativas de validação** do token tiver sido excedido, o reenvio pode não ser permitido. :::info Fatura de recolhimento Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/payment/batch_collection_slip/**PAYMENT_BATCH_KEY**/resend_token MÉTODO PATCH ### Request Path Params | Campo | Tipo | Descrição | Caracteres | | --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- | | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | | `payment_batch_key` * | uuid4 | Chave única de identificação do lote (`batch_payment_key` retornado na criação do lote). | 36 | ### Request Body Request Body (opcional) ```json { "contact_type": "sms" } ``` ### Body Params | Campo | Tipo | Descrição | Caracteres | | -------------- | ---------- | --------------------------------------- | ------------------------------------------------------- | | `contact_type` | enumerator | Forma de envio do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** | :::info Informação Caso não seja enviado um `contact_type`, o token será enviado da forma solicitada originalmente (`tfa_info.contact_type`). ::: ### Enumerador contact_type | Enumerador | Descrição | | ---------- | ------------------------------------------------- | | **sms** | Envio por mensagem de texto para telefone celular | | **email** | Envio por correio eletrônico | ## Response ### Success Response STATUS 200 Response Body: Token reenviado com sucesso ```json { "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72", "total_amount": 2778.42, "batch_status": "pending_2fa_approval", "payment_type": "collection_slip" } ``` ### Response Body Params | Campo | Tipo | Descrição | | ----------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `batch_payment_key` * | uuid4 | Chave única de identificação do pagamento em lote. | | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `account_key` * | uuid4 | Chave da conta debitada. | | `total_amount` * | number | Soma dos valores dos itens do lote. | | `batch_status` * | string | Após o reenvio, o lote permanece aguardando validação do token. O ciclo de `batch_status` está alinhado ao descrito na documentação de **solicitação de pagamento em lote** fornecida à operação (enumeradores `batch_payment_status`). | | `payment_type` * | string | Tipo do pagamento; para este fluxo, espera-se `collection_slip`. | Em seguida, utilize [Validação de token de lote de pagamento de fatura de recolhimento (convênio/tributo)](./validacao_de_token_de_lote_de_fatura_de_recolhimento.md) para concluir o 2FA. ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | | ----------- | --------- | ----------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação | | 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. | | 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. | | 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. | | 400 | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. | | | 400 | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Número de tentativas de validação de token de verificação excedido. | | 400 | BIP000064 | Bad Request | Error resending verification token | Erro ao reenviar token de verificação | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. | | 404 | BIP000083 | Not Found | Batch payment not found by batch payment key. | Lote de pagamentos não encontrado pela chave do lote. | | 400 | BIP000085 | Bad Request | Batch payment status is not pending approval. | Status do lote de pagamentos não é de aprovação pendente. | 400 | BIP000086 | Bad Request | A token is required for SMS or email validation. | Um token é necessário para validação via SMS ou email. | --- # Solicitar pagamento em lote de boleto bancário com autenticação de dois fatores URL: /documentation/baas/cobranca/2fa_v2/solicitar_pagamento_lote_de_boleto_bancario_com_confirmacao_de_lote Este endpoint permite solicitar o pagamento de múltiplos boletos bancários em uma única requisição, com **`tfa_info`** quando a operação exigir autenticação de dois fatores **nesta solicitação**. :::info Boleto bancário É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central. ::: :::info Fluxo após a solicitação Após a solicitação, o lote pode permanecer aguardando a [confirmação do lote com autenticação de dois fatores](./confirmacao_de_lote_de_boleto_bancario.md), conforme as regras da operação. Nesta etapa de confirmação, siga o fluxo com `tfa_info` descrito nessa documentação. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments/batch_bank_slip MÉTODO POST ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | Request Body: Pagamento em lote de boletos bancários (sem TFA nesta etapa) ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "bank_slip_payments": [ { "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd", "digitable_line": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8 }, { "request_control_key": "d8a26b54-323a-4924-0aed-e4fe6e4e4c0e", "barcode": "00190000090361557400500000024174396700000991000", "payment_amount": 200.5 } ] } ``` ### Body Params | Campo | Tipo | Descrição | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `bank_slip_payments` * | array | Lista de pagamentos de boleto bancário. Limite de **1000** itens por requisição. | Cada elemento de `bank_slip_payments` deve conter: | Campo | Tipo | Descrição | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente para aquele item do lote. | | `barcode` | string | Código de barras. | | `digitable_line` | string | Linha digitável. | | `payment_amount` * | number | Valor a ser pago. | :::danger Aviso Para cada item, o `payment_amount` enviado deve ser compatível com o que a consulta interna do boleto determinar: se o pagamento parcial **não** for permitido para aquele título, o valor deve corresponder ao total atualizado; se for permitido, o `payment_amount` pode seguir as regras do título (incluindo, quando aplicável, valores acima do nominal), como no fluxo de pagamento unitário de boleto bancário. ::: ### Objeto tfa_info | Campo | Tipo | Descrição | | ---------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `approver_document_number` * | string | Documento (CPF/CNPJ) da pessoa aprovadora que receberá o token ou aprovará via dispositivo. Obrigatório quando `tfa_info` é enviado. | | `session_id` | string | Chave única de identificação da sessão do dispositivo no formato UUID v4 (**obrigatório** para TFA via dispositivo). | | `contact_type` * | string | Canal para envio ou validação do token: **[Enumerador contact_type](#enumerador-contact_type)**. Obrigatório quando `tfa_info` é enviado. | #### Enumerador contact_type | Enumerador | Descrição | |------------|---------------------------------------------------| | **sms** | Envio por mensagem de texto para telefone celular | | **email** | Envio por correio eletrônico | | **device** | Validação por token do dispositivo | ## Response ### Success Response STATUS 202 Response Body: Lote aceito para processamento ```json { "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f", "total_amount": 1357.3, "batch_status": "pending", "payment_type": "bank_slip" } ``` Response Body: exemplo ilustrativo (`batch_status` aprovado) ```json { "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f", "total_amount": 1357.3, "batch_status": "approved", "payment_type": "bank_slip" } ``` :::info Processamento do lote O campo `batch_status` na resposta indica o **estado imediato** do lote após esta solicitação (por exemplo, pendente de confirmação, pendente de aprovação 2FA ou já encaminhado ao processamento), conforme o fluxo aplicável. Quando houver etapa de [confirmação do lote](./confirmacao_de_lote_de_boleto_bancario.md), siga essa documentação para aprovar ou rejeitar o lote com autenticação de dois fatores. Os valores possíveis de `batch_status` estão em [batch_payment_status](#enumeradores-batch_payment_status). ::: ### Response Body Params | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------| | `batch_payment_key` * | uuid4 | Chave única de identificação do pagamento em lote. | | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `account_key` * | uuid4 | Chave da conta debitada. | | `total_amount` * | number | Soma dos valores (`payment_amount`) dos itens do lote. | | `batch_status` * | [enum](#enumeradores-batch_payment_status) | Status do lote logo após a solicitação; depende do fluxo (confirmação, 2FA e processamento imediato). | | `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. | ### Enumeradores batch_payment_status | Enumerador | Descrição | |---------------|---------------| | `pending` | Pendente de processamento | | `pending_2fa_approval` | Pendente de aprovação 2FA | | `rejected` | Rejeitado | | `approved` | Aprovado | | `processed` | Processado | ### Enumeradores payment_type | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | :::danger Aviso O enumerador `collection_slip` não se aplica ao fluxo de lote de boletos bancários deste endpoint; para este caso, espera-se `payment_type` com valor `bank_slip`. ::: ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação | | 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. | | 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. | | 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. | | 400 | BIP000050 | Bad Request | Requester configuration does not exist. | Configuração do requester não existe. | | 400 | BIP000052 | Bad Request | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta | | 400 | BIP000053 | Bad Request | Error getting approver data | Erro ao obter dados do aprovador | | 400 | BIP000054 | Bad Request | TFA info required | Informações de TFA necessárias | | 400 | BIP000055 | Bad Request | Error sending verification token | Erro ao enviar token de verificação | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. | | 400 | BIP000079 | Bad Request | A session_id must be provided token | Uma session_id deve ser fornecida | | 400 | BIP000080 | Bad Request | Beneficiary bank code of this bank slip is not allowed. | Banco beneficiário desse boleto não é permitido. | | 400 | BIP000081 | Bad Request | A list of bank slip payments must be provided. | Uma lista de boletos bancários deve ser fornecida. | --- # Solicitar pagamento em lote de boleto bancário com autenticação de dois fatores URL: /documentation/baas/cobranca/2fa_v2/solicitar_pagamento_lote_de_boleto_bancario_sem_confirmacao_de_lote Este endpoint permite solicitar o pagamento de múltiplos boletos bancários em uma única requisição, com **`tfa_info`** quando a operação exigir autenticação de dois fatores **nesta solicitação**. :::info Boleto bancário É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments/batch_bank_slip MÉTODO POST ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | ## Autenticação via email e SMS Request Body: lote com linha digitável e TFA por SMS ou email ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "tfa_info": { "approver_document_number": "98765432100", "contact_type": "email" }, "bank_slip_payments": [ { "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd", "digitable_line": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8 } ] } ``` Request Body: lote com código de barras e TFA por SMS ou email ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "tfa_info": { "approver_document_number": "98765432100", "contact_type": "email" }, "bank_slip_payments": [ { "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd", "barcode": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8 } ] } ``` ## Autenticação via dispositivo Além das formas já existentes de autenticação via **sms** e **email**, é possível autenticar a transação utilizando um dispositivo [previamente cadastrado](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). Nesse caso, o `session_id` deve ser obtido na **Device Scan** e enviado no `tfa_info`. Request Body: lote com linha digitável e TFA por dispositivo ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "tfa_info": { "approver_document_number": "98765432100", "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72", "contact_type": "device" }, "bank_slip_payments": [ { "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd", "digitable_line": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8 } ] } ``` Request Body: lote com código de barras e TFA por dispositivo ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "tfa_info": { "approver_document_number": "98765432100", "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72", "contact_type": "device" }, "bank_slip_payments": [ { "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd", "barcode": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8 } ] } ``` ### Body Params | Campo | Tipo | Descrição | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `tfa_info` | object | Quando o 2FA for exigido **nesta etapa** (solicitação do lote), envie aprovador e canal de envio do token no [objeto `tfa_info`](#objeto-tfa_info). Caso o fluxo não exija 2FA na solicitação, omita o campo. | | `bank_slip_payments` * | array | Lista de pagamentos de boleto bancário. Limite de **1000** itens por requisição. | Cada elemento de `bank_slip_payments` deve conter: | Campo | Tipo | Descrição | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente para aquele item do lote. | | `barcode` | string | Código de barras. | | `digitable_line` | string | Linha digitável. | | `payment_amount` * | number | Valor a ser pago. | :::danger Aviso Para cada item, o `payment_amount` enviado deve ser compatível com o que a consulta interna do boleto determinar: se o pagamento parcial **não** for permitido para aquele título, o valor deve corresponder ao total atualizado; se for permitido, o `payment_amount` pode seguir as regras do título (incluindo, quando aplicável, valores acima do nominal), como no fluxo de pagamento unitário de boleto bancário. ::: ### Objeto tfa_info | Campo | Tipo | Descrição | | ---------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `approver_document_number` * | string | Documento (CPF/CNPJ) da pessoa aprovadora que receberá o token ou aprovará via dispositivo. Obrigatório quando `tfa_info` é enviado. | | `session_id` | string | Chave única de identificação da sessão do dispositivo no formato UUID v4 (**obrigatório** para TFA via dispositivo). | | `contact_type` * | string | Canal para envio ou validação do token: **[Enumerador contact_type](#enumerador-contact_type)**. Obrigatório quando `tfa_info` é enviado. | #### Enumerador contact_type | Enumerador | Descrição | |------------|---------------------------------------------------| | **sms** | Envio por mensagem de texto para telefone celular | | **email** | Envio por correio eletrônico | | **device** | Validação por token do dispositivo | ## Response ### Success Response STATUS 201 Response Body: Lote pendente de aprovação de dois fatores ```json { "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f", "total_amount": 1357.3, "batch_status": "pending_2fa_approval", "payment_type": "bank_slip" } ``` :::info Processamento do lote O campo `batch_status` na resposta indica o **estado imediato** do lote após esta solicitação (por exemplo, pendente de aprovação 2FA ou já encaminhado ao processamento), conforme o fluxo aplicável. O 2FA pode integrar esta solicitação (`tfa_info`) ou outras etapas do fluxo, conforme a operação. Os valores possíveis de `batch_status` estão em [batch_payment_status](#enumeradores-batch_payment_status). ::: ### Response Body Params | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------| | `batch_payment_key` * | uuid4 | Chave única de identificação do pagamento em lote. | | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `account_key` * | uuid4 | Chave da conta debitada. | | `total_amount` * | number | Soma dos valores (`payment_amount`) dos itens do lote. | | `batch_status` * | [enum](#enumeradores-batch_payment_status) | Status do lote logo após a solicitação; depende do fluxo (2FA e processamento imediato). | | `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. | ### Enumeradores batch_payment_status | Enumerador | Descrição | |---------------|---------------| | `pending` | Pendente de processamento | | `pending_2fa_approval` | Lote pendente de 2FA para aprovação | | `pending_2fa_rejection` | Lote pendente de 2FA para rejeição | | `rejected` | Rejeitado | | `approved` | Aprovado | | `processed` | Processado | ### Enumeradores payment_type | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | :::danger Aviso O enumerador `collection_slip` não se aplica ao fluxo de lote de boletos bancários deste endpoint; para este caso, espera-se `payment_type` com valor `bank_slip`. ::: ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação | | 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. | | 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. | | 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. | | 400 | BIP000050 | Bad Request | Requester configuration does not exist. | Configuração do requester não existe. | | 400 | BIP000052 | Bad Request | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta | | 400 | BIP000053 | Bad Request | Error getting approver data | Erro ao obter dados do aprovador | | 400 | BIP000054 | Bad Request | TFA info required | Informações de TFA necessárias | | 400 | BIP000055 | Bad Request | Error sending verification token | Erro ao enviar token de verificação | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. | | 400 | BIP000079 | Bad Request | A session_id must be provided token | Uma session_id deve ser fornecida | | 400 | BIP000080 | Bad Request | Beneficiary bank code of this bank slip is not allowed. | Banco beneficiário desse boleto não é permitido. | | 400 | BIP000081 | Bad Request | A list of bank slip payments must be provided. | Uma lista de boletos bancários deve ser fornecida. | --- # Solicitar pagamento em lote de fatura de recolhimento (convênio/tributo) com autenticação de dois fatores URL: /documentation/baas/cobranca/2fa_v2/solicitar_pagamento_lote_de_fatura_de_recolhimento_com_confirmacao_de_lote Este endpoint permite solicitar o pagamento de múltiplas faturas de recolhimento em uma única requisição, com **`tfa_info`** quando a operação exigir autenticação de dois fatores **nesta solicitação**. :::info Fatura de recolhimento Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um boleto bancário apresenta. ::: :::info Fluxo após a solicitação Após a solicitação, o lote pode permanecer aguardando a [confirmação do lote com autenticação de dois fatores](./confirmacao_de_lote_de_fatura_de_recolhimento.md), conforme as regras da operação. Quando o 2FA for exigido nesta solicitação, o corpo deve incluir **`tfa_info`** conforme as seções abaixo e o [objeto `tfa_info`](#objeto-tfa_info). Na etapa de confirmação do lote deste fluxo, siga a documentação com `tfa_info`. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments/batch_collection_slip MÉTODO POST ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | Request Body: Pagamento em lote de faturas de recolhimento (sem TFA nesta etapa) ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "collection_slip_payments": [ { "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd", "digitable_line": "836200000138892100450006762142420244046000010192", "payment_amount": 1389.21 }, { "request_control_key": "d8a26b54-323a-4924-0aed-e4fe6e4e4c0e", "barcode": "83620000001388921004500067621424202440460000101", "payment_amount": 1389.21 } ] } ``` ## Autenticação via email e SMS Request Body: lote com linha digitável e TFA por SMS ou email ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "tfa_info": { "approver_document_number": "98765432100", "contact_type": "email" }, "collection_slip_payments": [ { "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd", "digitable_line": "836200000138892100450006762142420244046000010192", "payment_amount": 1389.21 } ] } ``` Request Body: lote com código de barras e TFA por SMS ou email ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "tfa_info": { "approver_document_number": "98765432100", "contact_type": "email" }, "collection_slip_payments": [ { "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd", "barcode": "83620000001388921004500067621424202440460000101", "payment_amount": 1389.21 } ] } ``` ## Autenticação via dispositivo Além das formas já existentes de autenticação via **sms** e **email**, é possível autenticar a transação utilizando um dispositivo [previamente cadastrado](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). Nesse caso, o `session_id` deve ser obtido na **Device Scan** e enviado no `tfa_info`. Request Body: lote com linha digitável e TFA por dispositivo ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "tfa_info": { "approver_document_number": "98765432100", "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72", "contact_type": "device" }, "collection_slip_payments": [ { "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd", "digitable_line": "836200000138892100450006762142420244046000010192", "payment_amount": 1389.21 } ] } ``` Request Body: lote com código de barras e TFA por dispositivo ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "tfa_info": { "approver_document_number": "98765432100", "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72", "contact_type": "device" }, "collection_slip_payments": [ { "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd", "barcode": "83620000001388921004500067621424202440460000101", "payment_amount": 1389.21 } ] } ``` ### Body Params | Campo | Tipo | Descrição | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `tfa_info` | object | Quando o 2FA for exigido **nesta etapa** (solicitação do lote), envie aprovador e canal de envio do token no [objeto `tfa_info`](#objeto-tfa_info). Caso o fluxo não exija 2FA na solicitação, omita o campo. | | `collection_slip_payments` * | array | Lista de pagamentos de fatura de recolhimento. Limite de **1000** itens por requisição. | Cada elemento de `collection_slip_payments` deve conter: | Campo | Tipo | Descrição | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente para aquele item do lote. | | `barcode` | string | Código de barras. | | `digitable_line` | string | Linha digitável. | | `payment_amount` * | number | Valor a ser pago. | :::danger Aviso Para cada item, o `payment_amount` enviado deve ser compatível com o que a consulta interna da fatura de recolhimento determinar (por exemplo, alinhado ao `total_amount` e às regras do convênio/tributo), nas mesmas condições do fluxo de pagamento unitário de fatura de recolhimento. ::: ### Objeto tfa_info | Campo | Tipo | Descrição | | ---------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `approver_document_number` * | string | Documento (CPF/CNPJ) da pessoa aprovadora que receberá o token ou aprovará via dispositivo. Obrigatório quando `tfa_info` é enviado. | | `session_id` | string | Chave única de identificação da sessão do dispositivo no formato UUID v4 (**obrigatório** para TFA via dispositivo). | | `contact_type` * | string | Canal para envio ou validação do token: **[Enumerador contact_type](#enumerador-contact_type)**. Obrigatório quando `tfa_info` é enviado. | #### Enumerador contact_type | Enumerador | Descrição | |------------|---------------------------------------------------| | **sms** | Envio por mensagem de texto para telefone celular | | **email** | Envio por correio eletrônico | | **device** | Validação por token do dispositivo | ## Response ### Success Response STATUS 202 Response Body: Lote aceito para processamento ```json { "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72", "total_amount": 2778.42, "batch_status": "pending", "payment_type": "collection_slip" } ``` Response Body: exemplo ilustrativo (`batch_status` aprovado) ```json { "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72", "total_amount": 2778.42, "batch_status": "approved", "payment_type": "collection_slip" } ``` :::info Processamento do lote O campo `batch_status` na resposta indica o **estado imediato** do lote após esta solicitação (por exemplo, pendente de confirmação, pendente de aprovação 2FA ou já encaminhado ao processamento), conforme o fluxo aplicável. Quando houver etapa de [confirmação do lote](./confirmacao_de_lote_de_fatura_de_recolhimento.md), siga essa documentação para aprovar ou rejeitar o lote com autenticação de dois fatores. Os valores possíveis de `batch_status` estão em [batch_payment_status](#enumeradores-batch_payment_status). ::: ### Response Body Params | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------| | `batch_payment_key` * | uuid4 | Chave única de identificação do pagamento em lote. | | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `account_key` * | uuid4 | Chave da conta debitada. | | `total_amount` * | number | Soma dos valores (`payment_amount`) dos itens do lote. | | `batch_status` * | [enum](#enumeradores-batch_payment_status) | Status do lote logo após a solicitação; depende do fluxo (confirmação, 2FA e processamento imediato). | | `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. | ### Enumeradores batch_payment_status | Enumerador | Descrição | |---------------|---------------| | `pending` | Pendente de processamento | | `pending_2fa_approval` | Pendente de aprovação 2FA | | `rejected` | Rejeitado | | `approved` | Aprovado | | `processed` | Processado | ### Enumeradores payment_type | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | :::danger Aviso O enumerador `bank_slip` não se aplica ao fluxo de lote de faturas de recolhimento deste endpoint; para este caso, espera-se `payment_type` com valor `collection_slip`. ::: ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. | | 400 | BIP000050 | Bad Request | Requester configuration does not exist. | Configuração do requester não existe. | | 400 | BIP000052 | Bad Request | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta | | 400 | BIP000053 | Bad Request | Error getting approver data | Erro ao obter dados do aprovador | | 400 | BIP000054 | Bad Request | TFA info required | Informações de TFA necessárias | | 400 | BIP000055 | Bad Request | Error sending verification token | Erro ao enviar token de verificação | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. | | 400 | BIP000079 | Bad Request | A session_id must be provided token | Uma session_id deve ser fornecida | | 400 | BIP000082 | Bad Request | A list of collection slip payments must be provided. | Uma lista de faturas de recolhimento deve ser fornecida. | --- # Solicitar pagamento em lote de fatura de recolhimento (convênio/tributo) com autenticação de dois fatores URL: /documentation/baas/cobranca/2fa_v2/solicitar_pagamento_lote_de_fatura_de_recolhimento_sem_confirmacao_de_lote Este endpoint permite solicitar o pagamento de múltiplas faturas de recolhimento em uma única requisição, com **`tfa_info`** quando a operação exigir autenticação de dois fatores **nesta solicitação**. :::info Fatura de recolhimento Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um boleto bancário apresenta. ::: :::info Fluxo após a solicitação A **autenticação de dois fatores (2FA)** é exigida **nesta solicitação**; o corpo deve incluir **`tfa_info`** conforme as seções abaixo e o [objeto `tfa_info`](#objeto-tfa_info). ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments/batch_collection_slip MÉTODO POST ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | ## Autenticação via email e SMS Request Body: lote com linha digitável e TFA por SMS ou email ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "tfa_info": { "approver_document_number": "98765432100", "contact_type": "email" }, "collection_slip_payments": [ { "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd", "digitable_line": "836200000138892100450006762142420244046000010192", "payment_amount": 1389.21 } ] } ``` Request Body: lote com código de barras e TFA por SMS ou email ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "tfa_info": { "approver_document_number": "98765432100", "contact_type": "email" }, "collection_slip_payments": [ { "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd", "barcode": "83620000001388921004500067621424202440460000101", "payment_amount": 1389.21 } ] } ``` ## Autenticação via dispositivo Além das formas já existentes de autenticação via **sms** e **email**, é possível autenticar a transação utilizando um dispositivo [previamente cadastrado](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). Nesse caso, o `session_id` deve ser obtido na **Device Scan** e enviado no `tfa_info`. Request Body: lote com linha digitável e TFA por dispositivo ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "tfa_info": { "approver_document_number": "98765432100", "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72", "contact_type": "device" }, "collection_slip_payments": [ { "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd", "digitable_line": "836200000138892100450006762142420244046000010192", "payment_amount": 1389.21 } ] } ``` Request Body: lote com código de barras e TFA por dispositivo ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "tfa_info": { "approver_document_number": "98765432100", "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72", "contact_type": "device" }, "collection_slip_payments": [ { "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd", "barcode": "83620000001388921004500067621424202440460000101", "payment_amount": 1389.21 } ] } ``` ### Body Params | Campo | Tipo | Descrição | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `tfa_info` | object | Quando o 2FA for exigido **nesta etapa** (solicitação do lote), envie aprovador e canal de envio do token no [objeto `tfa_info`](#objeto-tfa_info). Caso o fluxo não exija 2FA na solicitação, omita o campo. | | `collection_slip_payments` * | array | Lista de pagamentos de fatura de recolhimento. Limite de **1000** itens por requisição. | Cada elemento de `collection_slip_payments` deve conter: | Campo | Tipo | Descrição | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente para aquele item do lote. | | `barcode` | string | Código de barras. | | `digitable_line` | string | Linha digitável. | | `payment_amount` * | number | Valor a ser pago. | :::danger Aviso Para cada item, o `payment_amount` enviado deve ser compatível com o que a consulta interna da fatura de recolhimento determinar (por exemplo, alinhado ao `total_amount` e às regras do convênio/tributo), nas mesmas condições do fluxo de pagamento unitário de fatura de recolhimento. ::: ### Objeto tfa_info Os campos seguem o mesmo formato da [solicitação de pagamento de fatura de recolhimento](./solicitacao_de_pagamento_de_fatura_de_recolhimento.md#objeto-tfa_info). | Campo | Tipo | Descrição | | ---------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `approver_document_number` * | string | Documento (CPF/CNPJ) da pessoa aprovadora que receberá o token ou aprovará via dispositivo. Obrigatório quando `tfa_info` é enviado. | | `session_id` | string | Chave única de identificação da sessão do dispositivo no formato UUID v4 (**obrigatório** para TFA via dispositivo). | | `contact_type` * | string | Canal para envio ou validação do token: **[Enumerador contact_type](#enumerador-contact_type)**. Obrigatório quando `tfa_info` é enviado. | #### Enumerador contact_type | Enumerador | Descrição | |------------|---------------------------------------------------| | **sms** | Envio por mensagem de texto para telefone celular | | **email** | Envio por correio eletrônico | | **device** | Validação por token do dispositivo | ## Response ### Success Response STATUS 202 Response Body: Lote aceito para processamento ```json { "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72", "total_amount": 2778.42, "batch_status": "pending", "payment_type": "collection_slip" } ``` Response Body: exemplo ilustrativo com `batch_status` aprovado ```json { "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72", "total_amount": 2778.42, "batch_status": "approved", "payment_type": "collection_slip" } ``` :::info Processamento do lote O campo `batch_status` na resposta indica o **estado imediato** do lote após esta solicitação (por exemplo, pendente de aprovação 2FA ou já encaminhado ao processamento), conforme o fluxo aplicável. O 2FA pode integrar esta solicitação (`tfa_info`) ou outras etapas do fluxo, conforme a operação. Os valores possíveis de `batch_status` estão em [batch_payment_status](#enumeradores-batch_payment_status). ::: ### Response Body Params | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------| | `batch_payment_key` * | uuid4 | Chave única de identificação do pagamento em lote. | | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `account_key` * | uuid4 | Chave da conta debitada. | | `total_amount` * | number | Soma dos valores (`payment_amount`) dos itens do lote. | | `batch_status` * | [enum](#enumeradores-batch_payment_status) | Status do lote logo após a solicitação; depende do fluxo (2FA e processamento imediato). | | `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. | ### Enumeradores batch_payment_status | Enumerador | Descrição | |---------------|---------------| | `pending` | Pendente de processamento | | `pending_2fa_approval` | Pendente de aprovação 2FA | | `rejected` | Rejeitado | | `approved` | Aprovado | | `processed` | Processado | ### Enumeradores payment_type | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | :::danger Aviso O enumerador `bank_slip` não se aplica ao fluxo de lote de faturas de recolhimento deste endpoint; para este caso, espera-se `payment_type` com valor `collection_slip`. ::: ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. | | 400 | BIP000050 | Bad Request | Requester configuration does not exist. | Configuração do requester não existe. | | 400 | BIP000052 | Bad Request | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta | | 400 | BIP000053 | Bad Request | Error getting approver data | Erro ao obter dados do aprovador | | 400 | BIP000054 | Bad Request | TFA info required | Informações de TFA necessárias | | 400 | BIP000055 | Bad Request | Error sending verification token | Erro ao enviar token de verificação | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. | | 400 | BIP000079 | Bad Request | A session_id must be provided token | Uma session_id deve ser fornecida | | 400 | BIP000082 | Bad Request | A list of collection slip payments must be provided. | Uma lista de faturas de recolhimento deve ser fornecida. | --- # Validação de token de lote de pagamento de boleto bancário URL: /documentation/baas/cobranca/2fa_v2/validacao_de_token_de_lote_de_boleto_bancario Este endpoint conclui a etapa de **autenticação de dois fatores (2FA)** para um lote de boletos bancários que, após a [confirmação do lote com `tfa_info`](./confirmacao_de_lote_de_boleto_bancario.md), encontra-se em `batch_status` **`pending_2fa_approval`** (aprovação) ou **`pending_2fa_rejection`** (rejeição). Com o token validado, o lote segue para **processamento assíncrono** dos pagamentos e o status final reflete a decisão registrada na confirmação (`approved` ou `rejected`). Para solicitar novo envio do token enquanto o lote estiver em **pending_2fa_approval** (aprovação) ou **pending_2fa_rejection** (rejeição), use [Reenviar token de confirmação de lote de pagamento de boleto bancário](./solicitacao_de_reenvio_de_token_de_lote_de_boleto_bancario.md). :::info Boleto bancário É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/payment/batch_bank_slip/**PAYMENT_BATCH_KEY**/validate_token MÉTODO PATCH ### Request Path Params | Campo | Tipo | Descrição | Caracteres | | --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- | | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | | `payment_batch_key` * | uuid4 | Chave única de identificação do lote (`batch_payment_key` retornado na criação do lote). | 36 | ### Autenticação via Email e SMS Request Body: Validação de token do lote ```json { "token": "329adf" } ``` ### Autenticação via Dispositivo Para finalizar a autenticação via dispositivo, a requisição deve ser enviada com um payload vazio. A validação ocorre internamente, sem necessidade de informações adicionais no corpo da requisição. Este endpoint só deve ser utilizado após o lote ter entrado em **`pending_2fa_approval`** (aprovação) ou **`pending_2fa_rejection`** (rejeição) na [confirmação do lote com `tfa_info`](./confirmacao_de_lote_de_boleto_bancario.md). Request Body: Validação de token do lote ```json { } ``` ### Body Params | Campo | Tipo | Descrição | Caracteres | | ------- | ------ | ---------------------------------------------------------------------------------------------------------------- | ---------- | | `token` | string | Código de autenticação enviado ao aprovador de movimentações da conta **obrigatório para TFA via SMS ou e-mail** | 6 | ## Response ### Success Response Após a validação bem-sucedida, a API responde com **202** e o lote passa a ser processado de forma assíncrona. O status final segue a decisão registrada na confirmação (`approved` ou `rejected`). STATUS 202 Response Body: Lote após validação do token (exemplo com decisão `approved`) ```json { "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f", "total_amount": 1357.3, "batch_status": "approved", "payment_type": "bank_slip" } ``` ### Response Body Params | Campo | Tipo | Descrição | | ----------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `batch_payment_key` * | uuid4 | Chave única de identificação do pagamento em lote. | | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `account_key` * | uuid4 | Chave da conta debitada. | | `total_amount` * | number | Soma dos valores dos itens do lote. | | `batch_status` * | string | Após validação do token, o status final reflete a decisão registrada na confirmação (`approved` ou `rejected`). O ciclo de `batch_status` está alinhado ao descrito na documentação de **solicitação de pagamento em lote** fornecida à operação (enumeradores `batch_payment_status`). | | `payment_type` * | string | Tipo do pagamento; para este fluxo, espera-se `bank_slip`. | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | | ----------- | --------- | ----------- | --------------------------------------------- | ---------------------------------------------------------------- | | 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação | | 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. | | 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. | | 400 | BIP000050 | Bad Request | Requester configuration does not exist | Configuração do requester não existe. | | 400 | BIP000058 | Bad Request | Error while validating verification token | Erro ao validar token de verificação | | 400 | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Número de tentativas de validação de token de verificação excedido. | | 400 | BIP000060 | Bad Request | Verification token expired. | Token de verificação expirado. | | 400 | BIP000061 | Bad Request | Verification token validation failed. | Falha na validação do token de verificação. | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. | | 404 | BIP000083 | Not Found | Batch payment not found by batch payment key. | Lote de pagamentos não encontrado pela chave do lote. | | 400 | BIP000085 | Bad Request | Batch payment status is not pending approval. | Status do lote de pagamentos não é de aprovação pendente. | | 400 | BIP000086 | Bad Request | A token is required for SMS or email validation. | Um token é necessário para validação via SMS ou email. | --- # Validação de token de lote de pagamento de fatura de recolhimento (convênio/tributo) URL: /documentation/baas/cobranca/2fa_v2/validacao_de_token_de_lote_de_fatura_de_recolhimento Este endpoint conclui a etapa de **autenticação de dois fatores (2FA)** para um lote de faturas de recolhimento que, após a [confirmação do lote com `tfa_info`](./confirmacao_de_lote_de_fatura_de_recolhimento.md), encontra-se em `batch_status` **`pending_2fa_approval`** (aprovação) ou **`pending_2fa_rejection`** (rejeição). Com o token validado, o lote segue para **processamento assíncrono** dos pagamentos e o status final reflete a decisão registrada na confirmação (`approved` ou `rejected`). Para solicitar novo envio do token enquanto o lote estiver em **pending_2fa_approval** (aprovação) ou **pending_2fa_rejection** (rejeição), use [Reenviar token de confirmação de lote de pagamento de fatura de recolhimento (convênio/tributo)](./solicitacao_de_reenvio_de_token_de_lote_de_fatura_de_recolhimento.md). :::info Fatura de recolhimento Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/payment/batch_collection_slip/**PAYMENT_BATCH_KEY**/validate_token MÉTODO PATCH ### Request Path Params | Campo | Tipo | Descrição | Caracteres | | --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- | | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | | `payment_batch_key` * | uuid4 | Chave única de identificação do lote (`batch_payment_key` retornado na criação do lote). | 36 | ### Autenticação via Email e SMS Request Body: Validação de token do lote ```json { "token": "329adf" } ``` ### Autenticação via Dispositivo Para finalizar a autenticação via dispositivo, a requisição deve ser enviada com um payload vazio. A validação ocorre internamente, sem necessidade de informações adicionais no corpo da requisição. Este endpoint só deve ser utilizado após o lote ter entrado em **`pending_2fa_approval`** (aprovação) ou **`pending_2fa_rejection`** (rejeição) na [confirmação do lote com `tfa_info`](./confirmacao_de_lote_de_fatura_de_recolhimento.md). Request Body: Validação de token do lote ```json { } ``` ### Body Params | Campo | Tipo | Descrição | Caracteres | | ------- | ------ | ---------------------------------------------------------------------------------------------------------------- | ---------- | | `token` | string | Código de autenticação enviado ao aprovador de movimentações da conta **obrigatório para TFA via SMS ou e-mail** | 6 | ## Response ### Success Response Após a validação bem-sucedida, a API responde com **202** e o lote passa a ser processado de forma assíncrona. O status final segue a decisão registrada na confirmação (`approved` ou `rejected`). STATUS 202 Response Body: Lote após validação do token (exemplo com decisão `approved`) ```json { "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72", "total_amount": 2778.42, "batch_status": "approved", "payment_type": "collection_slip" } ``` ### Response Body Params | Campo | Tipo | Descrição | | ----------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `batch_payment_key` * | uuid4 | Chave única de identificação do pagamento em lote. | | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `account_key` * | uuid4 | Chave da conta debitada. | | `total_amount` * | number | Soma dos valores dos itens do lote. | | `batch_status` * | string | Após validação do token, o status final reflete a decisão registrada na confirmação (`approved` ou `rejected`). O ciclo de `batch_status` está alinhado ao descrito na documentação de **solicitação de pagamento em lote** fornecida à operação (enumeradores `batch_payment_status`). | | `payment_type` * | string | Tipo do pagamento; para este fluxo, espera-se `collection_slip`. | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | | ----------- | --------- | ----------- | --------------------------------------------- | ---------------------------------------------------------------- | | 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação | | 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. | | 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. | | 400 | BIP000050 | Bad Request | Requester configuration does not exist | Configuração do requester não existe. | | 400 | BIP000058 | Bad Request | Error while validating verification token | Erro ao validar token de verificação | | 400 | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Número de tentativas de validação de token de verificação excedido. | | 400 | BIP000060 | Bad Request | Verification token expired. | Token de verificação expirado. | | 400 | BIP000061 | Bad Request | Verification token validation failed. | Falha na validação do token de verificação. | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. | | 404 | BIP000083 | Not Found | Batch payment not found by batch payment key. | Lote de pagamentos não encontrado pela chave do lote. | | 400 | BIP000085 | Bad Request | Batch payment status is not pending approval. | Status do lote de pagamentos não é de aprovação pendente. | | 400 | BIP000086 | Bad Request | A token is required for SMS or email validation. | Um token é necessário para validação via SMS ou email. | --- # Agendar Pagamento de Boleto Bancário URL: /documentation/baas/cobranca/agendamento/agendar_pagamento_de_boleto_bancario Este endpoint permite realizar o agendamento do pagamento de boletos bancários. O agendamento deve ser realizado após a consulta do boleto bancário, utilizando as informações retornadas para garantir o funcionamento correto do fluxo, evitando falhas durante o processo de pagamento. :::info Boleto bancário É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central. ::: ## Request ENDPOINT /account/ ACCOUNT_KEY /payment_schedule/bank_slip MÉTODO POST ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | Request Body: Pagamento de boleto bancário com linha digitável ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "digitable_line": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8, "payment_date": "2024-03-30" } ``` Request Body: Pagamento de boleto bancário com código de barras ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "barcode": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8, "payment_date": "2024-03-30" } ``` ### Body Params | Campo | Tipo | Descrição | |-------------------------|--------|-----------------------------------------------------| | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente. | | `barcode` | string | Código de barras. | | `digitable_line` | string | Linha digitável. | | `payment_amount` * | number | Valor a ser pago. | | `payment_date` * | string | Data do agendamento. | :::danger Aviso O `payment_amount` deve ser sempre igual ao `total_amount` retornado na consulta do boleto bancário caso o pagamento parcial não seja permitido para o boleto bancário. Para títulos em que o pagamento parcial é permitido, o cliente pode escolher o `payment_amount`, desde que a soma do mesmo com o `registered_payment_amount` do boleto bancário não seja superior ao `total_amount`. ::: ## Response ### Success Response STATUS 201 Response Body: Agendamento confirmado ```json { "payment_key":"c4325104-d60b-44f3-aae4-49155564a2ea", "request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189", "payer_name":"COOPERATIVA INDUSTRIAL MURILO", "payer_document_number":"00037025000160", "source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f", "paid_amount":1050.1, "payment_date":"2024-04-03", "payment_type":"bank_slip", "bank_slip": { "bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a", "barcode":"00193967000009910000000003615574000000002417", "digitable_line":"00190000090361557400500000024174396700000991000", "payer_name":"COOPERATIVA TESTE", "payer_document_number":"00037025000160", "beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA", "beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA", "beneficiary_document_number":"52069937000117", "beneficiary_bank_ispb":"00000000", "guarantor_name":null, "guarantor_document_number":null, "expiration_date":"2024-03-29", "max_payment_data": "2026-03-29", "partial_payment_indicator":"allowed", "registered_payment_amount":9029.0, "nominal_amount":9910.0, "total_amount":10129.1, "rebate_amount":0.0, "discount_amount":0.0, "fine_amount":0.0, "interest_amount":219.1 }, "collection_slip":null, "payment_schedule_status":"scheduled" } ``` ### Response Body Params | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------| | `payment_key` * | uuid4 | Chave única de identificação do pagamento. | | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente. | | `payer_name` * | string | Nome do pagador efetivo.| | `payer_document_number` * | string | Número de documento do pagador efetivo (CPF/CNPJ). | | `source_account_key` * | uuid4 | Chave da conta debitada. | | `paid_amount` * | number | Valor pago efetivamente. | | `payment_date` * | string | Data do pagamento. | | `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. | | `bank_slip` | [object](#objeto-bank_slip) | Boleto bancário. | | `collection_slip` | object | Fatura de recolhimento. | | `payment_schedule_status` * | [enum](#enumeradores-payment_schedule_status) | Status do pagamento. | ### Enumeradores payment_type | Enumerador | Descrição | |---------------|---------------| | `bank_slip` | Boleto bancário | | `collection_slip` | Fatura de recolhimento | :::danger Aviso O enumerador `collection_slip` não se aplica para o fluxo de boletos bancários, assim como o objeto collection_slip que sempre será nulo. ::: ### Enumeradores payment_schedule_status | Enumerador | Descrição | |---------------------|------------------------------------------------------------------| | `pending_2fa_approval` | Agendamento pendente de autenticação de dois fatores (2FA) | | `scheduled` | Pagamento agendado com sucesso | | `executed` | O agendamento foi executado com sucesso e o pagamento referente ao agendamento gerado | | `rejected` | O agendamento foi rejeitado e nenhum pagamento foi gerado | | `canceled` | Agendamento cancelado | | `error` | Erro ao realizar o agendamento | :::danger Aviso Para pagamentos onde a QI não receber uma resposta da CIP em até dois minutos, o pagamento será retornado com o status `pending_execution`. Após a QI receber a resposta da CIP, será enviado para o cliente o webhook de pagamento pendente descrito na [página de webhooks](/documentation/baas/cobranca/webhooks). ::: ### Objeto bank_slip | Campo | Tipo | Descrição | |-----------------------------------|---------|-----------------------------------| | `barcode` * | string | Código de barras. | | `digitable_line` * | string | Linha digitável. | | `payer_name` * | string | Nome do pagador.| | `payer_document_number` * | string | Número de documento do pagador (CPF/CNPJ). | | `beneficiary_name` * | string | Nome do beneficiário. | | `beneficiary_trading_name` | string | Nome fantasia do beneficiário. | | `beneficiary_document_number` * | string | Número de documento do beneficiário (CPF/CNPJ). | | `beneficiary_bank_ispb` * | string | Código ispb do banco do beneficiário. | | `guarantor_name` | string | Nome do sacador avalista. | | `guarantor_document_number` | string | Número de documento do sacador avalista (CPF/CNPJ). | | `expiration_date` * | string | Data de vencimento. | | `max_payment_date` * | string | Data máxima de pagamento. | | `partial_payment_indicator` * | [enum](#enumeradores-partial_payment_indicator) | Indicador de pagamento parcial. | | `registered_payment_amount` | string | Valor total de pagamento registrado. | | `nominal_amount` * | number | Valor original. | | `total_amount` * | number | Valor total. | | `rebate_amount` * | number | Valor do abatimento. | | `discount_amount` * | number | Valor do desconto. | | `fine_amount` * | number | Valor da multa. | | `interest_amount` * | number | Valor do juros. | ### Enumeradores partial_payment_indicator | Enumerador | Descrição | |---------------|---------------| | `allowed` | Permitido | | `not_allowed` | Não permitido | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 400 | BIP000001 | Bad Request | The barcode or digitable line must have 44 or 47 characters. | O código de barras ou linha digitável deve ter 44 ou 47 caracteres. | | 400 | BIP000002 | Bad Request | The bill sent does not correspond to a bank slip. | A conta enviado não corresponde a um boleto bancário. | | 400 | BIP000003 | Bad Request | The digitable line sent is invalid. | A linha digitável enviada é inválida. | | 404 | BIP000004 | Not Found | The bank slip was not found. | O boleto não foi encontrado. | | 400 | BIP000005 | Bad Request | It was not possible to consult the bank slip at this time. Please try again in a few minutes. | Não foi possível consultar o boleto neste momento. Por favor, tente novamente em alguns minutos. | | 400 | BIP000006 | Bad Request | Bank slip already written off | Boleto já baixado | | 400 | BIP000007 | Bad Request | Bank slip blocked for payment | Boleto bloqueado para pagamento | | 400 | BIP000008 | Bad Request | Bank slip already paid | Boleto já pago | | 400 | BIP000009 | Bad Request | Invalid bank slip. Please consult issuing bank | Boleto inválido. Favor consultar banco emissor | | 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação | | 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. | | 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. | | 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. | | 400 | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. | | 400 | BIP000015 | Bad Request | Payment date is greater than the maximum payment date. | A data de pagamento é maior que a data máxima de pagamento. | | 400 | BIP000016 | Bad Request | Payment date is smaller than the calculation date. | A data de pagamento é menor que a data de cálculo. | | 400 | BIP000017 | Bad Request | Invalid payment amount. | Valor de pagamento inválido. | | 400 | BIP000018 | Bad Request | Partial payment is not allowed. | Pagamento parcial não é permitido. | | 400 | BIP000019 | Bad Request | The payment amount is greater than the available amount. | O valor do pagamento é maior que o valor disponível. | | 400 | BIP000020 | Bad Request | All partial payments for this bank slip have already been made. | Todos os pagamentos parciais deste boleto já foram realizados. | | 400 | BIP000022 | Bad Request | Bank slip payment service is closed. | Serviço de pagamento de boleto está fechado. | | 400 | BIP000023 | Bad Request | The source account has insufficient balance. Payment cannot be made. | A conta de origem possui saldo insuficiente. Pagamento não pode ser realizado. | | 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. | | 400 | BIP000025 | Bad Request | It was not possible to pay the bank slip at this time. Please verify your information and, if necessary, contact us for assistance. | Não foi possível pagar o boleto neste momento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para assistência. | | 400 | BIP000028 | Bad Request | The source account has blocked balance. Payment cannot be made. | A conta de origem possui saldo em conta bloqueado. Pagamento não pode ser realizado. | ## Ambiente de Sandbox Para realizar os testes em ambiente de sandbox, devem ser usadas as linhas digitáveis listadas na [Seção de pagamento de boleto bancário](/documentation/baas/cobranca/pagar_boleto_bancario). --- # Agendar Pagamento de Fatura de Recolhimento (convênio/tributo) URL: /documentation/baas/cobranca/agendamento/agendar_pagamento_de_fatura_de_recolhimento Este endpoint permite realizar o agendamento de pagamento de faturas de recolhimento. O agendamento deve ser realizado após a consulta da Fatura de Recolhimento, utilizando as informações retornadas para garantir o funcionamento correto do fluxo, evitando falhas durante o processo de pagamento. :::info Fatura de Recolhimento Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgão públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta. ::: ## Request ENDPOINT /account/ ACCOUNT_KEY /payment_schedule/collection_slip MÉTODO POST ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | Request Body: Agendamento de fatura de recolhimento com linha digitável ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "digitable_line": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8, "payment_date": "2024-03-30" } ``` Request Body: Agendamento de fatura de recolhimento com código de barras ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "barcode": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8, "payment_date": "2024-03-30" } ``` ### Body Params | Campo | Tipo | Descrição | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente. | | `barcode` | string | Código de barras. | | `digitable_line` | string | Linha digitável. | | `payment_amount` * | number | Valor a ser pago. | | `payment_date` * | string | Data do agendamento. | :::danger Aviso O `payment_amount` deve sempre igual ao `total_amount` retornado na consulta do boleto bancário. ::: ## Response ### Success Response STATUS 201 Response Body: Agendamento confirmado ```json { "payment_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a", "request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9", "payer_name": "COOPERATIVA INDUSTRIAL MURILO", "payer_document_number": "62069937000118", "source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72", "paid_amount": 1389.21, "payment_date": "2024-04-30", "payment_type": "collection_slip", "bank_slip": null, "collection_slip": { "barcode": null, "digitable_line": "836200000138892100450006762142420244046000010192", "collection_name": "CIA ULTRAGAZ SA-COD", "collection_document_number": "00394460005887", "expiration_date": "2024-04-15", "total_amount": 1389.21 }, "payment_schedule_status": "scheduled" } ``` ### Response Body Params | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------------------------| | `payment_key` * | uuid4 | Chave única de identificação do pagamento. | | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente. | | `payer_name` * | string | Nome do pagador efetivo. | | `payer_document_number` * | string | Número de documento do pagador efetivo (CPF/CNPJ). | | `source_account_key` * | uuid4 | Chave da conta debitada. | | `transaction_key` * | uuid4 | Chave da transação do pagamento. | | `transaction_revert_key` | uuid4 | Chave da transação de reversão do pagamento. | | `paid_amount` * | number | Valor pago efetivamente. | | `payment_date` * | string | Data do pagamento. | | `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. | | `bank_slip` | object | Boleto bancário. | | `collection_slip` | [object](#objeto-collection_slip) | Fatura de recolhimento. | | `payment_schedule_status` * | [enum](#enumeradores-payment_schedule_status) | Status do agendamento. | ### Enumeradores payment_type | Enumerador | Descrição | |---------------|---------------| | `bank_slip` | Boleto bancário | | `collection_slip` | Fatura de recolhimento | :::danger Aviso O enumerador `bank_slip` não se aplica para o fluxo de faturas de recolhimento, assim como o objeto bank_slip que sempre será nulo. ::: ### Enumeradores payment_schedule_status | Enumerador | Descrição | |---------------------|------------------------------------------------------------------| | `pending_2fa_approval` | Agendamento pendente de autenticação de dois fatores (2FA) | | `scheduled` | Pagamento agendado com sucesso | | `executed` | O agendamento foi executado com sucesso e o pagamento referente ao agendamento gerado | | `rejected` | O agendamento foi rejeitado e nenhum pagamento foi gerado | | `canceled` | Agendamento cancelado | | `error` | Erro ao realizar o agendamento | ### Objeto collection_slip | Campo | Tipo | Descrição | |-----------------------------------|---------|-----------------------------------| | `barcode` | string | Código de barras. | | `digitable_line` | string | Linha digitável. | | `collection_name` * | string | Nome do convênio.| | `collection_document_number` | string | Número de documento do convênio (CPF/CNPJ).| | `expiration_date` * | string | Data de vencimento. | | `total_amount` * | number | Valor total. | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 400 | BIP000032 | Bad Request | The bill sent does not correspond to a collection slip. | A conta enviada não corresponde a uma fatura de recolhimento. | | 400 | BIP000033 | Bad Request | The barcode or digitable line of the collection slip must have 44 or 48 characters. | O código de barras ou linha digitável da fatura de recolhimento deve ter 44 ou 48 caracteres. | | 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação | | 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. | | 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. | | 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. | | 400 | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. | | 400 | BIP000023 | Bad Request | The source account has insufficient balance. Payment cannot be made. | A conta de origem possui saldo insuficiente. Pagamento não pode ser realizado. | | 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. | | 400 | BIP000028 | Bad Request | The source account has blocked balance. Payment cannot be made. | A conta de origem possui saldo em conta bloqueado. Pagamento não pode ser realizado. | | 400 | BIP000034 | Bad Request | Collection slip already paid. | Fatura de recolhimento já paga. | | 400 | BIP000035 | Bad Request | Covenant slip invalid barcode. | Código de barras da fatura de recolhimento inválido. | | 400 | BIP000036 | Bad Request | Covenant slip overdue. | Fatura de recolhimento vencida. | | 400 | BIP000037 | Bad Request | Error in collection slip consultation. | Erro na consulta da fatura de recolhimento. | | 400 | BIP000038 | Bad Request | Outside of covenant payment hours. | Fora do horário de pagamento do convênio. | | 400 | BIP000039 | Bad Request | Collection slip not accepted. | Fatura de recolhimento não aceita. | | 400 | BIP000040 | Bad Request | Minimum advance not reached. | Mínimo de dias de adiantamento não atingido. | | 400 | BIP000041 | Bad Request | Max payment amount exceeded. | Valor máximo de pagamento excedido. | | 400 | BIP000044 | Bad Request | It was not possible to pay the collection slip at this time. Please verify your information and, if necessary, contact us for assistance. | Não foi possível pagar a fatura de recolhimento neste momento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para assistência. | ## Ambiente de Sandbox Em nosso ambiente de sandbox, disponibilizamos linhas digitáveis mockadas para a simulação de pagamentos bem-sucedidos e testes de cenários de erro. ### Cenários de sucesso | Linha digitável | |---| | 828300000007411100972013905080001546763201900028 | | 838000000009235700481007241345219112001474229880 | | 848000000006308600802021201071261517689002201070 | | 858200000015000000643025703477209504800448091020 | ### Cenários de erro | Linha digitável | Código de erro | |---|---| | 858500000037350000643217212883260006147448091022 | BIP000035 | --- # Cancelar Agendamento URL: /documentation/baas/cobranca/agendamento/cancelar_agendamento Este endpoint é utilizado para realizar o cancelamento de um agendamento de pagamento de um Boleto Bancário ou Fatura de Recolhimento. :::info Boleto bancário É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central. ::: :::info Fatura de Recolhimento Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgão públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta. ::: ## Request ENDPOINT /account/ ACCOUNT_KEY /payment_schedule/ PAYMENT_SCHEDULE_KEY /cancel MÉTODO PATCH ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |--------------------------|---------|----------------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | | `payment_schedule_key` * | uuid4 | Chave única de identificação do agendamento. | 36 | ## Response ### Success Response STATUS 200 Response Body: agendamento de pagamento de boleto bancário cancelado ```json { "payment_key":"c4325104-d60b-44f3-aae4-49155564a2ea", "request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189", "payer_name":"COOPERATIVA INDUSTRIAL MURILO", "payer_document_number":"00037025000160", "source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f", "paid_amount":1050.1, "payment_date":"2024-04-03", "payment_type":"bank_slip", "bank_slip": { "bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a", "barcode":"00193967000009910000000003615574000000002417", "digitable_line":"00190000090361557400500000024174396700000991000", "payer_name":"COOPERATIVA TESTE", "payer_document_number":"00037025000160", "beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA", "beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA", "beneficiary_document_number":"52069937000117", "beneficiary_bank_ispb":"00000000", "guarantor_name":null, "guarantor_document_number":null, "expiration_date":"2024-03-29", "max_payment_data": "2026-03-29", "partial_payment_indicator":"allowed", "registered_payment_amount":9029.0, "nominal_amount":9910.0, "total_amount":10129.1, "rebate_amount":0.0, "discount_amount":0.0, "fine_amount":0.0, "interest_amount":219.1 }, "collection_slip":null, "payment_schedule_status":"canceled" } ``` Response Body: agendamento de pagamento de fatura de recolhimento cancelada ```json { "payment_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a", "request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9", "payer_name": "COOPERATIVA INDUSTRIAL MURILO", "payer_document_number": "62069937000118", "source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72", "paid_amount": 1389.21, "payment_date": "2024-04-30", "payment_type": "collection_slip", "bank_slip": null, "collection_slip": { "barcode": null, "digitable_line": "836200000138892100450006762142420244046000010192", "collection_name": "CIA ULTRAGAZ SA-COD", "collection_document_number": "00394460005887", "expiration_date": "2024-04-15", "total_amount": 1389.21 }, "payment_schedule_status": "canceled" } ``` ### Response Body Params | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------------------------| | `payment_key` * | uuid4 | Chave única de identificação do pagamento. | | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente. | | `payer_name` * | string | Nome do pagador efetivo. | | `payer_document_number` * | string | Número do documento do pagador efetivo (CPF/CNPJ). | | `source_account_key` * | uuid4 | Chave da conta debitada. | | `paid_amount` * | number | Valor pago efetivamente. | | `payment_date` * | string | Data do agendamento. | | `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. | | `bank_slip` | [object](#objeto-bank_slip) | Boleto bancário. | | `collection_slip` | object | Fatura de recolhimento. | | `payment_schedule_status` * | [enum](#enumeradores-payment_schedule_status) | Status do agendamento. | ### Enumeradores payment_type | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | ### Enumeradores payment_schedule_status | Enumerador | Descrição | |------------|-----------------------| | `canceled` | Agendamento cancelado | ### Objeto bank_slip | Campo | Tipo | Descrição | |-----------------------------------|---------|-----------------------------------| | `barcode` * | string | Código de barras. | | `digitable_line` * | string | Linha digitável. | | `payer_name` * | string | Nome do pagador.| | `payer_document_number` * | string | Número do documento do pagador (CPF/CNPJ). | | `beneficiary_name` * | string | Nome do beneficiário. | | `beneficiary_trading_name` | string | Nome fantasia do beneficiário. | | `beneficiary_document_number` * | string | Número do documento do beneficiário (CPF/CNPJ). | | `beneficiary_bank_ispb` * | string | Código ispb do banco do beneficiário. | | `guarantor_name` | string | Nome do sacador avalista. | | `guarantor_document_number` | string | Número do documento do sacador avalista (CPF/CNPJ). | | `expiration_date` * | string | Data de vencimento. | | `max_payment_date` * | string | Data máxima de pagamento. | | `partial_payment_indicator` * | [enum](#enumeradores-partial_payment_indicator) | Indicador de pagamento parcial. | | `registered_payment_amount` | string | Valor total de pagamento registrado. | | `nominal_amount` * | number | Valor original. | | `total_amount` * | number | Valor total. | | `rebate_amount` * | number | Valor do abatimento. | | `discount_amount` * | number | Valor do desconto. | | `fine_amount` * | number | Valor da multa. | | `interest_amount` * | number | Valor do juros. | ### Enumeradores partial_payment_indicator | Enumerador | Descrição | |---------------|---------------| | `allowed` | Permitido | | `not_allowed` | Não permitido | ### Objeto collection_slip | Campo | Tipo | Descrição | |-----------------------------------|---------|-----------------------------------| | `barcode` | string | Código de barras. | | `digitable_line` | string | Linha digitável. | | `collection_name` * | string | Nome do convênio.| | `collection_document_number` | string | Número de documento do convênio (CPF/CNPJ).| | `expiration_date` * | string | Data de vencimento. | | `total_amount` * | number | Valor total. | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 400 | BIP000001 | Bad Request | The barcode or digitable line must have 44 or 47 characters. | O código de barras ou linha digitável deve ter 44 ou 47 caracteres. | | 400 | BIP000002 | Bad Request | The bill sent does not correspond to a bank slip. | A conta enviado não corresponde a um boleto bancário. | | 400 | BIP000003 | Bad Request | The digitable line sent is invalid. | A linha digitável enviada é inválida. | | 404 | BIP000004 | Not Found | The bank slip was not found. | O boleto não foi encontrado. | | 400 | BIP000005 | Bad Request | It was not possible to consult the bank slip at this time. Please try again in a few minutes. | Não foi possível consultar o boleto neste momento. Por favor, tente novamente em alguns minutos. | | 400 | BIP000006 | Bad Request | Bank slip already written off | Boleto já baixado | | 400 | BIP000007 | Bad Request | Bank slip blocked for payment | Boleto bloqueado para pagamento | | 400 | BIP000008 | Bad Request | Bank slip already paid | Boleto já pago | | 400 | BIP000009 | Bad Request | Invalid bank slip. Please consult issuing bank | Boleto inválido. Favor consultar banco emissor | --- # Consultar Agendamento URL: /documentation/baas/cobranca/agendamento/consultar_agendamento Este endpoint é utilizado para consultar as informações de um agendamento de pagamento de um Boleto Bancário ou Fatura de Recolhimento. :::info Boleto bancário É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central. ::: :::info Fatura de Recolhimento Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgão públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta. ::: ## Request ENDPOINT /account/ ACCOUNT_KEY /payment_schedule/ PAYMENT_SCHEDULE_KEY MÉTODO GET ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |--------------------------|---------|----------------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | | `payment_schedule_key` * | uuid4 | Chave única de identificação do agendamento. | 36 | ## Response ### Success Response STATUS 200 Response Body: Agendamento de pagamento de boleto bancário ```json { "payment_key":"c4325104-d60b-44f3-aae4-49155564a2ea", "request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189", "payer_name":"COOPERATIVA INDUSTRIAL MURILO", "payer_document_number":"00037025000160", "source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f", "paid_amount":1050.1, "payment_date":"2024-04-03", "payment_type":"bank_slip", "bank_slip": { "bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a", "barcode":"00193967000009910000000003615574000000002417", "digitable_line":"00190000090361557400500000024174396700000991000", "payer_name":"COOPERATIVA TESTE", "payer_document_number":"00037025000160", "beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA", "beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA", "beneficiary_document_number":"52069937000117", "beneficiary_bank_ispb":"00000000", "guarantor_name":null, "guarantor_document_number":null, "expiration_date":"2024-03-29", "max_payment_data": "2026-03-29", "partial_payment_indicator":"allowed", "registered_payment_amount":9029.0, "nominal_amount":9910.0, "total_amount":10129.1, "rebate_amount":0.0, "discount_amount":0.0, "fine_amount":0.0, "interest_amount":219.1 }, "collection_slip":null, "payment_schedule_status":"scheduled" } ``` Response Body: Agendamento de pagamento de fatura de recolhimento ```json { "payment_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a", "request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9", "payer_name": "COOPERATIVA INDUSTRIAL MURILO", "payer_document_number": "62069937000118", "source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72", "paid_amount": 1389.21, "payment_date": "2024-04-30", "payment_type": "collection_slip", "bank_slip": null, "collection_slip": { "barcode": null, "digitable_line": "836200000138892100450006762142420244046000010192", "collection_name": "CIA ULTRAGAZ SA-COD", "collection_document_number": "00394460005887", "expiration_date": "2024-04-15", "total_amount": 1389.21 }, "payment_schedule_status": "scheduled" } ``` ### Response Body Params | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------------------------| | `payment_key` * | uuid4 | Chave única de identificação do pagamento. | | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente. | | `payer_name` * | string | Nome do pagador efetivo. | | `payer_document_number` * | string | Número do documento do pagador efetivo (CPF/CNPJ). | | `source_account_key` * | uuid4 | Chave da conta debitada. | | `transaction_key` * | uuid4 | Chave da transação do pagamento. | | `transaction_revert_key` | uuid4 | Chave da transação de reversão do pagamento. | | `paid_amount` * | number | Valor pago efetivamente. | | `payment_date` * | string | Data do agendamento. | | `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. | | `bank_slip` | [object](#objeto-bank_slip) | Boleto bancário. | | `collection_slip` | object | Fatura de recolhimento. | | `payment_schedule_status` * | [enum](#enumeradores-payment_schedule_status) | Status do agendamento. | ### Enumeradores payment_type | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | ### Enumeradores payment_schedule_status | Enumerador | Descrição | |---------------------|------------------------------------------------------------------| | `pending_2fa_approval` | Agendamento pendente de autenticação de dois fatores (2FA) | | `scheduled` | Pagamento agendado com sucesso | | `executed` | O agendamento foi executado com sucesso e o pagamento referente ao agendamento gerado | | `rejected` | O agendamento foi rejeitado e nenhum pagamento foi gerado | | `canceled` | Agendamento cancelado | | `error` | Erro ao realizar o agendamento | ### Objeto bank_slip | Campo | Tipo | Descrição | |-----------------------------------|---------|-----------------------------------| | `barcode` * | string | Código de barras. | | `digitable_line` * | string | Linha digitável. | | `payer_name` * | string | Nome do pagador.| | `payer_document_number` * | string | Número do documento do pagador (CPF/CNPJ). | | `beneficiary_name` * | string | Nome do beneficiário. | | `beneficiary_trading_name` | string | Nome fantasia do beneficiário. | | `beneficiary_document_number` * | string | Número do documento do beneficiário (CPF/CNPJ). | | `beneficiary_bank_ispb` * | string | Código ispb do banco do beneficiário. | | `guarantor_name` | string | Nome do sacador avalista. | | `guarantor_document_number` | string | Número do documento do sacador avalista (CPF/CNPJ). | | `expiration_date` * | string | Data de vencimento. | | `max_payment_date` * | string | Data máxima de pagamento. | | `partial_payment_indicator` * | [enum](#enumeradores-partial_payment_indicator) | Indicador de pagamento parcial. | | `registered_payment_amount` | string | Valor total de pagamento registrado. | | `nominal_amount` * | number | Valor original. | | `total_amount` * | number | Valor total. | | `rebate_amount` * | number | Valor do abatimento. | | `discount_amount` * | number | Valor do desconto. | | `fine_amount` * | number | Valor da multa. | | `interest_amount` * | number | Valor do juros. | ### Enumeradores partial_payment_indicator | Enumerador | Descrição | |---------------|---------------| | `allowed` | Permitido | | `not_allowed` | Não permitido | ### Objeto collection_slip | Campo | Tipo | Descrição | |-----------------------------------|---------|-----------------------------------| | `barcode` | string | Código de barras. | | `digitable_line` | string | Linha digitável. | | `collection_name` * | string | Nome do convênio.| | `collection_document_number` | string | Número de documento do convênio (CPF/CNPJ).| | `expiration_date` * | string | Data de vencimento. | | `total_amount` * | number | Valor total. | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 400 | BIP000001 | Bad Request | The barcode or digitable line must have 44 or 47 characters. | O código de barras ou linha digitável deve ter 44 ou 47 caracteres. | | 400 | BIP000002 | Bad Request | The bill sent does not correspond to a bank slip. | A conta enviado não corresponde a um boleto bancário. | | 400 | BIP000003 | Bad Request | The digitable line sent is invalid. | A linha digitável enviada é inválida. | | 404 | BIP000004 | Not Found | The bank slip was not found. | O boleto não foi encontrado. | | 400 | BIP000005 | Bad Request | It was not possible to consult the bank slip at this time. Please try again in a few minutes. | Não foi possível consultar o boleto neste momento. Por favor, tente novamente em alguns minutos. | | 400 | BIP000006 | Bad Request | Bank slip already written off | Boleto já baixado | | 400 | BIP000007 | Bad Request | Bank slip blocked for payment | Boleto bloqueado para pagamento | | 400 | BIP000008 | Bad Request | Bank slip already paid | Boleto já pago | | 400 | BIP000009 | Bad Request | Invalid bank slip. Please consult issuing bank | Boleto inválido. Favor consultar banco emissor | --- # Listar Agendamentos URL: /documentation/baas/cobranca/agendamento/listar_agendamentos Este endpoint tem a finalidade de fornecer detalhes de todos os agendamentos realizados pelo parceiro integrador, incluindo boletos bancários e Faturas de recolhimento. :::info Boleto bancário É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central. ::: :::info Fatura de recolhimento Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgão públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta. ::: ## Request ENDPOINT /account/ ACCOUNT_KEY /payment_schedules MÉTODO GET ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | ### Request Query String Params | Campo | Tipo | Descrição | |------------------------|-------------|--------------------------------------------------------------------------| | `request_control_key` | uuid4 | Chave única de identificação da request do cliente. | | `payment_schedule_key` | uuid4 | Chave única de identificação do agendamento. | | `payment_key` | uuid4 | Chave única de identificação do pagamento gerado para o agendamento. | | `payment_type` | [enum](#enumeradores-payment_type) | Tipo do pagamento. | | `payment_schedule_status` | [enum](#enumeradores-payment_schedule_status) | Status do agendamento. | | `date_from` | string | Data inicial. Formato "YYYY-MM-DD". | | `date_to` | string | Data final. Formato "YYYY-MM-DD". | | `page` | string | Número da página requisitada. 1 por padrão. | | `page_size` | string | Tamanho da página requisitada na consulta. 30 por padrão e valor máximo. | ### Enumeradores payment_type | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | ### Enumeradores payment_schedule_status | Enumerador | Descrição | |---------------------|------------------------------------------------------------------| | `pending_2fa_approval` | Agendamento pendente de autenticação de dois fatores (2FA) | | `scheduled` | Pagamento agendado com sucesso | | `executed` | O agendamento foi executado com sucesso e o pagamento referente ao agendamento gerado | | `rejected` | O agendamento foi rejeitado e nenhum pagamento foi gerado | | `canceled` | Agendamento cancelado | | `error` | Erro ao realizar o agendamento ## Response ### Success Response STATUS 200 Response Body: Consulta de pagamentos ```json { "data": [ { "payment_key":"c4325104-d60b-44f3-aae4-49155564a2ea", "request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189", "payer_name":"COOPERATIVA INDUSTRIAL MURILO", "payer_document_number":"00037025000160", "source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f", "paid_amount":1050.1, "payment_date":"2024-04-03", "payment_type":"bank_slip", "bank_slip": { "bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a", "barcode":"00193967000009910000000003615574000000002417", "digitable_line":"00190000090361557400500000024174396700000991000", "payer_name":"COOPERATIVA TESTE", "payer_document_number":"00037025000160", "beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA", "beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA", "beneficiary_document_number":"52069937000117", "beneficiary_bank_ispb":"00000000", "guarantor_name":null, "guarantor_document_number":null, "expiration_date":"2024-03-29", "max_payment_data": "2026-03-29", "partial_payment_indicator":"allowed", "registered_payment_amount":9029.0, "nominal_amount":9910.0, "total_amount":10129.1, "rebate_amount":0.0, "discount_amount":0.0, "fine_amount":0.0, "interest_amount":219.1 }, "collection_slip":null, "payment_schedule_status":"scheduled" }, { "payment_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a", "request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9", "payer_name": "COOPERATIVA INDUSTRIAL MURILO", "payer_document_number": "62069937000118", "source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72", "paid_amount": 1389.21, "payment_date": "2024-04-30", "payment_type": "collection_slip", "bank_slip": null, "collection_slip": { "barcode": null, "digitable_line": "836200000138892100450006762142420244046000010192", "collection_name": "CIA ULTRAGAZ SA-COD", "collection_document_number": "00394460005887", "expiration_date": "2024-04-15", "total_amount": 1389.21 }, "payment_schedule_status": "scheduled" } ], "pagination": { "current_page": 1, "rows_per_page": 30 } } ``` ### Response Body Params | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------------------------| | `payment_key` * | uuid4 | Chave única de identificação do pagamento. | | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente. | | `payer_name` * | string | Nome do pagador efetivo. | | `payer_document_number` * | string | Número de documento do pagador efetivo (CPF/CNPJ). | | `source_account_key` * | uuid4 | Chave da conta debitada. | | `paid_amount` * | number | Valor pago efetivamente. | | `payment_date` * | string | Data do pagamento. | | `payment_type` * | [enum](#enumeradores-payment_type-1) | Tipo do pagamento. | | `bank_slip` | [object](#objeto-bank_slip) | Boleto bancário. | | `collection_slip` | [object](#objeto-collection_slip) | Fatura de recolhimento. | | `payment_schedule_status` * | [enum](#enumeradores-payment_schedule_status) | Status do agendamento. | ### Enumeradores payment_type | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | ### Enumeradores payment_schedule_status | Enumerador | Descrição | |---------------------|------------------------------------------------------------------| | `pending_2fa_approval` | Agendamento pendente de autenticação de dois fatores (2FA) | | `scheduled` | Pagamento agendado com sucesso | | `executed` | O agendamento foi executado com sucesso e o pagamento referente ao agendamento gerado | | `rejected` | O agendamento foi rejeitado e nenhum pagamento foi gerado | | `canceled` | Agendamento cancelado | | `error` | Erro ao realizar o agendamento | ### Objeto bank_slip | Campo | Tipo | Descrição | |-----------------------------------|---------|-----------------------------------| | `barcode` * | string | Código de barras. | | `digitable_line` * | string | Linha digitável. | | `payer_name` * | string | Nome do pagador.| | `payer_document_number` * | string | Número de documento do pagador (CPF/CNPJ). | | `beneficiary_name` * | string | Nome do beneficiário. | | `beneficiary_trading_name` | string | Nome fantasia do beneficiário. | | `beneficiary_document_number` * | string | Número de documento do beneficiário (CPF/CNPJ). | | `beneficiary_bank_ispb` * | string | Código ispb do banco do beneficiário. | | `guarantor_name` | string | Nome do sacador avalista. | | `guarantor_document_number` | string | Número de documento do sacador avalista (CPF/CNPJ). | | `expiration_date` * | string | Data de vencimento. | | `max_payment_date` * | string | Data máxima de pagamento. | | `partial_payment_indicator` * | [enum](#enumeradores-partial_payment_indicator) | Indicador de pagamento parcial. | | `registered_payment_amount` | string | Valor total de pagamento registrado. | | `nominal_amount` * | number | Valor original. | | `total_amount` * | number | Valor total. | | `rebate_amount` * | number | Valor do abatimento. | | `discount_amount` * | number | Valor do desconto. | | `fine_amount` * | number | Valor da multa. | | `interest_amount` * | number | Valor do juros. | ### Enumeradores partial_payment_indicator | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `allowed` | string | Permitido | | `not_allowed` | string | Não permitido | ### Objeto collection_slip | Campo | Tipo | Descrição | |-----------------------------------|---------|-----------------------------------| | `barcode` * | string | Código de barras. | | `digitable_line` * | string | Linha digitável. | | `collection_name` * | string | Nome do pagador.| | `collection_document_number` * | string | Número de documento do convênio (CPF/CNPJ). | | `expiration_date` * | string | Data de vencimento. | | `total_amount` * | number | Valor total. | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 400 | BIP000026 | Bad Request | Invalid payment date format. The correct format is YYYY-MM-DD. | Formato de data de pagamento inválido. O formato correto é YYYY-MM-DD. | | 400 | BIP000027 | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. | | 400 | BIP000047 | Bad Request | Invalid payment type. | Tipo de pagamento inválido. | --- # Solicitar agendamento em lote de boleto bancário URL: /documentation/baas/cobranca/agendamento/solicitar_agendamento_em_lote_de_boleto_bancario Este endpoint permite solicitar o **agendamento em lote** de boletos bancários em uma única requisição. :::info Boleto bancário É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments_schedule/batch_bank_slip MÉTODO POST ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | Request Body: Agendamento em lote de boletos bancários ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "bank_slip_payment_schedules": [ { "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd", "digitable_line": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8, "payment_date": "2026-04-10" }, { "request_control_key": "d8a26b54-323a-4924-0aed-e4fe6e4e4c0e", "barcode": "00190000090361557400500000024174396700000991000", "payment_amount": 200.5, "payment_date": "2026-04-15" } ] } ``` ### Body Params | Campo | Tipo | Descrição | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `bank_slip_payment_schedules` * | array | Lista de agendamentos de boleto bancário. Limite de **1000** itens por requisição. | Cada elemento de `bank_slip_payment_schedules` deve conter: | Campo | Tipo | Descrição | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente para aquele item do lote. | | `barcode` | string | Código de barras. | | `digitable_line` | string | Linha digitável. | | `payment_amount` * | number | Valor a ser pago. | | `payment_date` * | string | Data do agendamento do item. | :::danger Aviso Para cada item, o `payment_amount` deve seguir as regras do título retornadas na consulta do boleto bancário. Se o pagamento parcial não for permitido, o valor deve corresponder ao total atualizado do título. ::: ## Response ### Success Response STATUS 202 Response Body: Lote de agendamento criado ```json { "batch_payment_schedule_key": "c4325104-d60b-44f3-aae4-49155564a2ea", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f", "total_amount": 1357.3, "batch_payment_schedule_status": "scheduled", "payment_type": "bank_slip" } ``` ### Response Body Params | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------| | `batch_payment_schedule_key` * | uuid4 | Chave única de identificação do agendamento em lote. | | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `account_key` * | uuid4 | Chave da conta debitada. | | `total_amount` * | number | Soma dos valores (`payment_amount`) dos itens do lote. | | `batch_payment_schedule_status` * | [enum](#enumeradores-batch_payment_schedule_status) | Status do lote de agendamento após a solicitação. | | `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. | ### Enumeradores batch_payment_schedule_status | Enumerador | Descrição | |---------------|---------------| | `pending_2fa_approval` | Pendente de aprovação 2FA | | `scheduled` | Agendado | | `rejected` | Rejeitado | | `error` | Erro ao agendar | ### Enumeradores payment_type | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | :::danger Aviso O enumerador `collection_slip` não se aplica ao fluxo de agendamento em lote de boletos bancários deste endpoint; para este caso, espera-se `payment_type` com valor `bank_slip`. ::: ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação | | 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. | | 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. | | 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. | --- # Solicitar agendamento em lote de fatura de recolhimento URL: /documentation/baas/cobranca/agendamento/solicitar_agendamento_em_lote_de_fatura_de_recolhimento Este endpoint permite solicitar o **agendamento em lote** de faturas de recolhimento (convênio/tributo) em uma única requisição. :::info Fatura de recolhimento Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments_schedule/batch_collection_slip MÉTODO POST ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | Request Body: Agendamento em lote de faturas de recolhimento ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "collection_slip_payment_schedules": [ { "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd", "digitable_line": "836200000138892100450006762142420244046000010192", "payment_amount": 1389.21, "payment_date": "2026-04-10" }, { "request_control_key": "d8a26b54-323a-4924-0aed-e4fe6e4e4c0e", "barcode": "836200000138892100450006762142420244046000010192", "payment_amount": 550.10, "payment_date": "2026-04-15" } ] } ``` ### Body Params | Campo | Tipo | Descrição | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `collection_slip_payment_schedules` * | array | Lista de agendamentos de fatura de recolhimento. Limite de **1000** itens por requisição. | Cada elemento de `collection_slip_payment_schedules` deve conter: | Campo | Tipo | Descrição | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente para aquele item do lote. | | `barcode` | string | Código de barras. | | `digitable_line` | string | Linha digitável. | | `payment_amount` * | number | Valor a ser pago. | | `payment_date` * | string | Data do agendamento do item. | ## Response ### Success Response STATUS 202 Response Body: Lote de agendamento criado ```json { "batch_payment_schedule_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a", "request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9", "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72", "total_amount": 1939.31, "batch_payment_schedule_status": "scheduled", "payment_type": "collection_slip" } ``` ### Response Body Params | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------| | `batch_payment_schedule_key` * | uuid4 | Chave única de identificação do agendamento em lote. | | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `account_key` * | uuid4 | Chave da conta debitada. | | `total_amount` * | number | Soma dos valores (`payment_amount`) dos itens do lote. | | `batch_payment_schedule_status` * | [enum](#enumeradores-batch_payment_schedule_status) | Status do lote de agendamento após a solicitação. | | `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. | ### Enumeradores batch_payment_schedule_status | Enumerador | Descrição | |---------------|---------------| | `pending_2fa_approval` | Pendente de aprovação 2FA | | `scheduled` | Agendado | | `rejected` | Rejeitado | | `error` | Erro ao agendar | ### Enumeradores payment_type | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | :::danger Aviso O enumerador `bank_slip` não se aplica ao fluxo de agendamento em lote de faturas de recolhimento deste endpoint; para este caso, espera-se `payment_type` com valor `collection_slip`. ::: ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 400 | BIP000032 | Bad Request | The bill sent does not correspond to a collection slip. | A conta enviada não corresponde a uma fatura de recolhimento. | | 400 | BIP000033 | Bad Request | The barcode or digitable line of the collection slip must have 44 or 48 characters. | O código de barras ou linha digitável da fatura de recolhimento deve ter 44 ou 48 caracteres. | | 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação | | 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. | | 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. | | 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. | --- # Confirmação de lote de pagamento de boleto bancário URL: /documentation/baas/cobranca/confirmacao_de_lote_de_boleto_bancario Este endpoint permite **confirmar ou rejeitar** um lote de pagamento de boletos bancários previamente criado com [Solicitar pagamento em lote de boleto bancário](./solicitar_pagamento_lote_de_boleto_bancario_com_confirmacao_de_lote.md). A confirmação é a etapa que define se o processamento do lote segue (aprovação) ou é encerrado sem débito dos títulos (rejeição). :::info Boleto bancário É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/payment/batch_bank_slip/**PAYMENT_BATCH_KEY**/confirmation MÉTODO PATCH ### Request Path Params | Campo | Tipo | Descrição | Caracteres | | --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- | | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | | `payment_batch_key` * | uuid4 | Chave única de identificação do lote (`batch_payment_key` retornado na criação do lote). | 36 | ### Request Body **Request Body: Rejeição do lote** ```json { "batch_status": "rejected" } ``` **Request Body: Aprovação do lote** ```json { "batch_status": "approved" } ``` ### Body Params | Campo | Tipo | Descrição | | ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `batch_status` * | string | Decisão sobre o lote. Valores: `approved` (seguir com o processamento) ou `rejected` (cancelar o lote). Ver [enumerador batch_confirmation_status](#enumerador-batch_confirmation_status). | ### Enumerador batch_confirmation_status Valores aceitos no corpo da requisição para `batch_status`: | Valor | Descrição | | ---------- | ------------------------------------------------------------- | | `approved` | Aprovar o lote e continuar o fluxo de processamento. | | `rejected` | Rejeitar o lote; não há processamento assíncrono dos boletos. | ## Response ### Resposta: lote rejeitado STATUS 200 Quando `batch_status` no corpo da requisição é `rejected`, a API responde com **200**. O lote fica encerrado como rejeitado; não há fila assíncrona de pagamento dos boletos. **Response Body: Lote rejeitado** ```json { "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f", "total_amount": 1357.3, "batch_status": "rejected", "payment_type": "bank_slip" } ``` ### Resposta: lote aprovado — processamento assíncrono STATUS 202 Quando `batch_status` no corpo é `approved`, a API responde com **202** e o lote segue para **processamento assíncrono** dos boletos. O corpo retorna `batch_status` como `approved`. **Response Body: Lote aprovado para processamento assíncrono** ```json { "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f", "total_amount": 1357.3, "batch_status": "approved", "payment_type": "bank_slip" } ``` ### Response Body Params | Campo | Tipo | Descrição | | ----------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `batch_payment_key` * | uuid4 | Chave única de identificação do pagamento em lote. | | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `account_key` * | uuid4 | Chave da conta debitada. | | `total_amount` * | number | Soma dos valores dos itens do lote. | | `batch_status` * | string | Status do lote após esta chamada (`rejected` ou `approved` para o fluxo descrito nesta página). Alinhado ao ciclo de vida em [Solicitar pagamento em lote de boleto bancário — batch_payment_status](./solicitar_pagamento_lote_de_boleto_bancario_com_confirmacao_de_lote.md#enumeradores-batch_payment_status). | | `payment_type` * | string | Tipo do pagamento; para este fluxo, espera-se `bank_slip`. | ### Error Response STATUS 4XX **Response Body** ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | | ----------- | --------- | ----------- | --------------------------------------------- | ----------------------------------------------------- | | 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. | | 400 | BIP000050 | Bad Request | Requester configuration does not exist | Configuração do requester não existe. | | 404 | BIP000083 | Not Found | Batch payment not found by batch payment key. | Lote de pagamentos não encontrado pela chave do lote. | | 400 | BIP000084 | Bad Request | Batch payment status is not pending. | O status do lote de pagamentos não está pendente. | --- # Confirmação de lote de pagamento de fatura de recolhimento (convênio/tributo) URL: /documentation/baas/cobranca/confirmacao_de_lote_de_fatura_de_recolhimento Este endpoint permite **confirmar ou rejeitar** um lote de pagamento de faturas de recolhimento previamente criado com [Solicitar pagamento em lote de fatura de recolhimento (convênio/tributo)](./solicitar_pagamento_lote_de_fatura_de_recolhimento_com_confirmacao_de_lote.md). A confirmação é a etapa que define se o processamento do lote segue (aprovação) ou é encerrado sem débito dos títulos (rejeição). :::info Fatura de recolhimento Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um boleto bancário apresenta. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/payment/batch_collection_slip/**PAYMENT_BATCH_KEY**/confirmation MÉTODO PATCH ### Request Path Params | Campo | Tipo | Descrição | Caracteres | | --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- | | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | | `payment_batch_key` * | uuid4 | Chave única de identificação do lote (`batch_payment_key` retornado na criação do lote). | 36 | ### Request Body **Request Body: Rejeição do lote** ```json { "batch_status": "rejected" } ``` **Request Body: Aprovação do lote** ```json { "batch_status": "approved" } ``` ### Body Params | Campo | Tipo | Descrição | | ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `batch_status` * | string | Decisão sobre o lote. Valores: `approved` (seguir com o processamento) ou `rejected` (cancelar o lote). Ver [enumerador batch_confirmation_status](#enumerador-batch_confirmation_status). | ### Enumerador batch_confirmation_status Valores aceitos no corpo da requisição para `batch_status`: | Valor | Descrição | | ---------- | ----------------------------------------------------------------------------- | | `approved` | Aprovar o lote e continuar o fluxo de processamento. | | `rejected` | Rejeitar o lote; não há processamento assíncrono das faturas de recolhimento. | ## Response ### Resposta: lote rejeitado STATUS 200 Quando `batch_status` no corpo da requisição é `rejected`, a API responde com **200**. O lote fica encerrado como rejeitado; não há fila assíncrona de pagamento das faturas de recolhimento. **Response Body: Lote rejeitado** ```json { "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72", "total_amount": 2778.42, "batch_status": "rejected", "payment_type": "collection_slip" } ``` ### Resposta: lote aprovado — processamento assíncrono STATUS 202 Quando `batch_status` no corpo é `approved`, a API responde com **202** e o lote segue para **processamento assíncrono** das faturas de recolhimento. O corpo retorna `batch_status` como `approved`. **Response Body: Lote aprovado para processamento assíncrono** ```json { "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72", "total_amount": 2778.42, "batch_status": "approved", "payment_type": "collection_slip" } ``` ### Response Body Params | Campo | Tipo | Descrição | | ----------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `batch_payment_key` * | uuid4 | Chave única de identificação do pagamento em lote. | | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `account_key` * | uuid4 | Chave da conta debitada. | | `total_amount` * | number | Soma dos valores dos itens do lote. | | `batch_status` * | string | Status do lote após esta chamada (`rejected` ou `approved` para o fluxo descrito nesta página). Alinhado ao ciclo de vida em [Solicitar pagamento em lote de fatura de recolhimento — batch_payment_status](./solicitar_pagamento_lote_de_fatura_de_recolhimento_com_confirmacao_de_lote.md#enumeradores-batch_payment_status). | | `payment_type` * | string | Tipo do pagamento; para este fluxo, espera-se `collection_slip`. | ### Error Response STATUS 4XX **Response Body** ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | | ----------- | --------- | ----------- | --------------------------------------------- | ----------------------------------------------------- | | 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. | | 400 | BIP000050 | Bad Request | Requester configuration does not exist | Configuração do requester não existe. | | 404 | BIP000083 | Not Found | Batch payment not found by batch payment key. | Lote de pagamentos não encontrado pela chave do lote. | | 400 | BIP000084 | Bad Request | Batch payment status is not pending. | O status do lote de pagamentos não está pendente. | --- # Consulta de Boleto Bancário URL: /documentation/baas/cobranca/consultar_boleto_bancario Este endpoint é utilizado para consultar as informações de um boleto bancário. :::info Boleto bancário É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/bank_slip/ DIGITABLE_LINE or BARCODE MÉTODO GET ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |---------------------|---------|-----------------------------------|------------| | `digitable_line` | string | Linha digitável a ser consultada. | 47 | | `barcode` | string | Código de barras a ser consultado.| 44 | ### Request Query String Params | Campo | Tipo | Descrição | Caracteres | |---------------------|-------------|-----------------------------------|------------| | `payment_date` | string | Data do pagamento e que será levada em consideração nos cálculos dos valores do boleto. | YYYY-MM-DD | ## Response ### Success Response STATUS 200 Response Body: Boleto bancário disponível para pagamento ```json { "barcode":"00193967000009910000000003615574000000002417", "digitable_line":"00190000090361557400500000024174396700000991000", "payer_name":"COOPERATIVA AGRO.INDUSTRIAL TEST", "payer_document_number":"21063663000125", "beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA.", "beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA", "beneficiary_document_number":"30639204000138", "beneficiary_bank_ispb":"00000000", "guarantor_name":null, "guarantor_document_number":null, "expiration_date":"2024-03-29", "max_payment_data": "2026-03-29", "partial_payment_indicator":"not_allowed", "registered_payment_amount":null, "nominal_amount":9910.0, "total_amount":10129.1, "rebate_amount":0.0, "discount_amount":0.0, "fine_amount":0.0, "interest_amount":219.1 } ``` ### Response Body Params | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------| | `barcode` * | string | Código de barras. | | `digitable_line` * | string | Linha digitável. | | `payer_name` * | string | Nome do pagador.| | `payer_document_number` * | string | Número de documento do pagador (CPF/CNPJ). | | `beneficiary_name` * | string | Nome do beneficiário. | | `beneficiary_trading_name` | string | Nome fantasia do beneficiário. | | `beneficiary_document_number` * | string | Número de documento do beneficiário (CPF/CNPJ). | | `beneficiary_bank_ispb` * | string | Código ispb do banco do beneficiário. | | `guarantor_name` | string | Nome do sacador avalista. | | `guarantor_document_number` | string | Número de documento do sacador avalista (CPF/CNPJ). | | `expiration_date` * | string | Data de vencimento. | | `max_payment_date` * | string | Data máxima de pagamento. | | `partial_payment_indicator` * | [enum](#enumeradores-partial_payment_indicator) | Indicador de pagamento parcial | | `registered_payment_amount` | string | Valor total de pagamento registrado. | | `nominal_amount` * | number | Valor original. | | `total_amount` * | number | Valor total. | | `rebate_amount` * | number | Valor do abatimento. | | `discount_amount` * | number | Valor do desconto. | | `fine_amount` * | number | Valor da multa. | | `interest_amount` * | number | Valor do juros. | ### Enumeradores partial_payment_indicator | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `allowed` | string | Permitido | | `not_allowed` | string | Não permitido | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 400 | BIP000001 | Bad Request | The barcode or digitable line must have 44 or 47 characters. | O código de barras ou linha digitável deve ter 44 ou 47 caracteres. | | 400 | BIP000002 | Bad Request | The bill sent does not correspond to a bank slip. | A conta enviado não corresponde a um boleto bancário. | | 400 | BIP000003 | Bad Request | The digitable line sent is invalid. | A linha digitável enviada é inválida. | | 404 | BIP000004 | Not Found | The bank slip was not found. | O boleto não foi encontrado. | | 400 | BIP000005 | Bad Request | It was not possible to consult the bank slip at this time. Please try again in a few minutes. | Não foi possível consultar o boleto neste momento. Por favor, tente novamente em alguns minutos. | | 400 | BIP000006 | Bad Request | Bank slip already written off | Boleto já baixado | | 400 | BIP000007 | Bad Request | Bank slip blocked for payment | Boleto bloqueado para pagamento | | 400 | BIP000008 | Bad Request | Bank slip already paid | Boleto já pago | | 400 | BIP000009 | Bad Request | Invalid bank slip. Please consult issuing bank | Boleto inválido. Favor consultar banco emissor | ## Ambiente de Sandbox Em nosso ambiente de sandbox, disponibilizamos linhas digitáveis mockadas para a simulação de pagamentos bem-sucedidos e testes de cenários de erro. ### Cenários de sucesso | Linha digitável | |---| | 00190000090361557400500000024174396700000991000 | | 00190000090282802601919212747174596760001294161 | | 23793390014000000455277000249001596900000103995 | | 75691434020137513680900001040013196770002417240 | | 21390001171200000570700168167484796770000148206 | | 07790001161200000039300602819070498470000182970 | | 23792372059034189564835003432701998420000008306 | | 03399199530490000005254172701010698420000467696 | | 03399135012340000000830681701014198420038743888 | | 75691324620100735471370255730478698420064900819 | | 75691413310108906500520369970015899610000033705 | | 13695621010000389701400000037598810770000217000 | ### Cenários de erro | Linha digitável | Código de erro | |---|---| | 34191090083273252027893634770007296690012513600 | BIP000007 | | 07090010287045349010776686070590896770001160123 | BIP000007 | | 42297048060005815702500130494123896770000239491 | BIP000006 | | 74891123702849020818918378871083196690000050000 | BIP000009 | | 23792374119000209350986000372408496610000122810 | BIP000008 | --- # Consulta de Fatura de Recolhimento URL: /documentation/baas/cobranca/consultar_fatura_de_recolhimento Este endpoint é utilizado para consultar as informações de uma fatura de recolhimento. :::info Fatura de recolhimento Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgão públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta. Você pode conferir a lista de convênios aceitos pela QI Tech, bem como seus respectivos horários limite de pagamento, através deste [link](https://storage.googleapis.com/live-doc-api/public_samples/active_covenants.xlsx). ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/collection_slip/ DIGITABLE_LINE or BARCODE MÉTODO GET ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |---------------------|---------|-----------------------------------|------------| | `digitable_line` | string | Linha digitável a ser consultada. | 48 | | `barcode` | string | Código de barras a ser consultado.| 44 | ## Response ### Success Response STATUS 200 Response Body: Fatura de recolhimento disponível para pagamento ```json { "barcode": null, "digitable_line": "836200000138892100450006762142420244046000010192", "collection_name": "CIA ULTRAGAZ SA-COD", "expiration_date": "2024-04-15", "total_amount": 1389.21 } ``` ### Response Body Params | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------| | `barcode` | string | Código de barras. | | `digitable_line` | string | Linha digitável. | | `collection_name` * | string | Nome do convênio.| | `expiration_date` * | string | Data de vencimento. | | `total_amount` * | number | Valor total. | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 400 | BIP000032 | Bad Request | The bill sent does not correspond to a collection slip. | A conta enviada não corresponde a uma fatura de recolhimento. | | 400 | BIP000033 | Bad Request | The barcode or digitable line of the collection slip must have 44 or 48 characters. | O código de barras ou linha digitável da fatura de recolhimento deve ter 44 ou 48 caracteres. | | 400 | BIP000034 | Bad Request | Collection slip already paid. | Fatura de recolhimento já paga. | | 400 | BIP000035 | Bad Request | Covenant slip invalid barcode. | Código de barras da fatura de recolhimento inválido. | | 400 | BIP000036 | Bad Request | Covenant slip overdue. | Fatura de recolhimento vencida. | | 400 | BIP000037 | Bad Request | Error in collection slip consultation. | Erro na consulta da fatura de recolhimento. | | 400 | BIP000038 | Bad Request | Outside of covenant payment hours. | Fora do horário de pagamento do convênio. | | 400 | BIP000039 | Bad Request | Collection slip not accepted. | Fatura de recolhimento não aceita. | | 400 | BIP000040 | Bad Request | Minimum advance not reached. | Mínimo de dias de adiantamento não atingido. | | 400 | BIP000041 | Bad Request | Max payment amount exceeded. | Valor máximo de pagamento excedido. | ## Ambiente de Sandbox Em nosso ambiente de sandbox, disponibilizamos linhas digitáveis mockadas para a simulação de pagamentos bem-sucedidos e testes de cenários de erro. ### Cenários de sucesso | Linha digitável | |---| | 828300000007411100972013905080001546763201900028 | | 838000000009235700481007241345219112001474229880 | | 848000000006308600802021201071261517689002201070 | | 858200000015000000643025703477209504800448091020 | ### Cenários de erro | Linha digitável | Código de erro | |---|---| | 858500000037350000643217212883260006147448091022 | BIP000035 | --- # Consultar lote de pagamento URL: /documentation/baas/cobranca/consultar_lote_de_pagamento Este endpoint retorna o resumo do lote e a lista paginada dos pagamentos que o compõem (boletos bancários ou faturas de recolhimento). Para localizar `batch_payment_key`, utilize [Listar lotes de pagamento](./listar_lotes_de_pagamento.md). :::info Boleto bancário É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central. ::: :::info Fatura de recolhimento Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgão públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/batch/**BATCH_PAYMENT_KEY** MÉTODO GET ### Request Path Params | Campo | Tipo | Descrição | Caracteres | | --------------------- | ----- | -------------------------------------------------- | ---------- | | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | | `batch_payment_key` * | uuid4 | Chave única de identificação do pagamento em lote. | 36 | ### Request Query String Params | Campo | Tipo | Descrição | | ----------- | ------ | ----------------------------------------------------------------------------- | | `page` | string | Número da página dos itens em `payments.data`. 1 por padrão. | | `page_size` | string | Tamanho da página dos itens em `payments.data`. 30 por padrão e valor máximo. | ## Response ### Success Response STATUS 200 **Response Body: Detalhes do lote de pagamento** ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "total_paid": 10, "total_pending": 0, "total_error": 0, "total_amount": 1357.3, "payments": { "pagination": { "current_page": 1, "rows_per_page": 30 }, "data": [ { "payment_key": "c4325104-d60b-44f3-aae4-49155564a2ea", "payer_name": "COOPERATIVA INDUSTRIAL MURILO", "payer_document_number": "00037025000160", "source_account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f", "transaction_key": "4e80070a-a0bb-4be2-8178-55fbd73a3704", "transaction_revert_key": null, "paid_amount": 1050.1, "payment_date": "2024-04-03", "payment_type": "bank_slip", "bank_slip": { "bank_slip_key": "95080ffd-3ac5-48d7-b3fe-659e4aaba81a", "barcode": "00193967000009910000000003615574000000002417", "digitable_line": "00190000090361557400500000024174396700000991000", "payer_name": "COOPERATIVA TESTE", "payer_document_number": "00037025000160", "beneficiary_name": "TESTE EQUIPAMENTOS E SERVICOS LTDA", "beneficiary_trading_name": "TESTE EQUIPAMENTOS E SERVICOS LTDA", "beneficiary_document_number": "52069937000117", "beneficiary_bank_ispb": "00000000", "guarantor_name": null, "guarantor_document_number": null, "expiration_date": "2024-03-29", "max_payment_date": "2026-03-29", "partial_payment_indicator": "allowed", "registered_payment_amount": 9029.0, "nominal_amount": 9910.0, "total_amount": 10129.1, "rebate_amount": 0.0, "discount_amount": 0.0, "fine_amount": 0.0, "interest_amount": 219.1 }, "collection_slip": null, "payment_status": "executed", "error_reason": null } ] } } ``` ### Response Body Params | Campo | Tipo | Descrição | | ----------------------- | -------------------------- | ------------------------------------------------------------- | | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `total_paid` * | int | Quantidade de itens do lote pagos com sucesso. | | `total_pending` * | int | Quantidade de itens ainda pendentes no lote. | | `total_error` * | int | Quantidade de itens com erro no lote. | | `total_amount` * | number | Valor total do lote. | | `payments` * | [object](#objeto-payments) | Lista paginada dos pagamentos do lote. | ### Objeto payments | Campo | Tipo | Descrição | | -------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `pagination` * | [object](#objeto-pagination) | Paginação da lista de pagamentos do lote. | | `data` * | array | Itens do lote (estrutura equivalente a cada elemento de `data` em [Listar pagamentos](./listar_pagamentos.md), com campos adicionais abaixo). | Cada elemento de `payments.data` contém: | Campo | Tipo | Descrição | | ------------------------- | ------------------------------------ | ------------------------------------------------------------------------------ | | `payment_key` * | uuid4 | Chave única de identificação do pagamento. | | `payer_name` * | string | Nome do pagador efetivo. | | `payer_document_number` * | string | Número de documento do pagador efetivo (CPF/CNPJ). | | `source_account_key` * | uuid4 | Chave da conta debitada. | | `transaction_key` * | uuid4 | Chave da transação do pagamento. | | `transaction_revert_key` | uuid4 | Chave da transação de reversão do pagamento. | | `paid_amount` * | number | Valor pago efetivamente. | | `payment_date` * | string | Data do pagamento. | | `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. | | `bank_slip` | [object](#objeto-bank_slip) | Boleto bancário. Pode ser `null` quando `payment_type` for `collection_slip`. | | `collection_slip` | [object](#objeto-collection_slip) | Fatura de recolhimento. Pode ser `null` quando `payment_type` for `bank_slip`. | | `payment_status` * | [enum](#enumeradores-payment_status) | Status do pagamento. | | `error_reason` | string | Motivo do erro, quando aplicável; caso contrário `null`. | ### Objeto pagination | Campo | Tipo | Descrição | | ----------------- | ---- | ----------------------------------- | | `current_page` * | int | Página atual retornada. | | `rows_per_page` * | int | Quantidade de registros por página. | ### Enumeradores payment_type | Enumerador | Descrição | | ----------------- | ---------------------- | | `bank_slip` | Boleto bancário | | `collection_slip` | Fatura de recolhimento | ### Enumeradores payment_status | Enumerador | Descrição | | ------------------- | -------------------- | | `pending_execution` | Pendente de execução | | `executed` | Executado | | `reverted` | Revertido | | `rejected` | Rejeitado | | `error` | Erro | ### Objeto bank_slip | Campo | Tipo | Descrição | | ------------------------------- | ----------------------------------------------- | --------------------------------------------------- | | `bank_slip_key` * | uuid4 | Chave única de identificação do boleto bancário. | | `barcode` * | string | Código de barras. | | `digitable_line` * | string | Linha digitável. | | `payer_name` * | string | Nome do pagador. | | `payer_document_number` * | string | Número de documento do pagador (CPF/CNPJ). | | `beneficiary_name` * | string | Nome do beneficiário. | | `beneficiary_trading_name` | string | Nome fantasia do beneficiário. | | `beneficiary_document_number` * | string | Número de documento do beneficiário (CPF/CNPJ). | | `beneficiary_bank_ispb` * | string | Código ispb do banco do beneficiário. | | `guarantor_name` | string | Nome do sacador avalista. | | `guarantor_document_number` | string | Número de documento do sacador avalista (CPF/CNPJ). | | `expiration_date` * | string | Data de vencimento. | | `max_payment_date` * | string | Data máxima de pagamento. | | `partial_payment_indicator` * | [enum](#enumeradores-partial_payment_indicator) | Indicador de pagamento parcial. | | `registered_payment_amount` | number | Valor total de pagamento registrado. | | `nominal_amount` * | number | Valor original. | | `total_amount` * | number | Valor total. | | `rebate_amount` * | number | Valor do abatimento. | | `discount_amount` * | number | Valor do desconto. | | `fine_amount` * | number | Valor da multa. | | `interest_amount` * | number | Valor dos juros. | ### Enumeradores partial_payment_indicator | Enumerador | Descrição | | ------------- | ------------- | | `allowed` | Permitido | | `not_allowed` | Não permitido | ### Objeto collection_slip | Campo | Tipo | Descrição | | ------------------------------ | ------ | ------------------------------------------- | | `barcode` * | string | Código de barras. | | `digitable_line` * | string | Linha digitável. | | `collection_name` * | string | Nome do pagador. | | `collection_document_number` * | string | Número de documento do convênio (CPF/CNPJ). | | `expiration_date` * | string | Data de vencimento. | | `total_amount` * | number | Valor total. | ### Error Response STATUS 4XX **Response Body** ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | | ----------- | --------- | ----------- | --------------------------------------------------------------- | -------------------------------------------------------------- | | 400 | BIP000027 | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. | --- # Listar lotes de pagamento URL: /documentation/baas/cobranca/listar_lotes_de_pagamento Este endpoint retorna os lotes de pagamento de boletos bancários e faturas de recolhimento associados à conta, com suporte a filtros e paginação. :::info Boleto bancário É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central. ::: :::info Fatura de recolhimento Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgão públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/ ACCOUNT_KEY /batches MÉTODO GET ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | ### Request Query String Params | Campo | Tipo | Descrição | |---------------------|-------------|-----------------------------------| | `request_control_key` | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `batch_payment_key` | uuid4 | Chave única de identificação do pagamento em lote. | | `payment_type` | [enum](#enumeradores-payment_type) | Tipo do pagamento do lote. | | `batch_payment_status` | [enum](#enumeradores-batch_payment_status) | Status do lote. | | `date_from` | string | Data inicial. Formato "YYYY-MM-DD". | | `date_to` | string | Data final. Formato "YYYY-MM-DD". | | `page` | string | Número da página requisitada. 1 por padrão. | | `page_size` | string | Tamanho da página requisitada na consulta. 30 por padrão e valor máximo. | ### Enumeradores payment_type | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | ### Enumeradores batch_payment_status | Enumerador | Descrição | |---------------|---------------| | `pending` | Pendente de processamento | | `pending_2fa_approval` | Pendente de aprovação 2FA | | `rejected` | Rejeitado | | `approved` | Aprovado | | `processed` | Processado | ## Response ### Success Response STATUS 200 Response Body: Listagem de lotes de pagamento ```json { "pagination": { "current_page": 1, "rows_per_page": 30 }, "data": [ { "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "batch_status": "processed", "payment_type": "bank_slip", "total_paid": 10, "total_pending": 0, "total_error": 0, "total_amount": 1357.3 } ] } ``` ### Response Body Params | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------| | `pagination` * | [object](#objeto-pagination) | Informações de paginação da consulta. | | `data` * | array | Lista de lotes encontrados. | Cada elemento de `data` contém: | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------| | `batch_payment_key` * | uuid4 | Chave única de identificação do pagamento em lote. | | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `batch_status` * | [enum](#enumeradores-batch_payment_status-1) | Status atual do lote. | | `payment_type` * | [enum](#enumeradores-payment_type-1) | Tipo do pagamento do lote. | | `total_paid` * | int | Quantidade de itens do lote pagos com sucesso. | | `total_pending` * | int | Quantidade de itens ainda pendentes no lote. | | `total_error` * | int | Quantidade de itens com erro no lote. | | `total_amount` * | number | Valor total do lote. | ### Objeto pagination | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------| | `current_page` * | int | Página atual retornada. | | `rows_per_page` * | int | Quantidade de registros por página. | ### Enumeradores payment_type | Enumerador | Descrição | |---------------|---------------| | `bank_slip` | Boleto bancário | | `collection_slip` | Fatura de recolhimento | ### Enumeradores batch_payment_status | Enumerador | Descrição | |---------------|---------------| | `pending` | Pendente de processamento | | `pending_2fa_approval` | Pendente de aprovação 2FA | | `rejected` | Rejeitado | | `approved` | Aprovado | | `processed` | Processado | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 400 | BIP000026 | Bad Request | Invalid payment date format. The correct format is YYYY-MM-DD. | Formato de data de pagamento inválido. O formato correto é YYYY-MM-DD. | | 400 | BIP000027 | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. | | 400 | BIP000047 | Bad Request | Invalid payment type. | Tipo de pagamento inválido. | --- # Listar Pagamentos URL: /documentation/baas/cobranca/listar_pagamentos Este endpoint tem a finalidade de fornecer detalhes de todas as cobranças pagas pelo cliente, incluindo boletos bancários e Faturas de recolhimento. :::info Boleto bancário É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central. ::: :::info Fatura de recolhimento Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgão públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta. ::: ## Request ### Request Endpoint ENDPOINT /account/ ACCOUNT_KEY /payments MÉTODO GET ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | ### Request Query String Params | Campo | Tipo | Descrição | |---------------------|-------------|-----------------------------------| | `request_control_key` | uuid4 | Chave única de identificação da request do cliente. | | `payment_key` | uuid4 | Chave única de identificação do pagamento. | | `payment_schedule_key` | uuid4 | Chave única de identificação do agendamento de pagamento. | | `payment_type` | [enum](#enumeradores-payment_type) | Tipo do pagamento. | | `payment_status` | [enum](#enumeradores-payment_status) | Status do pagamento. | | `date_from` | string | Data inicial. Formato "YYYY-MM-DD". | | `date_to` | string | Data final. Formato "YYYY-MM-DD". | | `page` | string | Número da página requisitada. 1 por padrão. | | `page_size` | string | Tamanho da página requisitada na consulta. 30 por padrão e valor máximo. | ### Enumeradores payment_type | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | ### Enumeradores payment_status | Enumerador | Descrição | |---------------|---------------| | `pending_execution` | Pendente de execução | | `executed` | Executado | | `reverted` | Revertido | | `rejected` | Rejeitado | | `error` | Erro | ## Response ### Success Response STATUS 200 Response Body: Consulta de pagamentos ```json { "data": [ { "payment_key":"c4325104-d60b-44f3-aae4-49155564a2ea", "request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189", "payer_name":"COOPERATIVA INDUSTRIAL MURILO", "payer_document_number":"00037025000160", "source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f", "transaction_key":"4e80070a-a0bb-4be2-8178-55fbd73a3704", "transaction_revert_key":null, "paid_amount":1050.1, "payment_date":"2024-04-03", "payment_type":"bank_slip", "bank_slip": { "bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a", "barcode":"00193967000009910000000003615574000000002417", "digitable_line":"00190000090361557400500000024174396700000991000", "payer_name":"COOPERATIVA TESTE", "payer_document_number":"00037025000160", "beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA", "beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA", "beneficiary_document_number":"52069937000117", "beneficiary_bank_ispb":"00000000", "guarantor_name":null, "guarantor_document_number":null, "expiration_date":"2024-03-29", "max_payment_data": "2026-03-29", "partial_payment_indicator":"allowed", "registered_payment_amount":9029.0, "nominal_amount":9910.0, "total_amount":10129.1, "rebate_amount":0.0, "discount_amount":0.0, "fine_amount":0.0, "interest_amount":219.1 }, "collection_slip":null, "payment_status":"executed" } ], "pagination": { "current_page": 1, "rows_per_page": 30 } } ``` ### Response Body Params | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------| | `payment_key` * | uuid4 | Chave única de identificação do pagamento. | | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente. | | `payer_name` * | string | Nome do pagador efetivo.| | `payer_document_number` * | string | Número de documento do pagador efetivo (CPF/CNPJ). | | `source_account_key` * | uuid4 | Chave da conta debitada. | | `transaction_key` * | uuid4 | Chave da transação do pagamento. | | `transaction_revert_key` | uuid4 | Chave da transação de reversão do pagamento. | | `paid_amount` * | number | Valor pago efetivamente. | | `payment_date` * | string | Data do pagamento. | | `payment_type` * | [enum](#enumeradores-payment_type-1) | Tipo do pagamento. | | `bank_slip` | [object](#objeto-bank_slip) | Boleto bancário. | | `collection_slip` | [object](#objeto-collection_slip) | Fatura de recolhimento. | | `payment_status` * | [enum](#enumeradores-payment_status) | Status do pagamento. | ### Enumeradores payment_type | Enumerador | Descrição | |---------------|---------------| | `bank_slip` | Boleto bancário | | `collection_slip` | Fatura de recolhimento | ### Enumeradores payment_status | Enumerador | Descrição | |---------------|---------------| | `pending_execution` | Pendente de execução | | `executed` | Executado | | `reverted` | Revertido | | `rejected` | Rejeitado | | `error` | Erro | ### Objeto bank_slip | Campo | Tipo | Descrição | |-----------------------------------|---------|-----------------------------------| | `barcode` * | string | Código de barras. | | `digitable_line` * | string | Linha digitável. | | `payer_name` * | string | Nome do pagador.| | `payer_document_number` * | string | Número de documento do pagador (CPF/CNPJ). | | `beneficiary_name` * | string | Nome do beneficiário. | | `beneficiary_trading_name` | string | Nome fantasia do beneficiário. | | `beneficiary_document_number` * | string | Número de documento do beneficiário (CPF/CNPJ). | | `beneficiary_bank_ispb` * | string | Código ispb do banco do beneficiário. | | `guarantor_name` | string | Nome do sacador avalista. | | `guarantor_document_number` | string | Número de documento do sacador avalista (CPF/CNPJ). | | `expiration_date` * | string | Data de vencimento. | | `max_payment_date` * | string | Data máxima de pagamento. | | `partial_payment_indicator` * | [enum](#enumeradores-partial_payment_indicator) | Indicador de pagamento parcial. | | `registered_payment_amount` | string | Valor total de pagamento registrado. | | `nominal_amount` * | number | Valor original. | | `total_amount` * | number | Valor total. | | `rebate_amount` * | number | Valor do abatimento. | | `discount_amount` * | number | Valor do desconto. | | `fine_amount` * | number | Valor da multa. | | `interest_amount` * | number | Valor do juros. | ### Enumeradores partial_payment_indicator | Enumerador | Descrição | |---------------|---------------| | `allowed` | Permitido | | `not_allowed` | Não permitido | ### Objeto collection_slip | Campo | Tipo | Descrição | |-----------------------------------|---------|-----------------------------------| | `barcode` * | string | Código de barras. | | `digitable_line` * | string | Linha digitável. | | `collection_name` * | string | Nome do pagador.| | `collection_document_number` * | string | Número de documento do convênio (CPF/CNPJ). | | `expiration_date` * | string | Data de vencimento. | | `total_amount` * | number | Valor total. | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 400 | BIP000026 | Bad Request | Invalid payment date format. The correct format is YYYY-MM-DD. | Formato de data de pagamento inválido. O formato correto é YYYY-MM-DD. | | 400 | BIP000027 | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. | | 400 | BIP000047 | Bad Request | Invalid payment type. | Tipo de pagamento inválido. | --- # Realizar Pagamento de Boleto Bancário URL: /documentation/baas/cobranca/pagar_boleto_bancario Este endpoint permite realizar o pagamento de boletos bancários. O pagamento deve ser realizado após a consulta, utilizando as informações retornadas para garantir o funcionamento correto do fluxo, evitando falhas durante o processo de pagamento. :::info Boleto bancário É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central. ::: ## Request ### Request Endpoint ENDPOINT /account/ ACCOUNT_KEY /payment/bank_slip MÉTODO POST ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | Request Body: Pagamento de boleto bancário com linha digitável ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "digitable_line": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8 } ``` Request Body: Pagamento de boleto bancário com código de barras ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "barcode": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8 } ``` ### Body Params | Campo | Tipo | Descrição | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente. | | `barcode` | string | Código de barras. | | `digitable_line` | string | Linha digitável. | | `payment_amount` * | number | Valor a ser pago. | :::danger Aviso O `payment_amount` deve ser sempre igual ao `total_amount` retornado na consulta do boleto bancário caso o pagamento parcial não seja permitido para o boleto bancário. Para títulos em que o pagamento parcial é permitido, o cliente pode escolher arbitrariamente o `payment_amount`, podendo, inclusive, exceder o valor de face do boleto (`total_amount`). ::: ## Response ### Success Response STATUS 201 Response Body: Pagamento executado ```json { "payment_key":"c4325104-d60b-44f3-aae4-49155564a2ea", "request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189", "payer_name":"COOPERATIVA INDUSTRIAL MURILO", "payer_document_number":"00037025000160", "source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f", "transaction_key":"4e80070a-a0bb-4be2-8178-55fbd73a3704", "transaction_revert_key":null, "paid_amount":1050.1, "payment_date":"2024-04-03", "payment_type":"bank_slip", "bank_slip": { "bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a", "barcode":"00193967000009910000000003615574000000002417", "digitable_line":"00190000090361557400500000024174396700000991000", "payer_name":"COOPERATIVA TESTE", "payer_document_number":"00037025000160", "beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA", "beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA", "beneficiary_document_number":"52069937000117", "beneficiary_bank_ispb":"00000000", "guarantor_name":null, "guarantor_document_number":null, "expiration_date":"2024-03-29", "max_payment_data": "2026-03-29", "partial_payment_indicator":"allowed", "registered_payment_amount":9029.0, "nominal_amount":9910.0, "total_amount":10129.1, "rebate_amount":0.0, "discount_amount":0.0, "fine_amount":0.0, "interest_amount":219.1 }, "collection_slip":null, "payment_status":"executed" } ``` STATUS 202 Response Body: Pagamento pendente de execução ```json { "payment_key":"c4325104-d60b-44f3-aae4-49155564a2ea", "request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189", "payer_name":"COOPERATIVA INDUSTRIAL MURILO", "payer_document_number":"00037025000160", "source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f", "transaction_key":"4e80070a-a0bb-4be2-8178-55fbd73a3704", "transaction_revert_key":null, "paid_amount":1050.1, "payment_date":"2024-04-03", "payment_type":"bank_slip", "bank_slip": { "bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a", "barcode":"00193967000009910000000003615574000000002417", "digitable_line":"00190000090361557400500000024174396700000991000", "payer_name":"COOPERATIVA TESTE", "payer_document_number":"00037025000160", "beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA", "beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA", "beneficiary_document_number":"52069937000117", "beneficiary_bank_ispb":"00000000", "guarantor_name":null, "guarantor_document_number":null, "expiration_date":"2024-03-29", "max_payment_data": "2026-03-29", "partial_payment_indicator":"allowed", "registered_payment_amount":9029.0, "nominal_amount":9910.0, "total_amount":10129.1, "rebate_amount":0.0, "discount_amount":0.0, "fine_amount":0.0, "interest_amount":219.1 }, "collection_slip":null, "payment_status": "pending_execution" } ``` :::info Informação Caso seja retornado **HTTP Status 202** com o campo `payment_status` com valor **pending_execution**, o pagamento não deve ser retentado. Esta esse pagamento será processado assincronamente. É necessário verificar o status da transferência por meio da consulta de pagamento, ou aguardar envio do webhook de pagamento pendente descrito na [página de webhooks](/documentation/baas/cobranca/webhooks). ::: ### Response Body Params | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------| | `payment_key` * | uuid4 | Chave única de identificação do pagamento. | | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente. | | `payer_name` * | string | Nome do pagador efetivo.| | `payer_document_number` * | string | Número de documento do pagador efetivo (CPF/CNPJ). | | `source_account_key` * | uuid4 | Chave da conta debitada. | | `transaction_key` * | uuid4 | Chave da transação do pagamento. | | `transaction_revert_key` | uuid4 | Chave da transação de reversão do pagamento. | | `paid_amount` * | number | Valor pago efetivamente. | | `payment_date` * | string | Data do pagamento. | | `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. | | `bank_slip` | [object](#objeto-bank_slip) | Boleto bancário. | | `collection_slip` | object | Fatura de recolhimento. | | `payment_status` * | [enum](#enumeradores-payment_status) | Status do pagamento. | ### Enumeradores payment_type | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | :::danger Aviso O enumerador `collection_slip` não se aplica para o fluxo de boletos bancários, assim como o objeto collection_slip que sempre será nulo. ::: ### Enumeradores payment_status | Enumerador | Descrição | |---------------|---------------| | `pending_execution` | Pendente de execução | | `executed` | Executado | | `reverted` | Revertido | | `rejected` | Rejeitado | | `error` | Erro | :::danger Aviso Para pagamentos onde a QI não receber uma resposta da CIP em até dois minutos, o pagamento será retornado com o status `pending_execution`. Após a QI receber a resposta da CIP, será enviado para o cliente o webhook de pagamento pendente descrito na [página de webhooks](/documentation/baas/cobranca/webhooks). ::: ### Objeto bank_slip | Campo | Tipo | Descrição | |-----------------------------------|---------|-----------------------------------| | `barcode` * | string | Código de barras. | | `digitable_line` * | string | Linha digitável. | | `payer_name` * | string | Nome do pagador.| | `payer_document_number` * | string | Número de documento do pagador (CPF/CNPJ). | | `beneficiary_name` * | string | Nome do beneficiário. | | `beneficiary_trading_name` | string | Nome fantasia do beneficiário. | | `beneficiary_document_number` * | string | Número de documento do beneficiário (CPF/CNPJ). | | `beneficiary_bank_ispb` * | string | Código ispb do banco do beneficiário. | | `guarantor_name` | string | Nome do sacador avalista. | | `guarantor_document_number` | string | Número de documento do sacador avalista (CPF/CNPJ). | | `expiration_date` * | string | Data de vencimento. | | `max_payment_date` * | string | Data máxima de pagamento. | | `partial_payment_indicator` * | [enum](#enumeradores-partial_payment_indicator) | Indicador de pagamento parcial. | | `registered_payment_amount` | string | Valor total de pagamento registrado. | | `nominal_amount` * | number | Valor original. | | `total_amount` * | number | Valor total. | | `rebate_amount` * | number | Valor do abatimento. | | `discount_amount` * | number | Valor do desconto. | | `fine_amount` * | number | Valor da multa. | | `interest_amount` * | number | Valor do juros. | ### Enumeradores partial_payment_indicator | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `allowed` | string | Permitido | | `not_allowed` | string | Não permitido | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 400 | BIP000001 | Bad Request | The barcode or digitable line must have 44 or 47 characters. | O código de barras ou linha digitável deve ter 44 ou 47 caracteres. | | 400 | BIP000002 | Bad Request | The bill sent does not correspond to a bank slip. | A conta enviado não corresponde a um boleto bancário. | | 400 | BIP000003 | Bad Request | The digitable line sent is invalid. | A linha digitável enviada é inválida. | | 404 | BIP000004 | Not Found | The bank slip was not found. | O boleto não foi encontrado. | | 400 | BIP000005 | Bad Request | It was not possible to consult the bank slip at this time. Please try again in a few minutes. | Não foi possível consultar o boleto neste momento. Por favor, tente novamente em alguns minutos. | | 400 | BIP000006 | Bad Request | Bank slip already written off | Boleto já baixado | | 400 | BIP000007 | Bad Request | Bank slip blocked for payment | Boleto bloqueado para pagamento | | 400 | BIP000008 | Bad Request | Bank slip already paid | Boleto já pago | | 400 | BIP000009 | Bad Request | Invalid bank slip. Please consult issuing bank | Boleto inválido. Favor consultar banco emissor | | 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação | | 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. | | 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. | | 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. | | 400 | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. | | 400 | BIP000015 | Bad Request | Payment date is greater than the maximum payment date. | A data de pagamento é maior que a data máxima de pagamento. | | 400 | BIP000016 | Bad Request | Payment date is smaller than the calculation date. | A data de pagamento é menor que a data de cálculo. | | 400 | BIP000017 | Bad Request | Invalid payment amount. | Valor de pagamento inválido. | | 400 | BIP000018 | Bad Request | Partial payment is not allowed. | Pagamento parcial não é permitido. | | 400 | BIP000019 | Bad Request | The payment amount is greater than the available amount. | O valor do pagamento é maior que o valor disponível. | | 400 | BIP000020 | Bad Request | All partial payments for this bank slip have already been made. | Todos os pagamentos parciais deste boleto já foram realizados. | | 400 | BIP000022 | Bad Request | Bank slip payment service is closed. | Serviço de pagamento de boleto está fechado. | | 400 | BIP000023 | Bad Request | The source account has insufficient balance. Payment cannot be made. | A conta de origem possui saldo insuficiente. Pagamento não pode ser realizado. | | 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. | | 400 | BIP000025 | Bad Request | It was not possible to pay the bank slip at this time. Please verify your information and, if necessary, contact us for assistance. | Não foi possível pagar o boleto neste momento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para assistência. | | 400 | BIP000028 | Bad Request | The source account has blocked balance. Payment cannot be made. | A conta de origem possui saldo em conta bloqueado. Pagamento não pode ser realizado. | ## Ambiente de Sandbox Em nosso ambiente de sandbox, disponibilizamos linhas digitáveis mockadas para a simulação de pagamentos bem-sucedidos e testes de cenários de erro. ### Cenários de sucesso | Linha digitável | |---| | 00190000090361557400500000024174396700000991000 | | 00190000090282802601919212747174596760001294161 | | 23793390014000000455277000249001596900000103995 | | 75691434020137513680900001040013196770002417240 | | 21390001171200000570700168167484796770000148206 | | 07790001161200000039300602819070498470000182970 | | 23792372059034189564835003432701998420000008306 | | 03399199530490000005254172701010698420000467696 | | 03399135012340000000830681701014198420038743888 | | 75691324620100735471370255730478698420064900819 | ### Cenários de `pending_execution` A simulação desse cenário está melhor descrita na [página de simulações](/documentation/baas/cobranca/simulacao). | Linha digitável | |---| | 75691333790100505390300569460017397220000306867 | ### Cenários de erro | Linha digitável | Código de erro | |---|---| | 34191090083273252027893634770007296690012513600 | BIP000007 | | 07090010287045349010776686070590896770001160123 | BIP000007 | | 42297048060005815702500130494123896770000239491 | BIP000006 | | 74891123702849020818918378871083196690000050000 | BIP000009 | | 23792374119000209350986000372408496610000122810 | BIP000008 | --- # Realizar Pagamento de Fatura de Recolhimento (convênio/tributo) URL: /documentation/baas/cobranca/pagar_fatura_de_recolhimento Este endpoint permite realizar o pagamento de faturas de recolhimento. O pagamento deve ser realizado após a consulta, utilizando as informações retornadas na mesma, para garantir o funcionamento correto do fluxo evitando falhas durante o processo de pagamento. :::info Fatura de recolhimento Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgão públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta. ::: ## Request ### Request Endpoint ENDPOINT /account/ ACCOUNT_KEY /payment/collection_slip MÉTODO POST ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | Request Body: Pagamento de fatura de recolhimento com linha digitável ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "digitable_line": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8 } ``` Request Body: Pagamento de fatura de recolhimento com código de barras ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "barcode": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8 } ``` ### Body Params | Campo | Tipo | Descrição | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente. | | `barcode` | string | Código de barras. | | `digitable_line` | string | Linha digitável. | | `payment_amount` * | number | Valor a ser pago. | :::danger Aviso O `payment_amount` deve sempre igual ao `total_amount` retornado na consulta do boleto bancário. ::: ## Response ### Success Response STATUS 201 Response Body: Pagamento executado ```json { "payment_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a", "request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9", "payer_name": "COOPERATIVA INDUSTRIAL MURILO", "payer_document_number": "62069937000118", "source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72", "transaction_key": "fc9ccfd0-2f21-4207-9772-69238be74152", "transaction_revert_key": null, "paid_amount": 1389.21, "payment_date": "2024-04-30", "payment_type": "collection_slip", "bank_slip": null, "collection_slip": { "barcode": null, "digitable_line": "836200000138892100450006762142420244046000010192", "collection_name": "CIA ULTRAGAZ SA-COD", "collection_document_number": "00394460005887", "expiration_date": "2024-04-15", "total_amount": 1389.21 }, "payment_status": "executed" } ``` STATUS 202 :::info Webhook Quando o pagamento retornar status `202`, o processamento ainda está em andamento. **Não realize uma nova tentativa de pagamento** enquanto não receber a atualização do status final via webhook. ::: Response Body: Pagamento pendente ```json { "payment_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a", "request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9", "payer_name": "COOPERATIVA INDUSTRIAL MURILO", "payer_document_number": "62069937000118", "source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72", "transaction_key": "fc9ccfd0-2f21-4207-9772-69238be74152", "transaction_revert_key": null, "paid_amount": 1389.21, "payment_date": "2024-04-30", "payment_type": "collection_slip", "bank_slip": null, "collection_slip": { "barcode": null, "digitable_line": "836200000138892100450006762142420244046000010192", "collection_name": "CIA ULTRAGAZ SA-COD", "collection_document_number": "00394460005887", "expiration_date": "2024-04-15", "total_amount": 1389.21 }, "payment_status": "pending" } ``` ### Response Body Params | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------| | `payment_key` * | uuid4 | Chave única de identificação do pagamento. | | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente. | | `payer_name` * | string | Nome do pagador efetivo.| | `payer_document_number` * | string | Número de documento do pagador efetivo (CPF/CNPJ). | | `source_account_key` * | uuid4 | Chave da conta debitada. | | `transaction_key` * | uuid4 | Chave da transação do pagamento. | | `transaction_revert_key` | uuid4 | Chave da transação de reversão do pagamento. | | `paid_amount` * | number | Valor pago efetivamente. | | `payment_date` * | string | Data do pagamento. | | `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. | | `bank_slip` | object | Boleto bancário. | | `collection_slip` | [object](#objeto-collection_slip) | Fatura de recolhimento. | | `payment_status` * | [enum](#enumeradores-payment_status) | Status do pagamento. | ### Enumeradores payment_type | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | :::danger Aviso O enumerador `bank_slip` não se aplica para o fluxo de faturas de recolhimento, assim como o objeto bank_slip que sempre será nulo. ::: ### Enumeradores payment_status | Enumerador | Descrição | |---------------|---------------| | `pending` | Pendente | | `executed` | Executado | | `reverted` | Revertido | | `rejected` | Rejeitado | | `error` | Erro | ### Objeto collection_slip | Campo | Tipo | Descrição | |-----------------------------------|---------|-----------------------------------| | `barcode` | string | Código de barras. | | `digitable_line` | string | Linha digitável. | | `collection_name` * | string | Nome do convênio.| | `collection_document_number` | string | Número de documento do convênio (CPF/CNPJ).| | `expiration_date` * | string | Data de vencimento. | | `total_amount` * | number | Valor total. | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 400 | BIP000032 | Bad Request | The bill sent does not correspond to a collection slip. | A conta enviada não corresponde a uma fatura de recolhimento. | | 400 | BIP000033 | Bad Request | The barcode or digitable line of the collection slip must have 44 or 48 characters. | O código de barras ou linha digitável da fatura de recolhimento deve ter 44 ou 48 caracteres. | | 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação | | 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. | | 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. | | 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. | | 400 | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. | | 400 | BIP000023 | Bad Request | The source account has insufficient balance. Payment cannot be made. | A conta de origem possui saldo insuficiente. Pagamento não pode ser realizado. | | 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. | | 400 | BIP000028 | Bad Request | The source account has blocked balance. Payment cannot be made. | A conta de origem possui saldo em conta bloqueado. Pagamento não pode ser realizado. | | 400 | BIP000034 | Bad Request | Collection slip already paid. | Fatura de recolhimento já paga. | | 400 | BIP000035 | Bad Request | Covenant slip invalid barcode. | Código de barras da fatura de recolhimento inválido. | | 400 | BIP000036 | Bad Request | Covenant slip overdue. | Fatura de recolhimento vencida. | | 400 | BIP000037 | Bad Request | Error in collection slip consultation. | Erro na consulta da fatura de recolhimento. | | 400 | BIP000038 | Bad Request | Outside of covenant payment hours. | Fora do horário de pagamento do convênio. | | 400 | BIP000039 | Bad Request | Collection slip not accepted. | Fatura de recolhimento não aceita. | | 400 | BIP000040 | Bad Request | Minimum advance not reached. | Mínimo de dias de adiantamento não atingido. | | 400 | BIP000041 | Bad Request | Max payment amount exceeded. | Valor máximo de pagamento excedido. | | 400 | BIP000044 | Bad Request | It was not possible to pay the collection slip at this time. Please verify your information and, if necessary, contact us for assistance. | Não foi possível pagar a fatura de recolhimento neste momento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para assistência. | | 400 | BIP000045 | Bad Request | Collection slip payment service is closed. | Serviço de pagamento de fatura de recolhimento está fechado. | ## Ambiente de Sandbox Em nosso ambiente de sandbox, disponibilizamos linhas digitáveis mockadas para a simulação de pagamentos bem-sucedidos e testes de cenários de erro. ### Cenários de sucesso | Linha digitável | |---| | 828300000007411100972013905080001546763201900028 | | 838000000009235700481007241345219112001474229880 | | 848000000006308600802021201071261517689002201070 | | 858200000015000000643025703477209504800448091020 | ### Cenários de erro | Linha digitável | Código de erro | |---|---| | 858500000037350000643217212883260006147448091022 | BIP000035 | --- # Simulação de cenários URL: /documentation/baas/cobranca/simulacao_de_cenarios ## 1 - Simulação de pagamento em estado pendente de execução Para pagamentos aonde a QI não receber uma resposta da CIP em até dois minutos, o pagamento será retornado com o status `pending_execution`. Após a QI receber a resposta da CIP, será enviado para o cliente o webhook de pagamento pendente descrito na [página de webhooks](/documentation/baas/cobranca/webhooks). Para simular este cenário, realize um pagamento com linha digitável `"digitable_line": "75691333790100505390300569460017397220000306867"`. Para que o status do pagamento seja atualizado, realize a requisição abaixo com `payment_status` de **approved** para aprovar o pagamento, ou **rejected** para reprová-lo. ## Request ### Request Endpoint ENDPOINT /mock/account/ ACCOUNT_KEY /payment/ PAYMENT_KEY /bank_slip/confirmation MÉTODO PATCH ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | | `payment_key` * | uuid4 | Chave única de identificação do pagamento. | 36 | Request Body: Simulação de confirmação de pagamento ```json { "payment_status": "approved", } ``` ### Body Parameters | Campo | Tipo | Descrição | |-----------------------------|--------|-----------------------------------------------------------------------| | `payment_status` * | [enum](#enumeradores-payment_status) | Status do pagamento | ### Enumeradores payment_status | Enumerador |Descrição | |--------------|-----------| | `approved` | Aprovar e concluir o pagamento | | `rejected` | Rejeitar e reverter o pagamento | ## Response ### Success Response STATUS 204 Response Body: Simulação concluída ```json {} ``` --- # Solicitar Pagamento em Lote de Boleto Bancário URL: /documentation/baas/cobranca/solicitar_pagamento_lote_de_boleto_bancario_com_confirmacao_de_lote Este endpoint permite solicitar o pagamento de múltiplos boletos bancários em uma única requisição. :::info Boleto bancário É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central. ::: :::info Fluxo após a solicitação Após a solicitação, o lote pode permanecer aguardando a [confirmação do lote](./confirmacao_de_lote_de_boleto_bancario.md), conforme as regras da operação. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments/batch_bank_slip MÉTODO POST ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | Request Body: Pagamento em lote de boletos bancários ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "bank_slip_payments": [ { "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd", "digitable_line": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8 }, { "request_control_key": "d8a26b54-323a-4924-0aed-e4fe6e4e4c0e", "barcode": "00190000090361557400500000024174396700000991000", "payment_amount": 200.5 } ] } ``` ### Body Params | Campo | Tipo | Descrição | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `bank_slip_payments` * | array | Lista de pagamentos de boleto bancário. Limite de **1000** itens por requisição. | Cada elemento de `bank_slip_payments` deve conter: | Campo | Tipo | Descrição | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente para aquele item do lote. | | `barcode` | string | Código de barras. | | `digitable_line` | string | Linha digitável. | | `payment_amount` * | number | Valor a ser pago. | :::danger Aviso Para cada item, o `payment_amount` enviado deve ser compatível com o que a consulta interna do boleto determinar: se o pagamento parcial **não** for permitido para aquele título, o valor deve corresponder ao total atualizado; se for permitido, o `payment_amount` pode seguir as regras do título (incluindo, quando aplicável, valores acima do nominal), como no fluxo de pagamento unitário de boleto bancário. ::: ## Response ### Success Response STATUS 202 Response Body: Lote aceito para processamento ```json { "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f", "total_amount": 1357.3, "batch_status": "pending", "payment_type": "bank_slip" } ``` Response Body: exemplo ilustrativo (`batch_status` aprovado) ```json { "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f", "total_amount": 1357.3, "batch_status": "approved", "payment_type": "bank_slip" } ``` :::info Processamento do lote O campo `batch_status` na resposta indica o **estado imediato** do lote após esta solicitação (por exemplo, pendente de confirmação ou já encaminhado ao processamento), conforme o fluxo aplicável. Quando houver etapa de [confirmação do lote](./confirmacao_de_lote_de_boleto_bancario.md), utilize essa chamada para aprovar ou rejeitar o lote antes do débito dos títulos. Os valores possíveis de `batch_status` estão em [batch_payment_status](#enumeradores-batch_payment_status). ::: ### Response Body Params | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------| | `batch_payment_key` * | uuid4 | Chave única de identificação do pagamento em lote. | | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `account_key` * | uuid4 | Chave da conta debitada. | | `total_amount` * | number | Soma dos valores (`payment_amount`) dos itens do lote. | | `batch_status` * | [enum](#enumeradores-batch_payment_status) | Status do lote logo após a solicitação; depende do fluxo (confirmação e processamento imediato). | | `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. | ### Enumeradores batch_payment_status | Enumerador | Descrição | |---------------|---------------| | `pending` | Pendente de processamento | | `pending_2fa_approval` | Pendente de aprovação 2FA | | `rejected` | Rejeitado | | `approved` | Aprovado | | `processed` | Processado | ### Enumeradores payment_type | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | :::danger Aviso O enumerador `collection_slip` não se aplica ao fluxo de lote de boletos bancários deste endpoint; para este caso, espera-se `payment_type` com valor `bank_slip`. ::: ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação | | 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. | | 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. | | 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. | | 400 | BIP000050 | Bad Request | Requester configuration does not exist. | Configuração do requester não existe. | | 400 | BIP000080 | Bad Request | Beneficiary bank code of this bank slip is not allowed. | Banco beneficiário desse boleto não é permitido. | | 400 | BIP000081 | Bad Request | A list of bank slip payments must be provided. | Uma lista de boletos bancários deve ser fornecida. | --- # Solicitar Pagamento em Lote de Boleto Bancário URL: /documentation/baas/cobranca/solicitar_pagamento_lote_de_boleto_bancario_sem_confirmacao_de_lote Este endpoint permite solicitar o pagamento de múltiplos boletos bancários em uma única requisição. :::info Boleto bancário É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central. ::: :::info Fluxo após a solicitação Após a solicitação, o lote é encaminhado conforme o processamento definido para a operação. O campo `batch_status` reflete o estado imediato (por exemplo, pendente de processamento ou já em fila de débito). Os valores possíveis estão em [batch_payment_status](#enumeradores-batch_payment_status). ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments/batch_bank_slip MÉTODO POST ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | Request Body: Pagamento em lote de boletos bancários ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "bank_slip_payments": [ { "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd", "digitable_line": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8 }, { "request_control_key": "d8a26b54-323a-4924-0aed-e4fe6e4e4c0e", "barcode": "00190000090361557400500000024174396700000991000", "payment_amount": 200.5 } ] } ``` ### Body Params | Campo | Tipo | Descrição | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `bank_slip_payments` * | array | Lista de pagamentos de boleto bancário. Limite de **1000** itens por requisição. | Cada elemento de `bank_slip_payments` deve conter: | Campo | Tipo | Descrição | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente para aquele item do lote. | | `barcode` | string | Código de barras. | | `digitable_line` | string | Linha digitável. | | `payment_amount` * | number | Valor a ser pago. | :::danger Aviso Para cada item, o `payment_amount` enviado deve ser compatível com o que a consulta interna do boleto determinar: se o pagamento parcial **não** for permitido para aquele título, o valor deve corresponder ao total atualizado; se for permitido, o `payment_amount` pode seguir as regras do título (incluindo, quando aplicável, valores acima do nominal), como no fluxo de pagamento unitário de boleto bancário. ::: ## Response ### Success Response STATUS 202 Response Body: Lote aceito para processamento ```json { "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f", "total_amount": 1357.3, "batch_status": "pending", "payment_type": "bank_slip" } ``` Response Body: exemplo ilustrativo com `batch_status` aprovado ```json { "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f", "total_amount": 1357.3, "batch_status": "approved", "payment_type": "bank_slip" } ``` :::info Processamento do lote O campo `batch_status` na resposta indica o **estado imediato** do lote após esta solicitação (por exemplo, pendente de processamento ou já encaminhado ao processamento dos títulos), conforme o fluxo aplicável. Os valores possíveis de `batch_status` estão em [batch_payment_status](#enumeradores-batch_payment_status). ::: ### Response Body Params | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------| | `batch_payment_key` * | uuid4 | Chave única de identificação do pagamento em lote. | | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `account_key` * | uuid4 | Chave da conta debitada. | | `total_amount` * | number | Soma dos valores (`payment_amount`) dos itens do lote. | | `batch_status` * | [enum](#enumeradores-batch_payment_status) | Status do lote logo após a solicitação; depende do processamento imediato e das regras da operação. | | `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. | ### Enumeradores batch_payment_status | Enumerador | Descrição | |---------------|---------------| | `pending` | Pendente de processamento | | `pending_2fa_approval` | Pendente de aprovação 2FA | | `rejected` | Rejeitado | | `approved` | Aprovado | | `processed` | Processado | ### Enumeradores payment_type | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | :::danger Aviso O enumerador `collection_slip` não se aplica ao fluxo de lote de boletos bancários deste endpoint; para este caso, espera-se `payment_type` com valor `bank_slip`. ::: ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação | | 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. | | 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. | | 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. | | 400 | BIP000050 | Bad Request | Requester configuration does not exist. | Configuração do requester não existe. | | 400 | BIP000080 | Bad Request | Beneficiary bank code of this bank slip is not allowed. | Banco beneficiário desse boleto não é permitido. | | 400 | BIP000081 | Bad Request | A list of bank slip payments must be provided. | Uma lista de boletos bancários deve ser fornecida. | --- # Solicitar Pagamento em Lote de Fatura de Recolhimento (convênio/tributo) URL: /documentation/baas/cobranca/solicitar_pagamento_lote_de_fatura_de_recolhimento_com_confirmacao_de_lote Este endpoint permite solicitar o pagamento de múltiplas faturas de recolhimento em uma única requisição. :::info Fatura de recolhimento Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um boleto bancário apresenta. ::: :::info Fluxo após a solicitação Após a solicitação, o lote pode permanecer aguardando a [confirmação do lote](./confirmacao_de_lote_de_fatura_de_recolhimento.md), conforme as regras da operação. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments/batch_collection_slip MÉTODO POST ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | Request Body: Pagamento em lote de faturas de recolhimento ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "collection_slip_payments": [ { "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd", "digitable_line": "836200000138892100450006762142420244046000010192", "payment_amount": 1389.21 }, { "request_control_key": "d8a26b54-323a-4924-0aed-e4fe6e4e4c0e", "barcode": "83620000001388921004500067621424202440460000101", "payment_amount": 1389.21 } ] } ``` ### Body Params | Campo | Tipo | Descrição | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `collection_slip_payments` * | array | Lista de pagamentos de fatura de recolhimento. Limite de **1000** itens por requisição. | Cada elemento de `collection_slip_payments` deve conter: | Campo | Tipo | Descrição | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente para aquele item do lote. | | `barcode` | string | Código de barras. | | `digitable_line` | string | Linha digitável. | | `payment_amount` * | number | Valor a ser pago. | :::danger Aviso Para cada item, o `payment_amount` enviado deve ser compatível com o que a consulta interna da fatura de recolhimento determinar (por exemplo, alinhado ao `total_amount` e às regras do convênio/tributo), nas mesmas condições do fluxo de pagamento unitário de fatura de recolhimento. ::: ## Response ### Success Response STATUS 202 Response Body: Lote aceito para processamento ```json { "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72", "total_amount": 2778.42, "batch_status": "pending", "payment_type": "collection_slip" } ``` Response Body: exemplo ilustrativo (`batch_status` aprovado) ```json { "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72", "total_amount": 2778.42, "batch_status": "approved", "payment_type": "collection_slip" } ``` :::info Processamento do lote O campo `batch_status` na resposta indica o **estado imediato** do lote após esta solicitação (por exemplo, pendente de confirmação ou já encaminhado ao processamento), conforme o fluxo aplicável. Quando houver etapa de [confirmação do lote](./confirmacao_de_lote_de_fatura_de_recolhimento.md), utilize essa chamada para aprovar ou rejeitar o lote antes do débito dos títulos. Os valores possíveis de `batch_status` estão em [batch_payment_status](#enumeradores-batch_payment_status). ::: ### Response Body Params | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------| | `batch_payment_key` * | uuid4 | Chave única de identificação do pagamento em lote. | | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `account_key` * | uuid4 | Chave da conta debitada. | | `total_amount` * | number | Soma dos valores (`payment_amount`) dos itens do lote. | | `batch_status` * | [enum](#enumeradores-batch_payment_status) | Status do lote logo após a solicitação; depende do fluxo (confirmação e processamento imediato). | | `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. | ### Enumeradores batch_payment_status | Enumerador | Descrição | |---------------|---------------| | `pending` | Pendente de processamento | | `pending_2fa_approval` | Pendente de aprovação 2FA | | `rejected` | Rejeitado | | `approved` | Aprovado | | `processed` | Processado | ### Enumeradores payment_type | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | :::danger Aviso O enumerador `bank_slip` não se aplica ao fluxo de lote de faturas de recolhimento deste endpoint; para este caso, espera-se `payment_type` com valor `collection_slip`. ::: ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. | | 400 | BIP000050 | Bad Request | Requester configuration does not exist. | Configuração do requester não existe. | | 400 | BIP000082 | Bad Request | A list of collection slip payments must be provided. | Uma lista de faturas de recolhimento deve ser fornecida. | --- # Solicitar Pagamento em Lote de Fatura de Recolhimento (convênio/tributo) URL: /documentation/baas/cobranca/solicitar_pagamento_lote_de_fatura_de_recolhimento_sem_confirmacao_de_lote Este endpoint permite solicitar o pagamento de múltiplas faturas de recolhimento em uma única requisição. :::info Fatura de recolhimento Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um boleto bancário apresenta. ::: :::info Fluxo após a solicitação Após a solicitação, o lote é encaminhado conforme o processamento definido para a operação. O campo `batch_status` reflete o estado imediato (por exemplo, pendente de processamento ou já em fila de débito). Os valores possíveis estão em [batch_payment_status](#enumeradores-batch_payment_status). ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments/batch_collection_slip MÉTODO POST ### Request Path Params | Campo | Tipo | Descrição | Caracteres | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da conta. | 36 | Request Body: Pagamento em lote de faturas de recolhimento ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "collection_slip_payments": [ { "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd", "digitable_line": "836200000138892100450006762142420244046000010192", "payment_amount": 1389.21 }, { "request_control_key": "d8a26b54-323a-4924-0aed-e4fe6e4e4c0e", "barcode": "83620000001388921004500067621424202440460000101", "payment_amount": 1389.21 } ] } ``` ### Body Params | Campo | Tipo | Descrição | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `collection_slip_payments` * | array | Lista de pagamentos de fatura de recolhimento. Limite de **1000** itens por requisição. | Cada elemento de `collection_slip_payments` deve conter: | Campo | Tipo | Descrição | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente para aquele item do lote. | | `barcode` | string | Código de barras. | | `digitable_line` | string | Linha digitável. | | `payment_amount` * | number | Valor a ser pago. | :::danger Aviso Para cada item, o `payment_amount` enviado deve ser compatível com o que a consulta interna da fatura de recolhimento determinar (por exemplo, alinhado ao `total_amount` e às regras do convênio/tributo), nas mesmas condições do fluxo de pagamento unitário de fatura de recolhimento. ::: ## Response ### Success Response STATUS 202 Response Body: Lote aceito para processamento ```json { "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72", "total_amount": 2778.42, "batch_status": "pending", "payment_type": "collection_slip" } ``` Response Body: exemplo ilustrativo com `batch_status` aprovado ```json { "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72", "total_amount": 2778.42, "batch_status": "approved", "payment_type": "collection_slip" } ``` :::info Processamento do lote O campo `batch_status` na resposta indica o **estado imediato** do lote após esta solicitação (por exemplo, pendente de processamento ou já encaminhado ao processamento dos títulos), conforme o fluxo aplicável. Os valores possíveis de `batch_status` estão em [batch_payment_status](#enumeradores-batch_payment_status). ::: ### Response Body Params | Campo | Tipo | Descrição | |---------------------|---------|-----------------------------------| | `batch_payment_key` * | uuid4 | Chave única de identificação do pagamento em lote. | | `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). | | `account_key` * | uuid4 | Chave da conta debitada. | | `total_amount` * | number | Soma dos valores (`payment_amount`) dos itens do lote. | | `batch_status` * | [enum](#enumeradores-batch_payment_status) | Status do lote logo após a solicitação; depende do processamento imediato e das regras da operação. | | `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. | ### Enumeradores batch_payment_status | Enumerador | Descrição | |---------------|---------------| | `pending` | Pendente de processamento | | `pending_2fa_approval` | Pendente de aprovação 2FA | | `rejected` | Rejeitado | | `approved` | Aprovado | | `processed` | Processado | ### Enumeradores payment_type | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | :::danger Aviso O enumerador `bank_slip` não se aplica ao fluxo de lote de faturas de recolhimento deste endpoint; para este caso, espera-se `payment_type` com valor `collection_slip`. ::: ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. | | 400 | BIP000050 | Bad Request | Requester configuration does not exist. | Configuração do requester não existe. | | 400 | BIP000082 | Bad Request | A list of collection slip payments must be provided. | Uma lista de faturas de recolhimento deve ser fornecida. | --- # Webhooks URL: /documentation/baas/cobranca/webhooks :::danger Atenção! Os webhooks da QI Tech não devem ser mapeadas de forma restrita. Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs. ::: :::info Reenvio de Webhooks Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes). ::: ## Webhook de pagamentos ### Webhook Request Body Request Body: Pagamento executado ```json { "webhook_type": "baas.bill_payment.payment", "webhook_datetime": "2021-10-22T20:30:23.459Z", "data": { "source_account_key": "ca2c934e-5970-4c15-bdef-87e1b5c204e3", "payment_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "payment_schedule_key": null, "transaction_key": "5f67e4fc-d3bd-4831-a9b1-20859dcee7a9", "barcode":"00193967000009910000000003615574000000002417", "digitable_line":"00190000090361557400500000024174396700000991000", "payment_status": "executed", "payment_type":"bank_slip", "error_code": null, "error_message": null } } ``` Request Body: Pagamento pendente de execução ```json { "webhook_type": "baas.bill_payment.payment", "webhook_datetime": "2021-10-22T20:30:23.459Z", "data": { "source_account_key": "ca2c934e-5970-4c15-bdef-87e1b5c204e3", "payment_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "payment_schedule_key": null, "transaction_key": "5f67e4fc-d3bd-4831-a9b1-20859dcee7a9", "barcode":"00193967000009910000000003615574000000002417", "digitable_line":"00190000090361557400500000024174396700000991000", "payment_status": "pending_execution", "payment_type":"bank_slip", "error_code": null, "error_message": null } } ``` Request Body: Pagamento rejeitado ```json { "webhook_type": "baas.bill_payment.payment", "webhook_datetime": "2021-10-22T20:30:23.459Z", "data": { "source_account_key": "ca2c934e-5970-4c15-bdef-87e1b5c204e3", "payment_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "payment_schedule_key": null, "transaction_key": null, "barcode":"00193967000009910000000003615574000000002417", "digitable_line":"00190000090361557400500000024174396700000991000", "payment_status": "rejected", "payment_type":"bank_slip", "error_code": "BIP000023", "error_message": "The source account has insufficient balance. Payment cannot be made." } } ``` Request Body: Pagamento revertido ```json { "webhook_type": "baas.bill_payment.payment", "webhook_datetime": "2021-10-22T20:30:23.459Z", "data": { "source_account_key": "ca2c934e-5970-4c15-bdef-87e1b5c204e3", "payment_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "payment_schedule_key": null, "transaction_key": "5f67e4fc-d3bd-4831-a9b1-20859dcee7a9", "barcode":"81620000000000336592028110120200020214942099", "digitable_line":"816200000007000336592027811012020004202149420996", "payment_status": "reverted", "payment_type":"collection_slip", "error_code": "BIP000029", "error_message": "Bank slip payment write off rejected." } } ``` ### Webhook Body Params | Campo | Tipo | Descrição | |-----------------------|--------|-----------------------------------------------------------| | `webhook_type` | string | Um enumerador que define o tipo de evento sendo reportado | | `webhook_datetime` | string | Data e hora do envio do webhook | | `request_control_key` | uuid4 | Chave única de identificação da request do cliente. | | `source_account_key` * | uuid4 | Chave da conta debitada. | | `payment_key` | uuid4 | Chave única de identificação do pagamento. | | `payment_schedule_key` | uuid4 | Chave única de identificação do agendamento (somente para pagamentos gerados a partir de um agendamento). | | `barcode` | string | Código de barras. | | `digitable_line` | string | Linha digitável. | | `payment_type` | [enum](#enumeradores-payment_type) | Tipo do pagamento. | | `payment_status` | [enum](#enumeradores-payment_status) | Status do pagamento. | | `error_code` | string | Código de erro. | | `error_message` | string | Mensagem de erro. | ### Enumeradores payment_type | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | ### Enumeradores payment_status | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `executed` | string | Executado | | `rejected` | string | rejeitado | | `reverted` | string | Revertido | | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. | | 400 | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. | | 400 | BIP000023 | Bad Request | The source account has insufficient balance. Payment cannot be made. | A conta de origem possui saldo insuficiente. Pagamento não pode ser realizado. | | 400 | BIP000025 | Bad Request | It was not possible to pay the bank slip at this time. Please verify your information and, if necessary, contact us for assistance. | Não foi possível pagar o boleto neste momento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para assistência. | | 400 | BIP000029 | Bad Request | Bank slip payment write off rejected. | Baixa de pagamento de boleto rejeitada. | | 400 | BIP000034 | Bad Request | Collection slip already paid. | Fatura de recolhimento já paga. | | 400 | BIP000036 | Bad Request | Covenant slip overdue. | Fatura de recolhimento vencida. | | 400 | BIP000038 | Bad Request | Outside of covenant payment hours. | Fora do horário de pagamento do convênio. | | 400 | BIP000044 | Bad Request | It was not possible to pay the collection slip at this time. Please verify your ## Webhook de agendamento de pagamento :::info Fluxo de Webhooks para Agendamentos de Pagamentos O processo de agendamento e execução de pagamentos envolve a utilização de diferentes webhooks, cada um desempenhando um papel específico na notificação e no acompanhamento do status do pagamento. Quando o agendamento é executado na data solicitada, ele pode seguir para o status `executed` e será disparado um webhook de `payment_schedule` com o status `executed`, a execução do agendamento resulta na criação de um `payment` com o status `pending` e será enviado o webhook do mesmo. Alternativamente, o agendamento pode seguir para o status `rejected`, sem que o `payment` seja criado, em situações como o fechamento da conta ou alteração do valor do boleto, por exemplo. Nesse caso somente o webhook de `payment_schedule` com o status `rejected` é enviado, acompanhado dos devidos códigos de erro. - Inicialmente, o status do pagamento será `pending`, pois o processo de pagamento está em andamento. Quando o pagamento é concluído, um novo webhook de `payment` é enviado, agora com o status `executed`. - Se o pagamento não puder ser concluído, por exemplo, devido à falta de saldo na conta, um webhook de `payment` com o status `rejected` será enviado, acompanhado dos devidos códigos de erro. - Em casos de insuficiência de saldo na conta, o sistema realizará até 3 tentativas de pagamento, com um intervalo de 30 minutos entre cada uma. Nessa situação, poderão ser gerados múltiplos registros de pagamento para um mesmo agendamento executado. Por exemplo, se o saldo suficiente estiver disponível apenas na terceira tentativa, serão disparados os webhooks dos dois primeiros pagamentos com os status `payment` e `rejected`, seguidos pelos webhooks do terceiro pagamento com os status `payment` e `executed`. ::: ### Webhook Request Body Request Body: Agendamento de pagamento executado ```json { "webhook_type": "baas.bill_payment.payment_schedule", "webhook_datetime": "2021-10-22T20:30:23.459Z", "data": { "source_account_key": "ca2c934e-5970-4c15-bdef-87e1b5c204e3", "payment_schedule_key": "a72947e5-e676-4710-8f66-7d345f1c4064", "payment_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "barcode":"00193967000009910000000003615574000000002417", "digitable_line":"00190000090361557400500000024174396700000991000", "payment_type":"bank_slip", "payment_schedule_status": "executed", "error_code": null, "error_message": null } } ``` Request Body: Agendamento de pagamento rejeitado ```json { "webhook_type": "baas.bill_payment.payment_schedule", "webhook_datetime": "2021-10-22T20:30:23.459Z", "data": { "source_account_key": "ca2c934e-5970-4c15-bdef-87e1b5c204e3", "payment_schedule_key": "a72947e5-e676-4710-8f66-7d345f1c4064", "payment_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "barcode":"00193967000009910000000003615574000000002417", "digitable_line":"00190000090361557400500000024174396700000991000", "payment_type":"bank_slip", "payment_schedule_status": "rejected", "error_code": "BIP000007", "error_message": "Bank slip blocked for payment" } } ``` ### Webhook Body Params | Campo | Tipo | Descrição | |-----------------------|--------|-----------------------------------------------------------| | `webhook_type` | string | Um enumerador que define o tipo de evento sendo reportado | | `webhook_datetime` | string | Data e hora do envio do webhook | | `request_control_key` | uuid4 | Chave única de identificação da request do cliente. | | `source_account_key` * | uuid4 | Chave da conta debitada. | | `payment_key` | uuid4 | Chave única de identificação do pagamento. | | `payment_schedule_key` | uuid4 | Chave única de identificação do agendamento pagamento. | | `barcode` | string | Código de barras. | | `digitable_line` | string | Linha digitável. | | `payment_type` | [enum](#enumeradores-payment_type) | Tipo do agendamento de pagamento. | | `payment_schedule_status` | [enum](#enumeradores-payment_schedule_status) | Status do agendamento de pagamento. | | `error_code` | string | Código de erro. | | `error_message` | string | Mensagem de erro. | ### Enumeradores payment_type | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | ### Enumeradores payment_schedule_status | Enumerador | Tipo | Descrição | |---------------|-----------|---------------| | `executed` | string | Executado | | `rejected` | string | Rejeitado | | Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) | |-------------|-----------|--------|------------------|------------------| | 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. | | 400 | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. | | 400 | BIP000006 | Bad Request | Bank slip already written off | Boleto já baixado | | 400 | BIP000007 | Bad Request | Bank slip blocked for payment | Boleto bloqueado para pagamento | | 400 | BIP000008 | Bad Request | Bank slip already paid | Boleto já pago | | 400 | BIP000009 | Bad Request | Invalid bank slip. Please consult issuing bank | Boleto inválido. Favor consultar banco emissor | | 400 | BIP000034 | Bad Request | Collection slip already paid. | Fatura de recolhimento já paga. |