# QI Tech — Banking-as-a-Service › Boleto Payments Documentação da QI Tech em texto corrido, para colar em um LLM. Fonte: https://docs.qitech.com.br 54 página(s). Índice: - Cancel payment scheduling batch (/en/documentation/baas/cobranca/2fa_v2/agendamento/cancelar_agendamento_em_lote_de_pagamento) - Confirmar Agendamento de Boleto Bancário (/en/documentation/baas/cobranca/2fa_v2/agendamento/confirmar_agendamento_de_boleto_bancario) - Confirmação de Pagamento de Fatura de Recolhimento (/en/documentation/baas/cobranca/2fa_v2/agendamento/confirmar_agendamento_de_fatura_de_recolhimento) - Confirm bank slip batch scheduling (/en/documentation/baas/cobranca/2fa_v2/agendamento/confirmar_agendamento_em_lote_de_boleto_bancario) - Confirm collection slip batch scheduling (/en/documentation/baas/cobranca/2fa_v2/agendamento/confirmar_agendamento_em_lote_de_fatura_de_recolhimento) - Get payment scheduling batch (/en/documentation/baas/cobranca/2fa_v2/agendamento/consultar_lote_de_agendamento_de_pagamento) - List payment scheduling batches (/en/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 (/en/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 (/en/documentation/baas/cobranca/2fa_v2/agendamento/reenviar_token_de_agendamento_de_fatura_de_recolhimento) - Resend token for bank slip batch scheduling (/en/documentation/baas/cobranca/2fa_v2/agendamento/reenviar_token_de_agendamento_em_lote_de_boleto_bancario) - Resend token for collection slip batch scheduling (/en/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) (/en/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) (/en/documentation/baas/cobranca/2fa_v2/agendamento/solicitar_agendamento_de_pagamento_de_fatura_de_recolhimento) - Request bank slip batch scheduling with 2FA (/en/documentation/baas/cobranca/2fa_v2/agendamento/solicitar_agendamento_em_lote_de_boleto_bancario) - Request collection slip batch scheduling with 2FA (/en/documentation/baas/cobranca/2fa_v2/agendamento/solicitar_agendamento_em_lote_de_fatura_de_recolhimento) - Bank slip payment batch confirmation (/en/documentation/baas/cobranca/2fa_v2/confirmacao_de_lote_de_boleto_bancario) - Collection slip (utility/tax) payment batch confirmation (/en/documentation/baas/cobranca/2fa_v2/confirmacao_de_lote_de_fatura_de_recolhimento) - Confirm boleto payment (/en/documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_boleto_bancario) - Confirm payment of collection invoice (agreement/tribute) (/en/documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_fatura_de_recolhimento) - Introduction to Two-Factor Authentication (/en/documentation/baas/cobranca/2fa_v2/introducao_ao_pagamento_2fa) - Request boleto payment (2FA) (/en/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_boleto_bancario) - Request payment of collection invoice (agreement/tribute) (/en/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_fatura_de_recolhimento) - Resend payment confirmation token for Boleto (/en/documentation/baas/cobranca/2fa_v2/solicitacao_de_reenvio_de_token_de_boleto_bancario) - Resend Two-Factor Authentication Token for Collection Invoice Payments (/en/documentation/baas/cobranca/2fa_v2/solicitacao_de_reenvio_de_token_de_fatura_de_recolhimento) - Resend token for bank slip payment batch confirmation (/en/documentation/baas/cobranca/2fa_v2/solicitacao_de_reenvio_de_token_de_lote_de_boleto_bancario) - Resend token for collection slip payment batch confirmation (utility/tax) (/en/documentation/baas/cobranca/2fa_v2/solicitacao_de_reenvio_de_token_de_lote_de_fatura_de_recolhimento) - Request bank slip batch payment with two-factor authentication (/en/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 (/en/documentation/baas/cobranca/2fa_v2/solicitar_pagamento_lote_de_boleto_bancario_sem_confirmacao_de_lote) - Request collection slip (utility/tax) batch payment with two-factor authentication (/en/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 (/en/documentation/baas/cobranca/2fa_v2/solicitar_pagamento_lote_de_fatura_de_recolhimento_sem_confirmacao_de_lote) - Token validation for bank slip payment batch (/en/documentation/baas/cobranca/2fa_v2/validacao_de_token_de_lote_de_boleto_bancario) - Token validation for collection slip payment batch (utility/tax) (/en/documentation/baas/cobranca/2fa_v2/validacao_de_token_de_lote_de_fatura_de_recolhimento) - Schedule Boleto payment (/en/documentation/baas/cobranca/agendamento/agendar_pagamento_de_boleto_bancario) - Schedule payment of collection invoice (agreement/tribute) (/en/documentation/baas/cobranca/agendamento/agendar_pagamento_de_fatura_de_recolhimento) - Cancel schedule (/en/documentation/baas/cobranca/agendamento/cancelar_agendamento) - Check scheduling (/en/documentation/baas/cobranca/agendamento/consultar_agendamento) - List schedules (/en/documentation/baas/cobranca/agendamento/listar_agendamentos) - Request batch scheduling of bank slip payments (/en/documentation/baas/cobranca/agendamento/solicitar_agendamento_em_lote_de_boleto_bancario) - Request batch scheduling of collection slip payments (/en/documentation/baas/cobranca/agendamento/solicitar_agendamento_em_lote_de_fatura_de_recolhimento) - Confirmação de lote de pagamento de boleto bancário (/en/documentation/baas/cobranca/confirmacao_de_lote_de_boleto_bancario) - Confirmação de lote de pagamento de fatura de recolhimento (convênio/tributo) (/en/documentation/baas/cobranca/confirmacao_de_lote_de_fatura_de_recolhimento) - Consult boleto (/en/documentation/baas/cobranca/consultar_boleto_bancario) - Consult collection invoice (agreement/tribute) (/en/documentation/baas/cobranca/consultar_fatura_de_recolhimento) - Consultar lote de pagamento (/en/documentation/baas/cobranca/consultar_lote_de_pagamento) - Listar lotes de pagamento (/en/documentation/baas/cobranca/listar_lotes_de_pagamento) - List payments (/en/documentation/baas/cobranca/listar_pagamentos) - Make payment of Boleto (/en/documentation/baas/cobranca/pagar_boleto_bancario) - Make payment of collection invoice (agreement/tribute) (/en/documentation/baas/cobranca/pagar_fatura_de_recolhimento) - Scenario Simulation (/en/documentation/baas/cobranca/simulacao_de_cenarios) - Solicitar Pagamento em Lote de Boleto Bancário (/en/documentation/baas/cobranca/solicitar_pagamento_lote_de_boleto_bancario_com_confirmacao_de_lote) - Solicitar Pagamento em Lote de Boleto Bancário (/en/documentation/baas/cobranca/solicitar_pagamento_lote_de_boleto_bancario_sem_confirmacao_de_lote) - Solicitar Pagamento em Lote de Fatura de Recolhimento (convênio/tributo) (/en/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) (/en/documentation/baas/cobranca/solicitar_pagamento_lote_de_fatura_de_recolhimento_sem_confirmacao_de_lote) - Webhooks (/en/documentation/baas/cobranca/webhooks) --- # Cancel payment scheduling batch URL: /en/documentation/baas/cobranca/2fa_v2/agendamento/cancelar_agendamento_em_lote_de_pagamento This endpoint allows cancelar um batch de scheduling de payments enquanto o batch estiver em status cancelável. :::info Boleto bancário É o bank slip 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 payment autorizadas a funcionar pelo Banco Central. ::: :::info Fatura de recolhimento Esse tipo de cobrança é emitido por concessionárias de serviços (account 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 METHOD PATCH ### Request Path Params | Field | Type | Description | Characters | |-----------------------|-------|--------------------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da account. | 36 | | `batch_payment_key` * | uuid4 | Chave única de identificação do batch de scheduling. | 36 | ## Response ### Success Response STATUS 200 Response Body: Batch de scheduling 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 | Field | Type | Description | |--------------------------------|--------|-----------| | `batch_payment_schedule_key` * | uuid4 | Chave única de identificação do batch de scheduling. | | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente (batch). | | `account_key` * | uuid4 | Chave da account debitada. | | `total_amount` * | number | Soma dos valores dos itens do batch. | | `batch_payment_schedule_status` * | [enum](#enumeradores-batch_payment_schedule_status) | Status do batch após a solicitação de cancelamento. | | `payment_type` * | [enum](#enumeradores-payment_type) | Type do payment. | ### Enumerators batch_payment_schedule_status | Enumerator | Description | |------------------------|---------------------------| | `pending_2fa_approval` | Pendente de aprovação 2FA | | `scheduled` | Scheduled | | `rejected` | Rejected | | `canceled` | Canceled | | `error` | Scheduling error | ### Enumerators payment_type | Enumerator | Description | |-------------------|------------------------| | `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": "Description em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Description (eng) | Description (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 account de origem não foi encontrada. | | 404 | BIP000083 | Not Found | Batch payment not found by batch payment key.| Batch de payments não encontrado pela chave do batch. | | 400 | BIP000085 | Bad Request | Batch payment status is not pending approval.| Status do batch de payments não é de aprovação pendente. | --- # Confirmar Agendamento de Boleto Bancário URL: /en/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: /en/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. | --- # Confirm bank slip batch scheduling URL: /en/documentation/baas/cobranca/2fa_v2/agendamento/confirmar_agendamento_em_lote_de_boleto_bancario This endpoint allows validating the two-factor authentication (2FA) token for a bank slip scheduling batch in `batch_payment_schedule_status` **`pending_2fa_approval`**. :::info Bank slip A traditional bank slip (digitable line does not start with 8). It is registered in the Interbank Payment Chamber (CIP/Nuclea) and can be paid through financial and payment institutions authorized by the Central Bank. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payment/schedule_bank_slip/ BATCH_PAYMENT_SCHEDULE_KEY /validate_token METHOD PATCH ### Request Path Params | Field | Type | Description | Characters | | --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- | | `account_key` * | uuid4 | Unique account identifier key. | 36 | | `batch_payment_schedule_key` * | uuid4 | Unique batch scheduling identifier key. | 36 | Request Body: Batch scheduling token validation ```json { "token": "329adf" } ``` ### Body Params | Field | Type | Description | Characters | | ------- | ------ | ---------------------------------------------------------------------------------------------------------------- | ---------- | | `token` | string | Authentication code sent to the account transaction approver | 6 | ## Response ### Success Response STATUS 200 Response Body: Confirmed scheduling batch ```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 | Field | Type | Description | | ----------------------- | ------ | --------- | | `batch_payment_schedule_key` * | uuid4 | Unique batch scheduling identifier key. | | `request_control_key` * | uuid4 | Unique client request identifier key (batch). | | `account_key` * | uuid4 | Debited account key. | | `total_amount` * | number | Sum of item amounts in the batch. | | `batch_payment_schedule_status` * | [enum](#enumeradores-batch_payment_schedule_status) | Batch scheduling status after token validation. | | `payment_type` * | string | Payment type; for this flow, expected value is `bank_slip`. | ### Enumerators batch_payment_schedule_status | Enumerator | Description | |---------------|---------------| | `pending_2fa_approval` | Pending 2FA approval | | `scheduled` | Scheduled | | `rejected` | Rejected | | `error` | Scheduling error | ### Error Response STATUS 4XX Response Body ```json { "title": "Title", "description": "Description in English", "translation": "Description in Portuguese", "code": "Code" } ``` | HTTP Code | QI Code | Title | Description (eng) | Description (pt-br) | | ----------- | --------- | ----------- | --------------------------------------------- | ---------------------------------------------------------------- | | 403 | BIP000010 | Forbidden | User is not allowed to do this action | User is not allowed to do this action | | 404 | BIP000011 | Not Found | The source account key was not found. | The source account key was not found. | | 400 | BIP000058 | Bad Request | Error while validating verification token | Error while validating verification token | | 400 | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Number of verification token validation attempts exceeded. | | 400 | BIP000060 | Bad Request | Verification token expired. | Verification token expired. | | 400 | BIP000061 | Bad Request | Verification token validation failed. | Verification token validation failed. | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Payment verification time window exceeded. | | 404 | BIP000083 | Not Found | Batch payment not found by batch payment key. | Batch payment not found by batch payment key. | | 400 | BIP000085 | Bad Request | Batch payment status is not pending approval. | Batch payment status is not pending approval. | | 400 | BIP000086 | Bad Request | A token is required for SMS or email validation. | A token is required for SMS or email validation. | --- # Confirm collection slip batch scheduling URL: /en/documentation/baas/cobranca/2fa_v2/agendamento/confirmar_agendamento_em_lote_de_fatura_de_recolhimento This endpoint allows validar o token de autenticação de dois fatores (2FA) de um batch de scheduling de collection slips em `batch_payment_schedule_status` **`pending_2fa_approval`**. :::info Fatura de recolhimento Esse tipo de cobrança é emitido por concessionárias de serviços (account 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 METHOD PATCH ### Request Path Params | Field | Type | Description | Characters | | --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- | | `account_key` * | uuid4 | Chave única de identificação da account. | 36 | | `batch_payment_schedule_key` * | uuid4 | Chave única de identificação do batch de scheduling. | 36 | Request Body: Validação de token do batch de scheduling ```json { "token": "329adf" } ``` ### Body Params | Field | Type | Description | Characters | | ------- | ------ | ---------------------------------------------------------------------------------------------------------------- | ---------- | | `token` | string | Código de autenticação enviado ao aprovador de movimentações da account | 6 | ## Response ### Success Response STATUS 200 Response Body: Batch de scheduling 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 | Field | Type | Description | | ----------------------- | ------ | --------- | | `batch_payment_schedule_key` * | uuid4 | Chave única de identificação do scheduling em batch. | | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente (batch). | | `account_key` * | uuid4 | Chave da account debitada. | | `total_amount` * | number | Soma dos valores dos itens do batch. | | `batch_payment_schedule_status` * | [enum](#enumeradores-batch_payment_schedule_status) | Status do batch de scheduling após a validação do token. | | `payment_type` * | string | Type do payment; para este fluxo, espera-se `collection_slip`. | ### Enumerators batch_payment_schedule_status | Enumerator | Description | |---------------|---------------| | `pending_2fa_approval` | Pendente de aprovação 2FA | | `scheduled` | Scheduled | | `rejected` | Rejected | | `error` | Scheduling error | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Description em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Description (eng) | Description (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 account 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 payment excedida. | | 404 | BIP000083 | Not Found | Batch payment not found by batch payment key. | Batch de payments não encontrado pela chave do batch. | | 400 | BIP000085 | Bad Request | Batch payment status is not pending approval. | Status do batch de payments 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. | --- # Get payment scheduling batch URL: /en/documentation/baas/cobranca/2fa_v2/agendamento/consultar_lote_de_agendamento_de_pagamento This endpoint returns o resumo do batch de scheduling e a lista paginada dos schedulings que o compõem (bank slips ou collection slips). Para localizar `batch_payment_schedule_key`, utilize [List batchs de scheduling de payment](./listar_batchs_de_scheduling_de_payment.md). :::info Boleto bancário É o bank slip 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 payment autorizadas a funcionar pelo Banco Central. ::: :::info Fatura de recolhimento Esse tipo de cobrança é emitido por concessionárias de serviços (account 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 METHOD GET ### Request Path Params | Field | Type | Description | Characters | |-----------------------------|-------|----------------------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da account. | 36 | | `batch_payment_schedule_key` * | uuid4 | Chave única de identificação do batch de scheduling. | 36 | ### Request Query String Params | Field | Type | Description | |-------------|--------|-------------------------------------------------------------------------------| | `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 batch de scheduling ```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 }, "date": [ { "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 | Field | Type | Description | |--------------------------------|------------------------------------------|---------------------------------------------------------------| | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente (batch). | | `total_scheduled` * | int | Quantidade de itens do batch agendados com sucesso. | | `total_pending` * | int | Quantidade de itens ainda pendentes no batch. | | `total_error` * | int | Quantidade de itens com erro no batch. | | `total_amount` * | number | Valor total do batch. | | `batch_payment_schedule_status` * | [enum](#enumeradores-batch_payment_schedule_status) | Status do batch de scheduling. | | `payment_schedules` * | [object](#objeto-payment_schedules) | Lista paginada dos schedulings do batch. | ### Object payment_schedules | Field | Type | Description | |----------------|------------------------------|----------------------------------------------------------| | `pagination` * | [object](#objeto-pagination) | Paginação da lista de schedulings do batch. | | `date` * | array | Itens do batch (schedulings individuais). | Cada elemento de `payment_schedules.data` contém: | Field | Type | Description | |--------------------------|--------------------------------------|--------------------------------------------------------------------------------| | `payment_schedule_key` * | uuid4 | Chave única de identificação do scheduling. | | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente para o item do batch. | | `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 account debitada. | | `paid_amount` * | number | Valor agendado para payment. | | `payment_date` * | string | Data do scheduling. | | `payment_type` * | [enum](#enumeradores-payment_type) | Type do payment. | | `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 scheduling. | | `error_reason` | string | Motivo do erro, quando aplicável; caso contrário `null`. | ### Object pagination | Field | Type | Description | |------------------|------|-------------------------------------| | `current_page` * | int | Página atual retornada. | | `rows_per_page` *| int | Quantidade de registros por página. | ### Enumerators payment_type | Enumerator | Description | |-------------------|------------------------| | `bank_slip` | Boleto bancário | | `collection_slip` | Fatura de recolhimento | ### Enumerators payment_schedule_status | Enumerator | Description | |------------------------|------------------------------------------------------------------| | `pending_2fa_approval` | Scheduling pendente de autenticação de dois fatores (2FA) | | `scheduled` | Pagamento agendado com sucesso | | `executed` | O scheduling foi executado com sucesso e o payment foi gerado | | `rejected` | O scheduling foi rejeitado e nenhum payment foi gerado | | `canceled` | Scheduling cancelado | | `error` | Erro ao realizar o scheduling | ### Enumerators batch_payment_schedule_status | Enumerator | Description | |------------------------|---------------------------| | `pending_2fa_approval` | Pendente de aprovação 2FA | | `scheduled` | Scheduled | | `rejected` | Rejected | | `canceled` | Canceled | | `error` | Scheduling error | ### Object bank_slip | Field | Type | Description | |--------------------------------|-------------------------------------------------|-----------------------------------------------------| | `bank_slip_key` * | uuid4 | Chave única de identificação do bank slip. | | `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 payment. | | `partial_payment_indicator` * | [enum](#enumeradores-partial_payment_indicator) | Indicador de payment parcial. | | `registered_payment_amount` | number | Valor total de payment 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. | ### Enumerators partial_payment_indicator | Enumerator | Description | |---------------|---------------| | `allowed` | Permitido | | `not_allowed` | Não permitido | ### Object collection_slip | Field | Type | Description | |--------------------------------|--------|---------------------------------------------| | `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": "Description em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Description (eng) | Description (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. | Batch de payments não encontrado pela chave do batch. | --- # List payment scheduling batches URL: /en/documentation/baas/cobranca/2fa_v2/agendamento/listar_lotes_de_agendamento_de_pagamento This endpoint returns os batchs de scheduling de payments de bank slips e collection slips associados à account, com suporte a filtros e paginação. :::info Boleto bancário É o bank slip 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 payment autorizadas a funcionar pelo Banco Central. ::: :::info Fatura de recolhimento Esse tipo de cobrança é emitido por concessionárias de serviços (account 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 METHOD GET ### Request Path Params | Field | Type | Description | Characters | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da account. | 36 | ### Request Query String Params | Field | Type | Description | |--------------------------------|-------------|-----------------------------------| | `request_control_key` | uuid4 | Chave única de identificação da request do cliente (batch). | | `batch_payment_schedule_key` | uuid4 | Chave única de identificação do batch de scheduling. | | `payment_type` | [enum](#enumeradores-payment_type) | Type do payment do batch. | | `batch_payment_schedule_status`| [enum](#enumeradores-batch_payment_schedule_status) | Status do batch de scheduling. | | `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. | ### Enumerators payment_type | Enumerator | Type | Description | |-------------------|--------|------------------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | ### Enumerators batch_payment_schedule_status | Enumerator | Description | |------------------------|------------------------------------| | `pending_2fa_approval` | Pendente de aprovação 2FA | | `scheduled` | Scheduled | | `rejected` | Rejected | | `canceled` | Canceled | | `error` | Scheduling error | ## Response ### Success Response STATUS 200 Response Body: Listagem de batchs de scheduling ```json { "pagination": { "current_page": 1, "rows_per_page": 30 }, "date": [ { "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 | Field | Type | Description | |---------------------|---------|-----------------------------------| | `pagination` * | [object](#objeto-pagination) | Informações de paginação da consulta. | | `date` * | array | Lista de batchs encontrados. | Cada elemento de `date` contém: | Field | Type | Description | |---------------------------------|---------|-----------------------------------| | `batch_payment_schedule_key` * | uuid4 | Chave única de identificação do batch de scheduling. | | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente (batch). | | `batch_payment_schedule_status` * | [enum](#enumeradores-batch_payment_schedule_status-1) | Status atual do batch de scheduling. | | `payment_type` * | [enum](#enumeradores-payment_type-1) | Type do payment do batch. | | `total_scheduled` * | int | Quantidade de itens do batch agendados com sucesso. | | `total_pending` * | int | Quantidade de itens ainda pendentes no batch. | | `total_error` * | int | Quantidade de itens com erro no batch. | | `total_amount` * | number | Valor total do batch. | ### Object pagination | Field | Type | Description | |---------------------|---------|-----------------------------------| | `current_page` * | int | Página atual retornada. | | `rows_per_page` * | int | Quantidade de registros por página. | ### Enumerators payment_type | Enumerator | Description | |-------------------|------------------------| | `bank_slip` | Boleto bancário | | `collection_slip` | Fatura de recolhimento | ### Enumerators batch_payment_schedule_status | Enumerator | Description | |------------------------|---------------------------| | `pending_2fa_approval` | Pendente de aprovação 2FA | | `scheduled` | Scheduled | | `rejected` | Rejected | | `canceled` | Canceled | | `error` | Scheduling error | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Description em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Description (eng) | Description (pt-br) | |-------------|-----------|--------|------------------|------------------| | 400 | BIP000026 | Bad Request | Invalid payment date format. The correct format is YYYY-MM-DD. | Formato de date de payment 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. | Type de payment inválido. | --- # Reenviar Token Autenticação de Dois Fatores de Agendamento de Boleto Bancário URL: /en/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 | ## 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", "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](#object-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 | ### Object 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: /en/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. | --- # Resend token for bank slip batch scheduling URL: /en/documentation/baas/cobranca/2fa_v2/agendamento/reenviar_token_de_agendamento_em_lote_de_boleto_bancario This endpoint allows resending the two-factor authentication (2FA) token for a bank slip scheduling batch currently in `batch_payment_schedule_status` **`pending_2fa_approval`**. :::info Bank slip A traditional bank slip (digitable line does not start with 8). It is registered in the Interbank Payment Chamber (CIP/Nuclea) and can be paid through financial and payment institutions authorized by the Central Bank. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payment/schedule_bank_slip/ BATCH_PAYMENT_SCHEDULE_KEY /resend_token METHOD PATCH ### Request Path Params | Field | Type | Description | Characters | | --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- | | `account_key` * | uuid4 | Unique account identifier key. | 36 | | `batch_payment_schedule_key` * | uuid4 | Unique batch scheduling identifier key. | 36 | ### Request Body Request Body (optional) ```json { "contact_type": "sms" } ``` ### Body Params | Field | Type | Description | Characters | | -------------- | ---------- | --------------------------------------- | ------------------------------------------------------- | | `contact_type` | enumerator | Authentication token delivery channel | **[Enumerator contact_type](#enumerador-contact_type)** | :::info Information If `contact_type` is not sent, the token will be delivered using the channel originally requested in the batch scheduling (`tfa_info.contact_type`). ::: ### Enumerator contact_type | Enumerator | Description | | ---------- | ------------------------------------------------- | | **sms** | Send token via SMS | | **email** | Send token via email | ## Response ### Success Response STATUS 200 Response Body: Token resent successfully ```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 | Field | Type | Description | | ----------------------- | ------ | --------- | | `batch_payment_schedule_key` * | uuid4 | Unique batch scheduling identifier key. | | `request_control_key` * | uuid4 | Unique client request identifier key (batch). | | `account_key` * | uuid4 | Debited account key. | | `total_amount` * | number | Sum of item amounts in the batch. | | `batch_payment_schedule_status` * | string | After resend, the batch remains waiting for token validation (`pending_2fa_approval`). | | `payment_type` * | string | Payment type; for this flow, expected value is `bank_slip`. | Then use [Confirm bank slip batch scheduling](./confirmar_agendamento_em_lote_de_boleto_bancario.md) to complete 2FA. ### Error Response STATUS 4XX Response Body ```json { "title": "Title", "description": "Description in English", "translation": "Description in Portuguese", "code": "Code" } ``` | HTTP Code | QI Code | Title | Description (eng) | Description (pt-br) | | ----------- | --------- | ----------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | 403 | BIP000010 | Forbidden | User is not allowed to do this action | User is not allowed to do this action | | 404 | BIP000011 | Not Found | The source account key was not found. | The source account key was not found. | | 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | It was not possible to consult the source account at this time. Please try again in a few minutes. | | 400 | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Number of verification token validation attempts exceeded. | | 400 | BIP000064 | Bad Request | Error resending verification token | Error resending verification token | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Payment verification time window exceeded. | | 404 | BIP000083 | Not Found | Batch payment not found by batch payment key. | Batch payment not found by batch payment key. | | 400 | BIP000085 | Bad Request | Batch payment status is not pending approval. | Batch payment status is not pending approval. | --- # Resend token for collection slip batch scheduling URL: /en/documentation/baas/cobranca/2fa_v2/agendamento/reenviar_token_de_agendamento_em_lote_de_fatura_de_recolhimento This endpoint allows **reenviar** o token de autenticação de dois fatores (2FA) para um batch de scheduling de collection slips 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 (account 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 METHOD PATCH ### Request Path Params | Field | Type | Description | Characters | | --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- | | `account_key` * | uuid4 | Chave única de identificação da account. | 36 | | `batch_payment_schedule_key` * | uuid4 | Chave única de identificação do batch de scheduling. | 36 | ### Request Body Request Body (opcional) ```json { "contact_type": "sms" } ``` ### Body Params | Field | Type | Description | Characters | | -------------- | ---------- | --------------------------------------- | ------------------------------------------------------- | | `contact_type` | enumerator | Forma de envio do token de autenticação | **[Enumerator contact_type](#enumerador-contact_type)** | :::info Information Caso não seja enviado um `contact_type`, o token será enviado da forma solicitada originalmente no scheduling do batch (`tfa_info.contact_type`). ::: ### Enumerator contact_type | Enumerator | Description | | ---------- | ------------------------------------------------- | | **sms** | Envio por mensagem de texto para telefone celular | | **email** | Envio por correio eletrônico | ## Response ### Success Response STATUS 200 Response Body: Token resent successfully ```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 | Field | Type | Description | | ----------------------- | ------ | --------- | | `batch_payment_schedule_key` * | uuid4 | Chave única de identificação do scheduling em batch. | | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente (batch). | | `account_key` * | uuid4 | Chave da account debitada. | | `total_amount` * | number | Soma dos valores dos itens do batch. | | `batch_payment_schedule_status` * | string | Após o reenvio, o batch permanece aguardando validação do token (`pending_2fa_approval`). | | `payment_type` * | string | Type do payment; para este fluxo, espera-se `collection_slip`. | In sequence, use [Confirm scheduling em batch de collection slip](./confirmar_scheduling_em_batch_de_fatura_de_recolhimento.md) para concluir o 2FA. ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Description em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Description (eng) | Description (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 account 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 account 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 payment excedida. | | 404 | BIP000083 | Not Found | Batch payment not found by batch payment key. | Batch de payments não encontrado pela chave do batch. | | 400 | BIP000085 | Bad Request | Batch payment status is not pending approval. | Status do batch de payments não é de aprovação pendente. | --- # Solicitar Agendamento de Pagamento de Boleto Bancário com Autenticação de Dois Fatores (2FA) URL: /en/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](#object-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`. ::: ### Object tfa_info | Campo | Tipo | Descrição | |-----------------------------------|---------|-----------------------------------| | `approver_document_number`* | string | Número de documento da pessoa aprovadora da conta. | | `contact_type`* | string | Forma de contato com a pessoa aprovadora da conta, podendo ser **sms** ou **email** | ## Response ### Success Response STATUS 201 Response Body: Agendamento 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", "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 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](#object-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 | ### Object 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: /en/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](#object-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. ::: ### Object tfa_info | Campo | Tipo | Descrição | |-----------------------------------|---------|-----------------------------------| | `approver_document_number`* | string | Número de documento da pessoa aprovadora da conta (CPF/CNPJ). | | `contact_type`* | string | Forma de contato com a pessoa aprovadora da conta, podendo ser **sms** ou **email** | ## 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](#object-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 | ### Object 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 | --- # Request bank slip batch scheduling with 2FA URL: /en/documentation/baas/cobranca/2fa_v2/agendamento/solicitar_agendamento_em_lote_de_boleto_bancario This endpoint allows requesting **batch scheduling** for bank slips in a single request, with two-factor authentication when applicable. :::info Bank slip A traditional bank slip (digitable line does not start with 8). It is registered in the Interbank Payment Chamber (CIP/Nuclea) and can be paid through financial and payment institutions authorized by the Central Bank. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments_schedule/batch_bank_slip METHOD POST ### Request Path Params | Field | Type | Description | Characters | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Unique account identifier key. | 36 | Request Body: Bank slip batch scheduling ```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 | Field | Type | Description | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Unique client request identifier key (batch). | | `bank_slip_payment_schedules` * | array | List of bank slip schedules. Limit of **1000** items per request. | | `tfa_info` * | [object](#objeto-tfa_info) | Object containing the approver document and token delivery channel. | Each element in `bank_slip_payment_schedules` must contain: | Field | Type | Description | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Unique client request identifier key for that batch item. | | `barcode` | string | Barcode. | | `digitable_line` | string | Digitable line. | | `payment_amount` * | number | Amount to be paid. | | `payment_date` * | string | Scheduled execution date for the item. | :::danger Warning For each item, `payment_amount` must follow the bank slip rules returned by the lookup. If partial payment is not allowed, the amount must match the updated total amount. ::: ### Object tfa_info | Field | Type | Description | |-----------------------------|---------|-----------------------------------| | `approver_document_number`* | string | Approver document number (CPF/CNPJ). | | `contact_type`* | enumerator | Authentication token delivery channel | **[Enumerator contact_type](#enumerador-contact_type)** | | Enumerator | Description | |------------|---------------------------------------------------| | **sms** | Send token via SMS | | **email** | Send token via email | ## Response ### Success Response STATUS 202 Response Body: Scheduling batch pending two-factor approval ```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 | Field | Type | Description | |---------------------|---------|-----------------------------------| | `batch_payment_schedule_key` * | uuid4 | Unique batch scheduling identifier key. | | `request_control_key` * | uuid4 | Unique client request identifier key (batch). | | `account_key` * | uuid4 | Debited account key. | | `total_amount` * | number | Sum of (`payment_amount`) values for batch items. | | `batch_payment_schedule_status` * | [enum](#enumeradores-batch_payment_schedule_status) | Batch scheduling status after request. | | `payment_type` * | [enum](#enumeradores-payment_type) | Payment type. | ### Enumerators batch_payment_schedule_status | Enumerator | Description | |---------------|---------------| | `pending_2fa_approval` | Pending 2FA approval | | `scheduled` | Scheduled | | `rejected` | Rejected | | `error` | Scheduling error | ### Enumerators payment_type | Enumerator | Type | Description | |---------------|-----------|---------------| | `bank_slip` | string | Bank slip | | `collection_slip` | string | Collection slip | :::danger Warning The `collection_slip` enumerator does not apply to the bank slip batch scheduling flow for this endpoint; expected `payment_type` value is `bank_slip`. ::: ### Error Response STATUS 4XX Response Body ```json { "title": "Title", "description": "Description in English", "translation": "Description in Portuguese", "code": "Code" } ``` | HTTP Code | QI Code | Title | Description (eng) | Description (pt-br) | |-------------|-----------|--------|------------------|------------------| | 403 | BIP000010 | Forbidden | User is not allowed to do this action | User is not allowed to do this action | | 404 | BIP000011 | Not Found | The source account key was not found. | The source account key was not found. | | 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | It was not possible to consult the source account at this time. Please try again in a few minutes. | | 400 | BIP000024 | Bad Request | Request control key already exists. | Request control key already exists. | | 400 | BIP000052 | Bad Request | Given document number does not belong to an approver for this account | Given document number does not belong to an approver for this account | | 400 | BIP000053 | Bad Request | Error getting approver date | Error getting approver date | | 400 | BIP000054 | Bad Request | TFA info required | TFA info required | | 400 | BIP000055 | Bad Request | Error sending verification token | Error sending verification token | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Payment verification time window exceeded. | --- # Request collection slip batch scheduling with 2FA URL: /en/documentation/baas/cobranca/2fa_v2/agendamento/solicitar_agendamento_em_lote_de_fatura_de_recolhimento This endpoint allows solicitar o **scheduling em batch** de collection slips (convênio/tributo) em uma única request, 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 (account 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 METHOD POST ### Request Path Params | Field | Type | Description | Characters | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Chave única de identificação da account. | 36 | Request Body: Scheduling em batch de collection slips ```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 | Field | Type | Description | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente (batch). | | `collection_slip_payment_schedules` * | array | Lista de schedulings de collection slip. Limite de **1000** itens por request. | | `tfa_info` * | [object](#objeto-tfa_info) | Object contendo o documento da pessoa aprovadora da account e a forma de accountto. | Cada elemento de `collection_slip_payment_schedules` deve conter: | Field | Type | Description | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente para aquele item do batch. | | `barcode` | string | Código de barras. | | `digitable_line` | string | Linha digitável. | | `payment_amount` * | number | Valor a ser pago. | | `payment_date` * | string | Data do scheduling do item. | ### Object tfa_info | Field | Type | Description | |-----------------------------|---------|-----------------------------------| | `approver_document_number`* | string | Número de documento da pessoa aprovadora da account (CPF/CNPJ). | | `contact_type`* | enumerator | Forma de envio do token de autenticação | **[Enumerator contact_type](#enumerador-contact_type)** | | Enumerator | Description | |------------|---------------------------------------------------| | **sms** | Envio por mensagem de texto para telefone celular | | **email** | Envio por correio eletrônico | ## Response ### Success Response STATUS 202 Response Body: Batch de scheduling 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 | Field | Type | Description | |---------------------|---------|-----------------------------------| | `batch_payment_schedule_key` * | uuid4 | Chave única de identificação do scheduling em batch. | | `request_control_key` * | uuid4 | Chave única de identificação da request do cliente (batch). | | `account_key` * | uuid4 | Chave da account debitada. | | `total_amount` * | number | Soma dos valores (`payment_amount`) dos itens do batch. | | `batch_payment_schedule_status` * | [enum](#enumeradores-batch_payment_schedule_status) | Batch scheduling status after request. | | `payment_type` * | [enum](#enumeradores-payment_type) | Type do payment. | ### Enumerators batch_payment_schedule_status | Enumerator | Description | |---------------|---------------| | `pending_2fa_approval` | Pendente de aprovação 2FA | | `scheduled` | Scheduled | | `rejected` | Rejected | | `error` | Scheduling error | ### Enumerators payment_type | Enumerator | Type | Description | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Fatura de recolhimento | :::danger Warning O enumerador `bank_slip` não se aplica ao fluxo de scheduling em batch de collection slips 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": "Description em português", "code": "Código" } ``` | Código HTTP | Código QI | Título | Description (eng) | Description (pt-br) | |-------------|-----------|--------|------------------|------------------| | 400 | BIP000032 | Bad Request | The bill sent does not correspond to a collection slip. | A account enviada não corresponde a uma collection slip. | | 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 collection slip 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 account 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 account de origem neste momento. Por favor, tente novamente em alguns minutos. | | 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da request 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 account | | 400 | BIP000053 | Bad Request | Error getting approver date | 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 payment excedida. | --- # Bank slip payment batch confirmation URL: /en/documentation/baas/cobranca/2fa_v2/confirmacao_de_lote_de_boleto_bancario This document describes the **same route** as [Bank slip payment batch confirmation](../confirmacao_de_lote_de_boleto_bancario.md) when the operation requires **two-factor authentication (2FA)** at the confirmation step: the request body must include **`tfa_info`** together with `batch_status: approved` or `batch_status: rejected`. Then, the batch may remain in `pending_2fa_approval` (approval) or `pending_2fa_rejection` (rejection) until **token validation**. :::info Bank slip A traditional bank slip (digitable line not starting with digit 8). It is registered in the Interbank Payment Chamber (CIP/Núclea) and can be paid at financial and payment institutions authorized by the Central Bank. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/payment/batch_bank_slip/**PAYMENT_BATCH_KEY**/confirmation METHOD PATCH ### Request Path Params | Field | Type | Description | Characters | | --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- | | `account_key` * | uuid4 | Unique account identifier. | 36 | | `payment_batch_key` * | uuid4 | Unique batch identifier (`batch_payment_key` returned at batch creation). | 36 | ### Request Body **Request Body: Batch rejection (with `tfa_info`)** ```json { "batch_status": "rejected", "tfa_info": { "approver_document_number": "98765432100", "contact_type": "email" } } ``` **Request Body: Batch approval (with `tfa_info`)** ```json { "batch_status": "approved", "tfa_info": { "approver_document_number": "98765432100", "contact_type": "email" } } ``` ### Body Params | Field | Type | Description | | ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `batch_status` * | string | Batch decision. Values: `approved` (continue processing) or `rejected` (cancel the batch). See [batch_confirmation_status enumerator](#enumerador-batch_confirmation_status). | | `tfa_info` | object | Required in this flow with `batch_status: approved` or `batch_status: rejected`; provide approver information and token delivery channel in [tfa_info object](#object-tfa_info). | ### Enumerator batch_confirmation_status | Value | Description | | ---------- | ------------------------------------------------------------- | | `approved` | Approve the batch and continue the processing flow. | | `rejected` | Reject the batch; there is no asynchronous processing of bank slips. | ### Object tfa_info | Field | Type | Description | | ---------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `approver_document_number` * | string | Approver person's document number (CPF) that will receive the token. Required when `tfa_info` is provided. | | `contact_type` * | string | Channel used to send the token (for example, `sms` or `email`), according to operation and registration rules. Required when `tfa_info` is provided. | ## Response The HTTP status and the `batch_status` field in the response depend on the submitted decision and whether the flow requires token validation after this call. ### Response: rejected batch — pending token validation (2FA) STATUS 202 When `batch_status` in the request body is `rejected` and the request includes `tfa_info`, the API responds with **202**. The batch waits for token validation, and the body returns `batch_status` as `pending_2fa_rejection`. After token validation, the rejection decision is applied. **Response Body: Batch waiting for token validation (rejection decision)** ```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: approved batch — pending token validation (2FA) STATUS 202 When `batch_status` in the body is `approved` and the request includes `tfa_info`, the API responds with **202**. The batch waits for token validation, and the body returns `batch_status` as `pending_2fa_approval`. Next steps (code delivery, validation, and resend) are documented in [Batch bank slip token validation](./validacao_de_token_de_lote_de_boleto_bancario.md) and [Resend batch bank slip token](./solicitacao_de_reenvio_de_token_de_lote_de_boleto_bancario.md). **Response Body: Batch waiting for token validation** ```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 | Field | Type | Description | | ----------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `batch_payment_key` * | uuid4 | Unique batch payment identifier. | | `request_control_key` * | uuid4 | Unique client request identifier (batch). | | `account_key` * | uuid4 | Debited account key. | | `total_amount` * | number | Sum of the amounts of all batch items. | | `batch_status` * | string | In this call, the batch remains in `pending_2fa_approval` (approval) or `pending_2fa_rejection` (rejection) until token validation. After validation, the final status reflects the decision sent in confirmation (`approved` or `rejected`). | | `payment_type` * | string | Payment type; for this flow, expected value is `bank_slip`. | ### Error Response STATUS 4XX **Response Body** ```json { "title": "Title", "description": "Description in english", "translation": "Description em português", "code": "Code" } ``` | HTTP code | QI code | Title | Description (eng) | Description (pt-br) | | ----------- | --------- | ----------- | --------------------------------------------- | ----------------------------------------------------- | | 400 | BIP000013 | Bad Request | The source account is closed. | The source account is closed. | | 400 | BIP000050 | Bad Request | Requester configuration does not exist | Requester configuration does not exist. | | 400 | BIP000054 | Bad Request | TFA info required. | TFA info required. | | 404 | BIP000083 | Not Found | Batch payment not found by batch payment key. | Batch payment not found by batch payment key. | | 400 | BIP000084 | Bad Request | Batch payment status is not pending. | Batch payment status is not pending. | --- # Collection slip (utility/tax) payment batch confirmation URL: /en/documentation/baas/cobranca/2fa_v2/confirmacao_de_lote_de_fatura_de_recolhimento This document describes the **same route** as [Collection slip payment batch confirmation (utility/tax)](../confirmacao_de_lote_de_fatura_de_recolhimento.md) when the operation requires **two-factor authentication (2FA)** at the confirmation step: the request body must include **`tfa_info`** together with `batch_status: approved` or `batch_status: rejected`. Then, the batch may remain in `pending_2fa_approval` (approval) or `pending_2fa_rejection` (rejection) until **token validation**. :::info Collection slip (utility/tax bill) This charge type is issued by utility companies (water, electricity, phone, and gas) and public agencies (taxes). It is not registered in the Interbank Payment Chamber (CIP/Núclea), so it does not return the same information as a bank slip. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/payment/batch_collection_slip/**PAYMENT_BATCH_KEY**/confirmation METHOD PATCH ### Request Path Params | Field | Type | Description | Characters | | --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- | | `account_key` * | uuid4 | Unique account identifier. | 36 | | `payment_batch_key` * | uuid4 | Unique batch identifier (`batch_payment_key` returned at batch creation). | 36 | ### Request Body **Request Body: Batch rejection (with `tfa_info`)** ```json { "batch_status": "rejected", "tfa_info": { "approver_document_number": "98765432100", "contact_type": "email" } } ``` **Request Body: Batch approval (with `tfa_info`)** ```json { "batch_status": "approved", "tfa_info": { "approver_document_number": "98765432100", "contact_type": "email" } } ``` ### Body Params | Field | Type | Description | | ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `batch_status` * | string | Batch decision. Values: `approved` (continue processing) or `rejected` (cancel the batch). See [batch_confirmation_status enumerator](#enumerador-batch_confirmation_status). | | `tfa_info` | object | Required in this flow with `batch_status: approved` or `batch_status: rejected`; provide approver information and token delivery channel in [tfa_info object](#object-tfa_info). | ### Enumerator batch_confirmation_status Accepted values in the request body for `batch_status`: | Value | Description | | ---------- | ----------------------------------------------------------------------------- | | `approved` | Approve the batch and continue the processing flow. | | `rejected` | Reject the batch; there is no asynchronous processing of collection slips. | ### Object tfa_info | Field | Type | Description | | ---------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `approver_document_number` * | string | Approver person's document number (CPF) that will receive the token. Required when `tfa_info` is provided. | | `contact_type` * | string | Channel used to send the token (for example, `sms` or `email`), according to operation and registration rules. Required when `tfa_info` is provided. | ## Response The HTTP status and the `batch_status` field in the response depend on the submitted decision and whether the flow requires token validation after this call. ### Response: rejected batch — pending token validation (2FA) STATUS 202 When `batch_status` in the request body is `rejected` and the request includes `tfa_info`, the API responds with **202**. The batch waits for token validation, and the body returns `batch_status` as `pending_2fa_rejection`. After token validation, the rejection decision is applied. **Response Body: Batch waiting for token validation (rejection decision)** ```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: approved batch — pending token validation (2FA) STATUS 202 When `batch_status` in the body is `approved` and the request includes `tfa_info`, the API responds with **202**. The batch waits for token validation, and the body returns `batch_status` as `pending_2fa_approval`. Next steps are documented in [Batch collection slip token validation](./validacao_de_token_de_lote_de_fatura_de_recolhimento.md) and [Resend batch collection slip token](./solicitacao_de_reenvio_de_token_de_lote_de_fatura_de_recolhimento.md). **Response Body: Batch waiting for token validation** ```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 | Field | Type | Description | | ----------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `batch_payment_key` * | uuid4 | Unique batch payment identifier. | | `request_control_key` * | uuid4 | Unique client request identifier (batch). | | `account_key` * | uuid4 | Debited account key. | | `total_amount` * | number | Sum of the amounts of all batch items. | | `batch_status` * | string | In this call, the batch remains in `pending_2fa_approval` (approval) or `pending_2fa_rejection` (rejection) until token validation. After validation, the final status reflects the decision sent in confirmation (`approved` or `rejected`). | | `payment_type` * | string | Payment type; for this flow, expected value is `collection_slip`. | ### Error Response STATUS 4XX **Response Body** ```json { "title": "Title", "description": "Description in english", "translation": "Description em português", "code": "Code" } ``` | HTTP code | QI code | Title | Description (eng) | Description (pt-br) | | ----------- | --------- | ----------- | --------------------------------------------- | ----------------------------------------------------- | | 400 | BIP000013 | Bad Request | The source account is closed. | The source account is closed. | | 400 | BIP000050 | Bad Request | Requester configuration does not exist | Requester configuration does not exist. | | 400 | BIP000054 | Bad Request | TFA info required. | TFA info required. | | 404 | BIP000083 | Not Found | Batch payment not found by batch payment key. | Batch payment not found by batch payment key. | | 400 | BIP000084 | Bad Request | Batch payment status is not pending. | Batch payment status is not pending. | --- # Confirm boleto payment URL: /en/documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_boleto_bancario This endpoint allows the confirmation of boleto payment. :::info Boleto This is the conventional boleto (with digitable lines not starting with the digit 8). It is registered with the Interbank Payment Clearinghouse (CIP/Núclea) and can be paid at financial institutions and payment institutions authorized to operate by the Central Bank. ::: ## Request ### Request Endpoint ENDPOINT /account/ ACCOUNT_KEY /payment/ PAYMENT_KEY /bank_slip/validate_token MÉTODO PATCH ### Request Path Params | Field | Type | Description | Characters | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Unique account identification key. | 36 | | `payment_key` * | uuid4 | Unique payment identification key. | 36 | Request Body: Boleto payment confirmation ```json { "token": "329adf" } ``` ### Body Params | Field | Type | Description | |---------------------|---------------|-----------------------------------| | `token` * | string | Authentication code sent to the account's transaction approver | ## Response ### Success Response STATUS 200 Response Body: Payment executed ```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: Payment pending execution ```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 Information If **HTTP Status 202** is returned with the field `payment_status` having the value **pending_execution**, the payment should not be retried. This payment will be processed asynchronously. It is necessary to check the transfer status through the payment query, or wait for the pending payment webhook described on the [webhooks page](/documentation/baas_v2/cobranca/webhooks). ::: ### Response Body Params | Field | Type | Description | |---------------------|---------|-----------------------------------| | `payment_key` * | uuid4 | Unique payment identification key. | | `request_control_key` * | uuid4 | Unique identification key for the client's request. | | `payer_name` * | string | Name of the effective payer. | | `payer_document_number` * | string | Document number of the effective payer (CPF/CNPJ). | | `source_account_key` * | uuid4 | Key of the debited account. | | `transaction_key` * | uuid4 | Payment transaction key. | | `transaction_revert_key` | uuid4 | Payment reversal transaction key. | | `paid_amount` * | number | Amount effectively paid. | | `payment_date` * | string | Payment date. | | `payment_type` * | [enum](#enumerators-payment_type) | Payment type. | | `bank_slip` | [object](#object-bank_slip) | Boleto. | | `collection_slip` | object | Collection invoice. | | `payment_status` * | [enum](#enumerators-payment_status) | Payment status. | ### Enumerators payment_type | Enumerator | Type | Description | |---------------|-----------|---------------| | `bank_slip` | string | Boleto | | `collection_slip` | string | Collection invoice | :::danger Warning The enumerator `collection_slip` does not apply to the boleto flow, and the collection_slip object will always be null. ::: ### Enumerators payment_status | Enumerator | Description | |---------------|---------------| | `pending_execution` | Pending execution | | `executed` | Executed | | `reverted` | Reverted | | `rejected` | Rejected | | `error` | Error | :::danger Warning For payments where QI does not receive a response from CIP within two minutes, the payment will be returned with the status `pending_execution`. After QI receives the response from CIP, the pending payment webhook described on the [webhooks page](/documentation/baas_v2/cobranca/webhooks) will be sent to the client. ::: ### Object bank_slip | Field | Type | Description | |-----------------------------------|---------|-----------------------------------| | `barcode` * | string | Barcode. | | `digitable_line` * | string | Digitable line. | | `payer_name` * | string | Payer's name. | | `payer_document_number` * | string | Payer's document number (CPF/CNPJ). | | `beneficiary_name` * | string | Beneficiary's name. | | `beneficiary_trading_name` | string | Beneficiary's trade name. | | `beneficiary_document_number` * | string | Beneficiary's document number (CPF/CNPJ). | | `beneficiary_bank_ispb` * | string | ISPB code of the beneficiary's bank. | | `guarantor_name` | string | Name of the guarantor. | | `guarantor_document_number` | string | Guarantor's document number (CPF/CNPJ). | | `expiration_date` * | string | Due date. | | `max_payment_date` * | string | Maximum payment date. | | `partial_payment_indicator` * | [enum](#enumerators-partial_payment_indicator) | Partial payment indicator. | | `registered_payment_amount` | string | Total registered payment amount. | | `nominal_amount` * | number | Original amount. | | `total_amount` * | number | Total amount. | | `rebate_amount` * | number | Rebate amount. | | `discount_amount` * | number | Discount amount. | | `fine_amount` * | number | Fine amount. | | `interest_amount` * | number | Interest amount. | ### Enumerators partial_payment_indicator | Enumerator | Type | Description | |---------------|-----------|---------------| | `allowed` | string | Allowed | | `not_allowed` | string | Not allowed | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Description in portuguese", "code": "Código" } ``` | HTTP Code | QI Code | Title | Description (eng) | Description (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. | --- # Confirm payment of collection invoice (agreement/tribute) URL: /en/documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_fatura_de_recolhimento This endpoint allows the confirmation of collection invoice payments. :::info Collection Invoice This type of charge is issued by utility companies (water, electricity, telephone, and gas bills) and public entities (taxes). They are not registered with the Interbank Payment Clearinghouse (CIP/Núclea) and, therefore, do not return the same information as a boleto. ::: ## Request ### Request Endpoint ENDPOINT /account/ ACCOUNT_KEY /payment/ PAYMENT_KEY /collection_slip/validate_token MÉTODO PATCH ### Request Path Params | Field | Type | Description | Characters | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Unique account identification key. | 36 | | `payment_key` * | uuid4 | Unique payment identification key. | 36 | Request Body: Collection invoice payment confirmation ```json { "token": "329adf" } ``` ### Body Params | Field | Type | Description | |---------------------|---------------|-----------------------------------| | `token` * | string | Authentication code sent to the account's transaction approver | ## Response ### Success Response STATUS 200 Response Body: Payment executed ```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 | Field | Type | Description | |---------------------|---------|-----------------------------------| | `payment_key` * | uuid4 | Unique payment identification key. | | `request_control_key` * | uuid4 | Unique identification key for the client's request. | | `payer_name` * | string | Name of the effective payer. | | `payer_document_number` * | string | Document number of the effective payer (CPF/CNPJ). | | `source_account_key` * | uuid4 | Key of the debited account. | | `transaction_key` * | uuid4 | Payment transaction key. | | `transaction_revert_key` | uuid4 | Payment reversal transaction key. | | `paid_amount` * | number | Amount effectively paid. | | `payment_date` * | string | Payment date. | | `payment_type` * | [enum](#enumerators-payment_type) | Payment type. | | `bank_slip` | object | Boleto bancário. | | `collection_slip` | [object](#object-collection_slip) | Collection invoice. | | `payment_status` * | [enum](#enumerators-payment_status) | Payment status. | ### Enumerators payment_type | Enumerator | Type | Description | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Collection invoice | :::danger Warning The enumerator `bank_slip` does not apply to the collection invoice flow, and the bank_slip object will always be null. ::: ### Enumerators payment_status | Enumerator | Description | |---------------|---------------| | `executed` | Executed | | `reverted` | Reverted | | `rejected` | Rejected | | `error` | Error | ### Object collection_slip | Field | Type | Description | |-----------------------------------|---------|-----------------------------------| | `barcode` | string | Barcode. | | `digitable_line` | string | Digitable line. | | `collection_name` * | string | Name of the agreement. | | `collection_document_number` | string | Document number of the agreement (CPF/CNPJ). | | `expiration_date` * | string | Due date. | | `total_amount` * | number | Total amount. | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Description in portuguese", "code": "Código" } ``` | HTTP Code | QI Code | Title | Description (eng) | Description (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 | 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. | --- # Introduction to Two-Factor Authentication URL: /en/documentation/baas/cobranca/2fa_v2/introducao_ao_pagamento_2fa In this type of payment, payment confirmation via token sent to the person with approval powers for transactions on the payer's account is required. The payment request by integrator partners configured to use two-factor authentication is performed similarly to what is described in [boleto payment](/documentation/baas/cobranca/pagar_boleto_bancario) and [collection invoice payment](/documentation/baas/cobranca/pagar_fatura_de_recolhimento). The difference is the addition of the `tfa_info` object in the request, containing information about the transfer approver and the means of contact, and the status of the request in the response. The status of the request will always be returned as **pending_2fa_approval**. ## Flow for a Payment with Authorization The successful payment will follow the following process flow: - Perform the [boleto payment request](/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_boleto_bancario) or [collection invoice payment request](/documentation/baas_v2/cobranca/2fa_v2/solicitacao_de_pagamento_de_fatura_de_recolhimento) and receive a synchronous response with status **pending_2fa_approval** and the `payment_key`. - The indicated approver will receive a 6-digit `token` consisting of letters and digits. - The requester performs the [boleto payment confirmation](/documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_boleto_bancario) or [collection invoice payment confirmation](/documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_fatura_de_recolhimento) with the `payment_key` and the `token`. - The payment will be completed synchronously. ## Observations - Each payment has a maximum limit of 5 validation attempts for the `token`. When this limit is reached, the payment will be automatically set to rejected (**rejected**) status. - Each `token` has a maximum duration of 5 minutes. - A payment can have its `token` renewed and resent to the account approver. This process resets the 5-minute time but does not reset the invalid attempt counter. The previous `token` becomes invalid. - Once the payment is approved, it will be completed synchronously. - The notification event for sending the `token` to the approver is **baas.token_validation.bill_payment.payment.single**. It is possible to [customize](/documentation/notificacoes/template) the sent message. - The implemented `contact_type` for sending tokens are **sms** and **email**. --- # Request boleto payment (2FA) URL: /en/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_boleto_bancario This endpoint allows the payment request for boletos. The request should be made after a consultation, using the returned information to ensure the correct flow and avoid failures during the process. :::info Boleto This is the conventional boleto (with digitable lines not starting with the digit 8). It is registered with the Interbank Payment Clearinghouse (CIP/Núclea) and can be paid at financial institutions and payment institutions authorized to operate by the Central Bank. ::: ## Request ### Request Endpoint ENDPOINT /account/ ACCOUNT_KEY /payment/bank_slip MÉTODO POST ### Request Path Params | Field | Type | Description | Characters | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Unique account identification key. | 36 | Request Body: Boleto request with digitable line ```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: Boleto request with barcode ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "barcode": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8, "tfa_info": { "approver_document_number": "98765432100", "contact_type": "email" } } ``` ### Body Params | Field | Type | Description | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Unique identification key for the client's request. | | `barcode` | string | Barcode. | | `digitable_line` | string | Digitable line. | | `payment_amount` * | number | Amount to be paid. | | `tfa_info` * | [object](#object-tfa_info) | Object containing the document of the account approver and the means of contact. | :::danger Warning The `payment_amount` must always be equal to the `total_amount` returned in the boleto query if partial payment is not allowed for the boleto. For titles where partial payment is allowed, the client may choose the `payment_amount`, as long as its sum with the boleto's `registered_payment_amount` does not exceed the `total_amount`. ::: ### Object tfa_info | Field | Type | Description | |-----------------------------------|---------|-----------------------------------| | `approver_document_number`* | string | Document number of the account approver. | | `contact_type`* | string | Means of contact with the account approver, can be **sms** or **email** | ## Response ### Success Response STATUS 201 Response Body: Payment pending two-factor approval ```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 | Field | Type | Description | |---------------------|---------|-----------------------------------| | `payment_key` * | uuid4 | Unique payment identification key. | | `request_control_key` * | uuid4 | Unique identification key for the client's request. | | `payer_name` * | string | Name of the effective payer.| | `payer_document_number` * | string | Document number of the effective payer (CPF/CNPJ). | | `source_account_key` * | uuid4 | Key of the debited account. | | `transaction_key` * | uuid4 | Payment transaction key. | | `transaction_revert_key` | uuid4 | Payment reversal transaction key. | | `paid_amount` * | number | Amount effectively paid. | | `payment_date` * | string | Payment date. | | `payment_type` * | [enum](#enumerators-payment_type) | Payment type. | | `bank_slip` | [object](#object-bank_slip) | Boleto. | | `collection_slip` | object | Collection invoice. | | `payment_status` * | [enum](#enumerators-payment_status) | Payment status. | ### Enumerators payment_type | Enumerator | Type | Description | |---------------|-----------|---------------| | `bank_slip` | string | Boleto | | `collection_slip` | string | Collection invoice | :::danger Warning The enumerator `collection_slip` does not apply to the boleto flow, and the collection_slip object will always be null. ::: ### Enumerators payment_status | Enumerator | Description | |---------------|---------------| | `pending_2fa_approval` | pending two-factor approval | ### Object bank_slip | Field | Type | Description | |-----------------------------------|---------|-----------------------------------| | `barcode` * | string | Barcode. | | `digitable_line` * | string | Digitable line. | | `payer_name` * | string | Payer's name.| | `payer_document_number` * | string | Payer's document number (CPF/CNPJ). | | `beneficiary_name` * | string | Beneficiary's name. | | `beneficiary_trading_name` | string | Beneficiary's trade name. | | `beneficiary_document_number` * | string | Beneficiary's document number (CPF/CNPJ). | | `beneficiary_bank_ispb` * | string | ISPB code of the beneficiary's bank. | | `guarantor_name` | string | Name of the guarantor. | | `guarantor_document_number` | string | Guarantor's document number (CPF/CNPJ). | | `expiration_date` * | string | Due date. | | `max_payment_date` * | string | Maximum payment date. | | `partial_payment_indicator` * | [enum](#enumerators-partial_payment_indicator) | Partial payment indicator. | | `registered_payment_amount` | string | Total registered payment amount. | | `nominal_amount` * | number | Original amount. | | `total_amount` * | number | Total amount. | | `rebate_amount` * | number | Rebate amount. | | `discount_amount` * | number | Discount amount. | | `fine_amount` * | number | Fine amount. | | `interest_amount` * | number | Interest amount. | ### Enumerators partial_payment_indicator | Enumerator | Type | Description | |---------------|-----------|---------------| | `allowed` | string | Allowed | | `not_allowed` | string | Not allowed | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Description in portuguese", "code": "Código" } ``` | HTTP Code | QI Code | Title | Description (eng) | Description (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. | ## Sandbox environment In our sandbox environment, we provide mocked digitable lines for simulating successful payments and testing error scenarios. | Digitable line | |-----------------| | 00190000090361557400500000024174396700000991000 | | 00190000090282802601919212747174596760001294161 | | 23793390014000000455277000249001596900000103995 | | 75691434020137513680900001040013196770002417240 | | 21390001171200000570700168167484796770000148206 | | 34191090083273252027893634770007296690012513600 | | 42297048060005815702500130494123896770000239491 | | 07090010287045349010776686070590896770001160123 | | 74891123702849020818918378871083196690000050000 | | 23792374119000209350986000372408496610000122810 | --- # Request payment of collection invoice (agreement/tribute) URL: /en/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_fatura_de_recolhimento This endpoint allows the payment request for collection invoices with two-factor authentication. The request should be made after a consultation, using the returned information to ensure the correct flow and avoid failures during the process. :::info Collection Invoice This type of charge is issued by utility companies (water, electricity, telephone, and gas bills) and public entities (taxes). They are not registered with the Interbank Payment Clearinghouse (CIP/Núclea) and, therefore, do not return the same information as a boleto. ::: ## Request ### Request Endpoint ENDPOINT /account/ ACCOUNT_KEY /payment/collection_slip MÉTODO POST ### Request Path Params | Field | Type | Description | Characters | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Unique account identification key. | 36 | Request Body: Collection invoice request with digitable line ```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: Collection invoice request with barcode ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "barcode": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8, "tfa_info": { "approver_document_number": "98765432100", "contact_type": "email" } } ``` ### Body Params | Field | Type | Description | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Unique identification key for the client's request. | | `barcode` | string | Barcode. | | `digitable_line` | string | Digitable line. | | `payment_amount` * | number | Amount to be paid. | | `tfa_info` * | [object](#object-tfa_info) | Object containing the document of the account approver and the means of contact. | :::danger Warning The `payment_amount` must always be equal to the `total_amount` returned in the boleto query. ::: ### Object tfa_info | Field | Type | Description | |-----------------------------------|---------|-----------------------------------| | `approver_document_number`* | string | Document number of the account approver (CPF/CNPJ). | | `contact_type`* | string | Means of contact with the account approver, can be **sms** or **email** | ## Response ### Success Response STATUS 201 Response Body: Payment pending two-factor approval ```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 | Field | Type | Description | |---------------------|---------|-----------------------------------| | `payment_key` * | uuid4 | Unique payment identification key. | | `request_control_key` * | uuid4 | Unique identification key for the client's request. | | `payer_name` * | string | Name of the effective payer. | | `payer_document_number` * | string | Document of the effective payer (CPF/CNPJ). | | `source_account_key` * | uuid4 | Key of the debited account. | | `transaction_key` * | uuid4 | Payment transaction key. | | `transaction_revert_key` | uuid4 | Payment reversal transaction key. | | `paid_amount` * | number | Amount effectively paid. | | `payment_date` * | string | Payment date. | | `payment_type` * | [enum](#enumerators-payment_type) | Payment type. | | `bank_slip` | object | Boleto bancário. | | `collection_slip` | [object](#object-collection_slip) | Collection invoice. | | `payment_status` * | [enum](#enumerators-payment_status) | Payment status. | ### Enumerators payment_type | Enumerator | Type | Description | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Collection invoice | :::danger Warning The enumerator `bank_slip` does not apply to the collection invoice flow, and the bank_slip object will always be null. ::: ### Enumerators payment_status | Enumerator | Description | |---------------|---------------| | `pending_2fa_approval` | pending two-factor approval | ### Object collection_slip | Field | Type | Description | |-----------------------------------|---------|-----------------------------------| | `barcode` | string | Barcode. | | `digitable_line` | string | Digitable line. | | `collection_name` * | string | Name of the agreement. | | `collection_document_number` | string | Document number of the agreement (CPF/CNPJ).| | `expiration_date` * | string | Due date. | | `total_amount` * | number | Total amount. | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Description in portuguese", "code": "Código" } ``` | HTTP Code | QI Code | Title | Description (eng) | Description (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. | ## Sandbox Environment In our sandbox environment, we provide mocked digitable lines for simulating successful payments and testing error scenarios. | Digitable Line | |---| | 828300000007411100972013905080001546763201900028 | | 838000000009235700481007241345219112001474229880 | | 848000000006308600802021201071261517689002201070 | | 858200000015000000643025703477209504800448091020 | | 858500000037350000643217212883260006147448091022 | --- # Resend payment confirmation token for Boleto URL: /en/documentation/baas/cobranca/2fa_v2/solicitacao_de_reenvio_de_token_de_boleto_bancario This endpoint allows the resending of the authentication token for Boleto payments. :::info Boleto This is the conventional boleto (with digitable lines not starting with the digit 8). It is registered with the Interbank Payment Clearinghouse (CIP/Núclea) and can be paid at financial institutions and payment institutions authorized to operate by the Central Bank. ::: ## Request ### Request Endpoint ENDPOINT /account/ ACCOUNT_KEY /payment/ PAYMENT_KEY /bank_slip/resend_token MÉTODO PATCH ### Request Path Params | Field | Type | Description | Characters | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Unique account identification key. | 36 | | `payment_key` * | uuid4 | Unique payment identification key. | 36 | ## Response ### Success Response STATUS 200 Response Body: Token successfully resent ```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 | Field | Type | Description | |---------------------|---------|-----------------------------------| | `payment_key` * | uuid4 | Unique payment identification key. | | `request_control_key` * | uuid4 | Unique identification key for the client's request. | | `payer_name` * | string | Name of the effective payer. | | `payer_document_number` * | string | Document number of the effective payer (CPF/CNPJ). | | `source_account_key` * | uuid4 | Key of the debited account. | | `transaction_key` * | uuid4 | Payment transaction key. | | `transaction_revert_key` | uuid4 | Payment reversal transaction key. | | `paid_amount` * | number | Amount effectively paid. | | `payment_date` * | string | Payment date. | | `payment_type` * | [enum](#enumerators-payment_type) | Payment type. | | `bank_slip` | [object](#object-bank_slip) | Boleto. | | `collection_slip` | object | Collection invoice. | | `payment_status` * | [enum](#enumerators-payment_status) | Payment status. | ### Enumerators payment_type | Enumerator | Type | Description | |---------------|-----------|---------------| | `bank_slip` | string | Boleto | | `collection_slip` | string | Collection invoice | :::danger Warning The enumerator `collection_slip` does not apply to the boleto flow, and the collection_slip object will always be null. ::: ### Enumerators payment_status | Enumerator | Description | |---------------|---------------| | `pending_2fa_approval` | pending two-factor approval | ### Object bank_slip | Field | Type | Description | |-----------------------------------|---------|-----------------------------------| | `barcode` * | string | Barcode. | | `digitable_line` * | string | Digitable line. | | `payer_name` * | string | Payer's name. | | `payer_document_number` * | string | Payer's document number (CPF/CNPJ). | | `beneficiary_name` * | string | Beneficiary's name. | | `beneficiary_trading_name` | string | Beneficiary's trade name. | | `beneficiary_document_number` * | string | Beneficiary's document number (CPF/CNPJ). | | `beneficiary_bank_ispb` * | string | ISPB code of the beneficiary's bank. | | `guarantor_name` | string | Name of the guarantor. | | `guarantor_document_number` | string | Guarantor's document number (CPF/CNPJ). | | `expiration_date` * | string | Due date. | | `max_payment_date` * | string | Maximum payment date. | | `partial_payment_indicator` * | [enum](#enumerators-partial_payment_indicator) | Partial payment indicator. | | `registered_payment_amount` | string | Total registered payment amount. | | `nominal_amount` * | number | Original amount. | | `total_amount` * | number | Total amount. | | `rebate_amount` * | number | Rebate amount. | | `discount_amount` * | number | Discount amount. | | `fine_amount` * | number | Fine amount. | | `interest_amount` * | number | Interest amount. | ### Enumerators partial_payment_indicator | Enumerator | Type | Description | |---------------|-----------|---------------| | `allowed` | string | Allowed | | `not_allowed` | string | Not allowed | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | HTTP Code | QI Code | Title | Description (eng) | Description (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. | --- # Resend Two-Factor Authentication Token for Collection Invoice Payments URL: /en/documentation/baas/cobranca/2fa_v2/solicitacao_de_reenvio_de_token_de_fatura_de_recolhimento This endpoint allows the resending of the authentication token for collection invoice payments. :::info Collection Invoice This type of charge is issued by utility companies (water, electricity, telephone, and gas bills) and public entities (taxes). They are not registered with the Interbank Payment Clearinghouse (CIP/Núclea) and, therefore, do not return the same information as a boleto. ::: ## Request ### Request Endpoint ENDPOINT /account/ ACCOUNT_KEY /payment/ PAYMENT_KEY /collection_slip/resend_token MÉTODO PATCH ### Request Path Params | Field | Type | Description | Characters | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Unique account identification key. | 36 | | `payment_key` * | uuid4 | Unique payment identification key. | 36 | ## Response ### Success Response STATUS 200 Response Body: Token successfully resent ```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 | Field | Type | Description | |---------------------|---------|-----------------------------------| | `payment_key` * | uuid4 | Unique payment identification key. | | `request_control_key` * | uuid4 | Unique identification key for the client's request. | | `payer_name` * | string | Name of the effective payer. | | `payer_document_number` * | string | Document number of the effective payer (CPF/CNPJ). | | `source_account_key` * | uuid4 | Key of the debited account. | | `transaction_key` * | uuid4 | Payment transaction key. | | `transaction_revert_key` | uuid4 | Payment reversal transaction key. | | `paid_amount` * | number | Amount effectively paid. | | `payment_date` * | string | Payment date. | | `payment_type` * | [enum](#enumerators-payment_type) | Payment type. | | `bank_slip` | object | Boleto. | | `collection_slip` | [object](#object-collection_slip) | Collection invoice. | | `payment_status` * | [enum](#enumerators-payment_status) | Payment status. | ### Enumerators payment_type | Enumerator | Type | Description | |---------------|-----------|---------------| | `bank_slip` | string | Boleto bancário | | `collection_slip` | string | Collection invoice | :::danger Warning The enumerator `bank_slip` does not apply to the collection invoice flow, and the bank_slip object will always be null. ::: ### Enumerators payment_status | Enumerator | Description | |---------------|---------------| | `pending_2fa_approval` | pending two-factor approval | ### Object collection_slip | Field | Type | Description | |-----------------------------------|---------|-----------------------------------| | `barcode` | string | Barcode. | | `digitable_line` | string | Digitable line. | | `collection_name` * | string | Name of the agreement.| | `collection_document_number` | string | Document number of the agreement (CPF/CNPJ).| | `expiration_date` * | string | Due date. | | `total_amount` * | number | Total amount. | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | HTTP Code | QI Code | Title | Description (eng) | Description (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. | --- # Resend token for bank slip payment batch confirmation URL: /en/documentation/baas/cobranca/2fa_v2/solicitacao_de_reenvio_de_token_de_lote_de_boleto_bancario This endpoint allows **resending** the two-factor authentication (2FA) token for a bank slip batch that is waiting for token validation. A new token is generated and sent to the approver. If the token validation attempt limit has been exceeded, resending may not be allowed. :::info Bank slip A traditional bank slip (digitable line not starting with digit 8). It is registered in the Interbank Payment Chamber (CIP/Núclea) and can be paid at financial and payment institutions authorized by the Central Bank. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/payment/batch_bank_slip/**PAYMENT_BATCH_KEY**/resend_token METHOD PATCH ### Request Path Params | Field | Type | Description | Characters | | --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- | | `account_key` * | uuid4 | Unique account identifier. | 36 | | `payment_batch_key` * | uuid4 | Unique batch identifier (`batch_payment_key` returned at batch creation). | 36 | ### Request Body Request Body (opcional) ```json { "contact_type": "sms" } ``` ### Body Params | Field | Type | Description | Characters | | -------------- | ---------- | --------------------------------------- | ------------------------------------------------------- | | `contact_type` | enumerator | Authentication token delivery method | **[Enumerador contact_type](#enumerador-contact_type)** | :::info Information If `contact_type` is not sent, the token will be sent using the originally requested method (`tfa_info.contact_type`). ::: ### Enumerator contact_type | Enumerador | Description | | ---------- | ------------------------------------------------- | | **sms** | Send via SMS to mobile phone | | **email** | Send via email | ## Response ### Success Response STATUS 200 Response Body: Token resent successfully ```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 | Field | Type | Description | | ----------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `batch_payment_key` * | uuid4 | Unique batch payment identifier. | | `request_control_key` * | uuid4 | Unique client request identifier (batch). | | `account_key` * | uuid4 | Debited account key. | | `total_amount` * | number | Sum of the amounts of all batch items. | | `batch_status` * | string | After resend, the batch remains waiting for token validation. The `batch_status` cycle follows the batch payment request documentation available for your operation (enumerator `batch_payment_status`). | | `payment_type` * | string | Payment type; for this flow, expected value is `bank_slip`. | Then use [Batch bank slip token validation](./validacao_de_token_de_lote_de_boleto_bancario.md) to complete 2FA. ### Error Response STATUS 4XX Response Body ```json { "title": "Title", "description": "Description in english", "translation": "Description em português", "code": "Code" } ``` | HTTP code | QI code | Title | Description (eng) | Description (pt-br) | | ----------- | --------- | ----------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | 403 | BIP000010 | Forbidden | User is not allowed to do this action | User is not allowed to do this action | | 404 | BIP000011 | Not Found | The source account key was not found. | The source account key was not found. | | 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | It was not possible to consult the source account at this time. Please try again in a few minutes. | | 400 | BIP000013 | Bad Request | The source account is closed. | The source account is closed. | | 400 | BIP000014 | Bad Request | The source account is blocked. | The source account is blocked. | | 400 | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Number of verification token validation attempts exceeded. | | 400 | BIP000064 | Bad Request | Error resending verification token | Error resending verification token | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Payment verification time window exceeded. | | 404 | BIP000083 | Not Found | Batch payment not found by batch payment key. | Batch payment not found by batch payment key. | | 400 | BIP000085 | Bad Request | Batch payment status is not pending approval. | Batch payment status is not pending approval. | | 400 | BIP000086 | Bad Request | A token is required for SMS or email validation. | A token is required for SMS or email validation. | --- # Resend token for collection slip payment batch confirmation (utility/tax) URL: /en/documentation/baas/cobranca/2fa_v2/solicitacao_de_reenvio_de_token_de_lote_de_fatura_de_recolhimento This endpoint allows **resending** the two-factor authentication (2FA) token for a collection slip batch that is waiting for token validation. A new token is generated and sent to the approver. If the token validation attempt limit has been exceeded, resending may not be allowed. :::info Collection slip (utility/tax bill) This charge type is issued by utility companies (water, electricity, phone, and gas) and public agencies (taxes). It is not registered in the Interbank Payment Chamber (CIP/Núclea), so it does not return the same information as a bank slip. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/payment/batch_collection_slip/**PAYMENT_BATCH_KEY**/resend_token METHOD PATCH ### Request Path Params | Field | Type | Description | Characters | | --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- | | `account_key` * | uuid4 | Unique account identifier. | 36 | | `payment_batch_key` * | uuid4 | Unique batch identifier (`batch_payment_key` returned at batch creation). | 36 | ### Request Body Request Body (opcional) ```json { "contact_type": "sms" } ``` ### Body Params | Field | Type | Description | Characters | | -------------- | ---------- | --------------------------------------- | ------------------------------------------------------- | | `contact_type` | enumerator | Authentication token delivery method | **[Enumerador contact_type](#enumerador-contact_type)** | :::info Information If `contact_type` is not sent, the token will be sent using the originally requested method (`tfa_info.contact_type`). ::: ### Enumerator contact_type | Enumerador | Description | | ---------- | ------------------------------------------------- | | **sms** | Send via SMS to mobile phone | | **email** | Send via email | ## Response ### Success Response STATUS 200 Response Body: Token resent successfully ```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 | Field | Type | Description | | ----------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `batch_payment_key` * | uuid4 | Unique batch payment identifier. | | `request_control_key` * | uuid4 | Unique client request identifier (batch). | | `account_key` * | uuid4 | Debited account key. | | `total_amount` * | number | Sum of the amounts of all batch items. | | `batch_status` * | string | After resend, the batch remains waiting for token validation. The `batch_status` cycle follows the batch payment request documentation available for your operation (enumerator `batch_payment_status`). | | `payment_type` * | string | Payment type; for this flow, expected value is `collection_slip`. | Then use [Batch collection slip token validation](./validacao_de_token_de_lote_de_fatura_de_recolhimento.md) to complete 2FA. ### Error Response STATUS 4XX Response Body ```json { "title": "Title", "description": "Description in english", "translation": "Description em português", "code": "Code" } ``` | HTTP code | QI code | Title | Description (eng) | Description (pt-br) | | ----------- | --------- | ----------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | 403 | BIP000010 | Forbidden | User is not allowed to do this action | User is not allowed to do this action | | 404 | BIP000011 | Not Found | The source account key was not found. | The source account key was not found. | | 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | It was not possible to consult the source account at this time. Please try again in a few minutes. | | 400 | BIP000013 | Bad Request | The source account is closed. | The source account is closed. | | 400 | BIP000014 | Bad Request | The source account is blocked. | The source account is blocked. | | | 400 | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Number of verification token validation attempts exceeded. | | 400 | BIP000064 | Bad Request | Error resending verification token | Error resending verification token | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Payment verification time window exceeded. | | 404 | BIP000083 | Not Found | Batch payment not found by batch payment key. | Batch payment not found by batch payment key. | | 400 | BIP000085 | Bad Request | Batch payment status is not pending approval. | Batch payment status is not pending approval. | 400 | BIP000086 | Bad Request | A token is required for SMS or email validation. | A token is required for SMS or email validation. | --- # Request bank slip batch payment with two-factor authentication URL: /en/documentation/baas/cobranca/2fa_v2/solicitar_pagamento_lote_de_boleto_bancario_com_confirmacao_de_lote This endpoint allows requesting payment of multiple bank slips in a single request, with **`tfa_info`** when the operation requires two-factor authentication **at this request step**. :::info Bank slip A traditional bank slip (digitable line not starting with digit 8). It is registered in the Interbank Payment Chamber (CIP/Núclea) and can be paid at financial and payment institutions authorized by the Central Bank. ::: :::info Flow after the request After the request, the batch may remain waiting for [batch confirmation with two-factor authentication](./confirmacao_de_lote_de_boleto_bancario.md), according to operation rules. In this confirmation step, follow the flow with `tfa_info` described in that document. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments/batch_bank_slip METHOD POST ### Request Path Params | Field | Type | Description | Characters | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Unique account identifier. | 36 | Request Body: Batch bank slip payment (without TFA at this step) ```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 | Field | Type | Description | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Unique client request identifier (batch). | | `bank_slip_payments` * | array | List of bank slip payments. Limit of **1000** items per request. | Each item in `bank_slip_payments` must include: | Field | Type | Description | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Unique client request identifier for that batch item. | | `barcode` | string | Barcode. | | `digitable_line` | string | Digitable line. | | `payment_amount` * | number | Value a ser pago. | :::danger Warning For each item, the submitted `payment_amount` must be compatible with the internal bank slip lookup: if partial payment is **not** allowed, the amount must match the updated total; if allowed, `payment_amount` may follow title rules (including, when applicable, values above nominal), as in the single bank slip payment flow. ::: ### Object tfa_info | Field | Type | Description | | ---------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `approver_document_number` * | string | Document number (CPF/CNPJ) of the approver who will receive the token or approve via device. Required when `tfa_info` is provided. | | `session_id` | string | Unique device session identifier in UUID v4 format (**required** for device-based TFA). | | `contact_type` * | string | Channel for token delivery or validation: **[contact_type enumerator](#enumerador-contact_type)**. Required when `tfa_info` is provided. | #### Enumerator contact_type | Enumerador | Description | |------------|---------------------------------------------------| | **sms** | Send via SMS to mobile phone | | **email** | Send via email | | **device** | Validation via device token | ## Response ### Success Response STATUS 202 Response Body: Batch accepted for processing ```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 Batch processing The `batch_status` field in the response indicates the **immediate state** of the batch after this request (for example, pending confirmation, pending 2FA approval, or already routed to processing), according to the applicable flow. When there is a [batch confirmation](./confirmacao_de_lote_de_boleto_bancario.md) step, follow that documentation to approve or reject the batch with two-factor authentication. Possible `batch_status` values are listed in [batch_payment_status](#enumeradores-batch_payment_status). ::: ### Response Body Params | Field | Type | Description | |---------------------|---------|-----------------------------------| | `batch_payment_key` * | uuid4 | Unique batch payment identifier. | | `request_control_key` * | uuid4 | Unique client request identifier (batch). | | `account_key` * | uuid4 | Debited account key. | | `total_amount` * | number | Sum of `payment_amount` across all batch items. | | `batch_status` * | [enum](#enumeradores-batch_payment_status) | Batch status right after request; depends on the flow (confirmation, 2FA, and immediate processing). | | `payment_type` * | [enum](#enumeradores-payment_type) | Payment type. | ### Enumeratores batch_payment_status | Enumerador | Description | |---------------|---------------| | `pending` | Pendente de processamento | | `pending_2fa_approval` | Pending 2FA approval | | `rejected` | Rejeitado | | `approved` | Aprovado | | `processed` | Processado | ### Enumeratores payment_type | Enumerador | Type | Description | |---------------|-----------|---------------| | `bank_slip` | string | Bank slip | | `collection_slip` | string | Collection slip (utility/tax bill) | :::danger Warning The `collection_slip` enumerator does not apply to this bank slip batch endpoint; in this flow, `payment_type` must be `bank_slip`. ::: ### Error Response STATUS 4XX Response Body ```json { "title": "Title", "description": "Description in english", "translation": "Description em português", "code": "Code" } ``` | HTTP code | QI code | Title | Description (eng) | Description (pt-br) | |-------------|-----------|--------|------------------|------------------| | 403 | BIP000010 | Forbidden | User is not allowed to do this action | User is not allowed to do this action | | 404 | BIP000011 | Not Found | The source account key was not found. | The source account key was not found. | | 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | It was not possible to consult the source account at this time. Please try again in a few minutes. | | 400 | BIP000024 | Bad Request | Request control key already exists. | Request control key already exists. | | 400 | BIP000050 | Bad Request | Requester configuration does not exist. | Requester configuration does not exist. | | 400 | BIP000052 | Bad Request | Given document number does not belong to an approver for this account | Provided document number does not belong to an account approver | | 400 | BIP000053 | Bad Request | Error getting approver data | Error getting approver data | | 400 | BIP000054 | Bad Request | TFA info required | TFA info required | | 400 | BIP000055 | Bad Request | Error sending verification token | Error sending verification token | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Payment verification time window exceeded. | | 400 | BIP000079 | Bad Request | A session_id must be provided token | A session_id must be provided | | 400 | BIP000080 | Bad Request | Beneficiary bank code of this bank slip is not allowed. | Beneficiary bank code of this bank slip is not allowed. | | 400 | BIP000081 | Bad Request | A list of bank slip payments must be provided. | A list of bank slip payments must be provided. | --- # Solicitar pagamento em lote de boleto bancário com autenticação de dois fatores URL: /en/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. | --- # Request collection slip (utility/tax) batch payment with two-factor authentication URL: /en/documentation/baas/cobranca/2fa_v2/solicitar_pagamento_lote_de_fatura_de_recolhimento_com_confirmacao_de_lote This endpoint allows requesting payment of multiple collection slips in a single request, with **`tfa_info`** when the operation requires two-factor authentication **at this request step**. :::info Collection slip (utility/tax bill) This charge type is issued by utility companies (water, electricity, phone, and gas) and public agencies (taxes). It is not registered in the Interbank Payment Chamber (CIP/Núclea), so it does not return the same information as a bank slip. ::: :::info Flow after the request After the request, the batch may remain waiting for [batch confirmation with two-factor authentication](./confirmacao_de_lote_de_fatura_de_recolhimento.md), according to operation rules. When 2FA is required at this request step, include **`tfa_info`** as shown below and in the [tfa_info object](#object-tfa_info). In the batch confirmation step for this flow, follow the documentation with `tfa_info`. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments/batch_collection_slip METHOD POST ### Request Path Params | Field | Type | Description | Characters | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Unique account identifier. | 36 | Request Body: Batch collection slip payment (without TFA at this step) ```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 } ] } ``` ## Authentication via Email and SMS Request Body: batch with digitable line and TFA via SMS or 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: batch with barcode and TFA via SMS or 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 } ] } ``` ## Authentication via Device Besides existing authentication methods via **sms** and **email**, you can authenticate the transaction using a [previously registered device](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). In this case, `session_id` must be obtained in **Device Scan** and sent in `tfa_info`. Request Body: batch with digitable line and device TFA ```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: batch with barcode and device TFA ```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 | Field | Type | Description | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Unique client request identifier (batch). | | `tfa_info` | object | When 2FA is required **at this step** (batch request), send approver and token channel fields in the [tfa_info object](#object-tfa_info). If this flow does not require 2FA at request time, omit this field. | | `collection_slip_payments` * | array | List of collection slip payments. Limit of **1000** items per request. | Each item in `collection_slip_payments` must include: | Field | Type | Description | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Unique client request identifier for that batch item. | | `barcode` | string | Barcode. | | `digitable_line` | string | Digitable line. | | `payment_amount` * | number | Value a ser pago. | :::danger Warning For each item, `payment_amount` must be compatible with the internal collection slip lookup (for example, aligned with `total_amount` and utility/tax rules), under the same conditions as the single collection slip payment flow. ::: ### Object tfa_info | Field | Type | Description | | ---------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `approver_document_number` * | string | Document number (CPF/CNPJ) of the approver who will receive the token or approve via device. Required when `tfa_info` is provided. | | `session_id` | string | Unique device session identifier in UUID v4 format (**required** for device-based TFA). | | `contact_type` * | string | Channel for token delivery or validation: **[contact_type enumerator](#enumerador-contact_type)**. Required when `tfa_info` is provided. | #### Enumerator contact_type | Enumerador | Description | |------------|---------------------------------------------------| | **sms** | Send via SMS to mobile phone | | **email** | Send via email | | **device** | Validation via device token | ## Response ### Success Response STATUS 202 Response Body: Batch accepted for processing ```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 Batch processing The `batch_status` field in the response indicates the **immediate state** of the batch after this request (for example, pending confirmation, pending 2FA approval, or already routed to processing), according to the applicable flow. When there is a [batch confirmation](./confirmacao_de_lote_de_fatura_de_recolhimento.md) step, follow that documentation to approve or reject the batch with two-factor authentication. Possible `batch_status` values are listed in [batch_payment_status](#enumeradores-batch_payment_status). ::: ### Response Body Params | Field | Type | Description | |---------------------|---------|-----------------------------------| | `batch_payment_key` * | uuid4 | Unique batch payment identifier. | | `request_control_key` * | uuid4 | Unique client request identifier (batch). | | `account_key` * | uuid4 | Debited account key. | | `total_amount` * | number | Sum of `payment_amount` across all batch items. | | `batch_status` * | [enum](#enumeradores-batch_payment_status) | Batch status right after request; depends on the flow (confirmation, 2FA, and immediate processing). | | `payment_type` * | [enum](#enumeradores-payment_type) | Payment type. | ### Enumeratores batch_payment_status | Enumerador | Description | |---------------|---------------| | `pending` | Pendente de processamento | | `pending_2fa_approval` | Pending 2FA approval | | `rejected` | Rejeitado | | `approved` | Aprovado | | `processed` | Processado | ### Enumeratores payment_type | Enumerador | Type | Description | |---------------|-----------|---------------| | `bank_slip` | string | Bank slip | | `collection_slip` | string | Collection slip (utility/tax bill) | :::danger Warning The `bank_slip` enumerator does not apply to this collection slip batch endpoint; in this flow, `payment_type` must be `collection_slip`. ::: ### Error Response STATUS 4XX Response Body ```json { "title": "Title", "description": "Description in english", "translation": "Description em português", "code": "Code" } ``` | HTTP code | QI code | Title | Description (eng) | Description (pt-br) | |-------------|-----------|--------|------------------|------------------| | 400 | BIP000024 | Bad Request | Request control key already exists. | Request control key already exists. | | 400 | BIP000050 | Bad Request | Requester configuration does not exist. | Requester configuration does not exist. | | 400 | BIP000052 | Bad Request | Given document number does not belong to an approver for this account | Provided document number does not belong to an account approver | | 400 | BIP000053 | Bad Request | Error getting approver data | Error getting approver data | | 400 | BIP000054 | Bad Request | TFA info required | TFA info required | | 400 | BIP000055 | Bad Request | Error sending verification token | Error sending verification token | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Payment verification time window exceeded. | | 400 | BIP000079 | Bad Request | A session_id must be provided token | A session_id must be provided | | 400 | BIP000082 | Bad Request | A list of collection slip payments must be provided. | A list of collection slip payments must be provided. | --- # Solicitar pagamento em lote de fatura de recolhimento (convênio/tributo) com autenticação de dois fatores URL: /en/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. | --- # Token validation for bank slip payment batch URL: /en/documentation/baas/cobranca/2fa_v2/validacao_de_token_de_lote_de_boleto_bancario This endpoint completes the **two-factor authentication (2FA)** step for a bank slip batch that, after [batch confirmation with `tfa_info`](../confirmacao_de_lote_de_boleto_bancario_autenticacao_dois_fatores.md), is in `batch_status` **`pending_2fa_approval`** (approval) or **`pending_2fa_rejection`** (rejection). After token validation, the batch proceeds to **asynchronous payment processing**, and the final status reflects the decision recorded at confirmation (`approved` or `rejected`). To request a new token while the batch is in **pending_2fa_approval** (approval) or **pending_2fa_rejection** (rejection), use [Resend token for bank slip payment batch confirmation](./solicitacao_de_reenvio_de_token_de_lote_de_boleto_bancario.md). :::info Bank slip A traditional bank slip (digitable line not starting with digit 8). It is registered in the Interbank Payment Chamber (CIP/Núclea) and can be paid at financial and payment institutions authorized by the Central Bank. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/payment/batch_bank_slip/**PAYMENT_BATCH_KEY**/validate_token METHOD PATCH ### Request Path Params | Field | Type | Description | Characters | | --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- | | `account_key` * | uuid4 | Unique account identifier. | 36 | | `payment_batch_key` * | uuid4 | Unique batch identifier (`batch_payment_key` returned at batch creation). | 36 | ### Authentication via Email and SMS Request Body: Batch token validation ```json { "token": "329adf" } ``` ### Authentication via Device To complete device authentication, the request must be sent with an empty payload. Validation is performed internally, with no additional request body information required. This endpoint should only be used after the batch enters **`pending_2fa_approval`** (approval) or **`pending_2fa_rejection`** (rejection) at [batch confirmation with `tfa_info`](../confirmacao_de_lote_de_boleto_bancario_autenticacao_dois_fatores.md). Request Body: Batch token validation ```json { } ``` ### Body Params | Field | Type | Description | Characters | | ------- | ------ | ---------------------------------------------------------------------------------------------------------------- | ---------- | | `token` | string | Authentication code sent to the account transaction approver **required for TFA via SMS or email** | 6 | ## Response ### Success Response After successful validation, the API responds with **202** and the batch is processed asynchronously. The final status follows the decision registered in confirmation (`approved` or `rejected`). STATUS 202 Response Body: Batch after token validation (example with `approved` decision) ```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 | Field | Type | Description | | ----------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `batch_payment_key` * | uuid4 | Unique batch payment identifier. | | `request_control_key` * | uuid4 | Unique client request identifier (batch). | | `account_key` * | uuid4 | Debited account key. | | `total_amount` * | number | Sum of the amounts of all batch items. | | `batch_status` * | string | After token validation, the final status reflects the decision registered during confirmation (`approved` or `rejected`). The `batch_status` cycle follows the batch payment request documentation available for your operation (enumerator `batch_payment_status`). | | `payment_type` * | string | Payment type; for this flow, expected value is `bank_slip`. | ### Error Response STATUS 4XX Response Body ```json { "title": "Title", "description": "Description in english", "translation": "Description em português", "code": "Code" } ``` | HTTP code | QI code | Title | Description (eng) | Description (pt-br) | | ----------- | --------- | ----------- | --------------------------------------------- | ---------------------------------------------------------------- | | 403 | BIP000010 | Forbidden | User is not allowed to do this action | User is not allowed to do this action | | 404 | BIP000011 | Not Found | The source account key was not found. | The source account key was not found. | | 400 | BIP000013 | Bad Request | The source account is closed. | The source account is closed. | | 400 | BIP000050 | Bad Request | Requester configuration does not exist | Requester configuration does not exist. | | 400 | BIP000058 | Bad Request | Error while validating verification token | Error while validating verification token | | 400 | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Number of verification token validation attempts exceeded. | | 400 | BIP000060 | Bad Request | Verification token expired. | Verification token expired. | | 400 | BIP000061 | Bad Request | Verification token validation failed. | Verification token validation failed. | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Payment verification time window exceeded. | | 404 | BIP000083 | Not Found | Batch payment not found by batch payment key. | Batch payment not found by batch payment key. | | 400 | BIP000085 | Bad Request | Batch payment status is not pending approval. | Batch payment status is not pending approval. | | 400 | BIP000086 | Bad Request | A token is required for SMS or email validation. | A token is required for SMS or email validation. | --- # Token validation for collection slip payment batch (utility/tax) URL: /en/documentation/baas/cobranca/2fa_v2/validacao_de_token_de_lote_de_fatura_de_recolhimento This endpoint completes the **two-factor authentication (2FA)** step for a collection slip batch that, after [batch confirmation with `tfa_info`](../confirmacao_de_lote_de_fatura_de_recolhimento_autenticacao_dois_fatores.md), is in `batch_status` **`pending_2fa_approval`** (approval) or **`pending_2fa_rejection`** (rejection). After token validation, the batch proceeds to **asynchronous payment processing**, and the final status reflects the decision recorded at confirmation (`approved` or `rejected`). To request a new token while the batch is in **pending_2fa_approval** (approval) or **pending_2fa_rejection** (rejection), use [Resend token for collection slip payment batch confirmation (utility/tax)](./solicitacao_de_reenvio_de_token_de_lote_de_fatura_de_recolhimento.md). :::info Collection slip (utility/tax bill) This charge type is issued by utility companies (water, electricity, phone, and gas) and public agencies (taxes). It is not registered in the Interbank Payment Chamber (CIP/Núclea), so it does not return the same information as a bank slip. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/payment/batch_collection_slip/**PAYMENT_BATCH_KEY**/validate_token METHOD PATCH ### Request Path Params | Field | Type | Description | Characters | | --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- | | `account_key` * | uuid4 | Unique account identifier. | 36 | | `payment_batch_key` * | uuid4 | Unique batch identifier (`batch_payment_key` returned at batch creation). | 36 | ### Authentication via Email and SMS Request Body: Batch token validation ```json { "token": "329adf" } ``` ### Authentication via Device To complete device authentication, the request must be sent with an empty payload. Validation is performed internally, with no additional request body information required. This endpoint should only be used after the batch enters **`pending_2fa_approval`** (approval) or **`pending_2fa_rejection`** (rejection) at [batch confirmation with `tfa_info`](../confirmacao_de_lote_de_fatura_de_recolhimento_autenticacao_dois_fatores.md). Request Body: Batch token validation ```json { } ``` ### Body Params | Field | Type | Description | Characters | | ------- | ------ | ---------------------------------------------------------------------------------------------------------------- | ---------- | | `token` | string | Authentication code sent to the account transaction approver **required for TFA via SMS or email** | 6 | ## Response ### Success Response After successful validation, the API responds with **202** and the batch is processed asynchronously. The final status follows the decision registered in confirmation (`approved` or `rejected`). STATUS 202 Response Body: Batch after token validation (example with `approved` decision) ```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 | Field | Type | Description | | ----------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `batch_payment_key` * | uuid4 | Unique batch payment identifier. | | `request_control_key` * | uuid4 | Unique client request identifier (batch). | | `account_key` * | uuid4 | Debited account key. | | `total_amount` * | number | Sum of the amounts of all batch items. | | `batch_status` * | string | After token validation, the final status reflects the decision registered during confirmation (`approved` or `rejected`). The `batch_status` cycle follows the batch payment request documentation available for your operation (enumerator `batch_payment_status`). | | `payment_type` * | string | Payment type; for this flow, expected value is `collection_slip`. | ### Error Response STATUS 4XX Response Body ```json { "title": "Title", "description": "Description in english", "translation": "Description em português", "code": "Code" } ``` | HTTP code | QI code | Title | Description (eng) | Description (pt-br) | | ----------- | --------- | ----------- | --------------------------------------------- | ---------------------------------------------------------------- | | 403 | BIP000010 | Forbidden | User is not allowed to do this action | User is not allowed to do this action | | 404 | BIP000011 | Not Found | The source account key was not found. | The source account key was not found. | | 400 | BIP000013 | Bad Request | The source account is closed. | The source account is closed. | | 400 | BIP000050 | Bad Request | Requester configuration does not exist | Requester configuration does not exist. | | 400 | BIP000058 | Bad Request | Error while validating verification token | Error while validating verification token | | 400 | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Number of verification token validation attempts exceeded. | | 400 | BIP000060 | Bad Request | Verification token expired. | Verification token expired. | | 400 | BIP000061 | Bad Request | Verification token validation failed. | Verification token validation failed. | | 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Payment verification time window exceeded. | | 404 | BIP000083 | Not Found | Batch payment not found by batch payment key. | Batch payment not found by batch payment key. | | 400 | BIP000085 | Bad Request | Batch payment status is not pending approval. | Batch payment status is not pending approval. | | 400 | BIP000086 | Bad Request | A token is required for SMS or email validation. | A token is required for SMS or email validation. | --- # Schedule Boleto payment URL: /en/documentation/baas/cobranca/agendamento/agendar_pagamento_de_boleto_bancario This endpoint allows scheduling the payment of boletos. The scheduling should be made after consulting the boleto, using the returned information to ensure the correct flow and avoid failures during the payment process. :::info Boleto This is the conventional boleto (with digitable lines not starting with the digit 8). It is registered with the Interbank Payment Clearinghouse (CIP/Núclea) and can be paid at financial institutions and payment institutions authorized to operate by the Central Bank. ::: ## Request ENDPOINT /account/ ACCOUNT_KEY /payment_schedule/bank_slip METHOD POST ### Request Path Params | Field | Type | Description | Characters | |----------------|--------|-------------------------------------------|------------| | `account_key` *| uuidv4 | Unique account identification key. | 36 | Request Body: Payment of boleto with digitable line ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "digitable_line": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8, "payment_date": "2024-03-30" } ``` Request Body: Payment of boleto with barcode ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "barcode": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8, "payment_date": "2024-03-30" } ``` ### Body Params | Field | Type | Description | |-----------------------|--------|--------------------------------------------------------| | `request_control_key` * | uuid4 | Unique identification key for the client's request. | | `barcode` | string | Barcode. | | `digitable_line` | string | Digitable line. | | `payment_amount` * | number | Amount to be paid. | | `payment_date` * | string | Scheduling date. | :::danger Warning The `payment_amount` must always be equal to the `total_amount` returned in the boleto query if partial payment is not allowed for the boleto. For titles where partial payment is allowed, the client may choose the `payment_amount`, as long as its sum with the boleto's `registered_payment_amount` does not exceed the `total_amount`. ::: ## Response ### Success Response STATUS 201 Response Body: Schedule confirmed ```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 | Field | Type | Description | |----------------------|--------|-------------------------------------------------------------------| | `payment_key` * | uuid4 | Unique payment identification key. | | `request_control_key` * | uuid4| Unique identification key for the client's request. | | `payer_name` * | string | Name of the effective payer. | | `payer_document_number` * | string| Document number of the effective payer (CPF/CNPJ). | | `source_account_key` * | uuid4 | Key of the debited account. | | `paid_amount` * | number | Amount effectively paid. | | `payment_date` * | string | Payment date. | | `payment_type` * | [enum](#enumeradores-payment_type) | Payment type. | | `bank_slip` | [object](#object-bank_slip) | Boleto. | | `collection_slip` | object | Collection invoice. | | `payment_schedule_status` * | [enum](#enumeradores-payment_schedule_status) | Payment status. | ### Enumeradores payment_type | Enumerator | Description | |---------------------|---------------------------| | `bank_slip` | Boleto | | `collection_slip` | Collection invoice | :::danger Warning The enumerator `collection_slip` does not apply to the boleto flow, and the collection_slip object will always be null. ::: ### Enumeradores payment_schedule_status | Enumerator | Description | |---------------------------|------------------------------------------------------------------------------------------------| | `pending_2fa_approval` | Schedule pending two-factor authentication (2FA) | | `scheduled` | Payment successfully scheduled | | `executed` | The payment related to the schedule was successfully executed | | `rejected` | The payment related to the schedule was rejected | | `canceled` | Schedule canceled | | `error` | Error during scheduling | :::danger Warning For payments where QI does not receive a response from CIP within two minutes, the payment will be returned with the status `pending_execution`. After QI receives the response from CIP, the pending payment webhook described on the [webhooks page](/documentation/baas_v2/cobranca/webhooks) will be sent to the client. ::: ### Object bank_slip | Field | Type | Description | |-------------------------|-----------|-----------------------------------------------------------------------------| | `barcode` * | string | Barcode. | | `digitable_line` * | string | Digitable line. | | `payer_name` * | string | Payer's name. | | `payer_document_number` * | string | Payer's document number (CPF/CNPJ). | | `beneficiary_name` * | string | Beneficiary's name. | | `beneficiary_trading_name` | string | Beneficiary's trade name. | | `beneficiary_document_number` * | string | Beneficiary's document number (CPF/CNPJ). | | `beneficiary_bank_ispb` * | string | ISPB code of the beneficiary's bank. | | `guarantor_name` | string | Name of the guarantor. | | `guarantor_document_number` | string | Guarantor's document number (CPF/CNPJ). | | `expiration_date` * | string | Due date. | | `max_payment_date` * | string | Maximum payment date. | | `partial_payment_indicator` * | [enum](#enumeradores-partial_payment_indicator) | Partial payment indicator. | | `registered_payment_amount` | string| Total registered payment amount. | | `nominal_amount` * | number | Original amount. | | `total_amount` * | number | Total amount. | | `rebate_amount` * | number | Rebate amount. | | `discount_amount` * | number | Discount amount. | | `fine_amount` * | number | Fine amount. | | `interest_amount` * | number | Interest amount. | ### Enumeradores partial_payment_indicator | Enumerator | Description | |--------------- |-----------------------| | `allowed` | Allowed | | `not_allowed` | Not allowed | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Description in portuguese", "code": "Código" } ``` | HTTP Code | QI Code | Title | Description (eng) | Description (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). --- # Schedule payment of collection invoice (agreement/tribute) URL: /en/documentation/baas/cobranca/agendamento/agendar_pagamento_de_fatura_de_recolhimento This endpoint allows scheduling the payment of collection invoices. The scheduling should be made after consulting the Collection Invoice, using the returned information to ensure the correct flow and avoid failures during the payment process. :::info Collection Invoice This type of charge is issued by utility companies (water, electricity, telephone, and gas bills) and public entities (taxes). They are not registered with the Interbank Payment Clearinghouse (CIP/Núclea) and, therefore, do not return the same information as a boleto. ::: ## Request ENDPOINT /account/ ACCOUNT_KEY /payment_schedule/collection_slip METHOD POST ### Request Path Params | Field | Type | Description | Characters | |----------------|--------|-------------------------------------------|------------| | `account_key` *| uuidv4 | Unique account identification key. | 36 | Request Body: Scheduling of collection invoice with digitable line ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "digitable_line": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8, "payment_date": "2024-03-30" } ``` Request Body: Scheduling of collection invoice with barcode ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "barcode": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8, "payment_date": "2024-03-30" } ``` ### Body Params | Field | Type | Description | |----------------------|---------|--------------------------------------------| | `request_control_key` *| uuid4 | Unique identification key for the client's request. | | `barcode` | string | Barcode. | | `digitable_line` | string | Digitable line. | | `payment_amount` * | number | Amount to be paid. | | `payment_date` * | string | Scheduling date. | :::danger Warning The `payment_amount` must always be equal to the `total_amount` returned in the boleto query. ::: ## Response ### Success Response STATUS 201 Response Body: Schedule confirmed ```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 | Field | Type | Description | |----------------------|--------|---------------------------------------------------| | `payment_key` * | uuid4 | Unique payment identification key. | | `request_control_key` *| uuid4 | Unique identification key for the client's request.| | `payer_name` * | string | Name of the effective payer. | | `payer_document_number` *| string | Document number of the effective payer (CPF/CNPJ).| | `source_account_key` *| uuid4 | Key of the debited account. | | `transaction_key` * | uuid4 | Payment transaction key. | | `transaction_revert_key` | uuid4 | Payment reversal transaction key. | | `paid_amount` * | number | Amount effectively paid. | | `payment_date` * | string | Payment date. | | `payment_type` * | [enum](#enumeradores-payment_type) | Payment type. | | `bank_slip` | object | Boleto. | | `collection_slip` | [object](#object-collection_slip) | Collection invoice. | | `payment_schedule_status` * | [enum](#enumeradores-payment_schedule_status) | Schedule status. | ### Enumeradores payment_type | Enumerator | Description | |---------------------|---------------------------| | `bank_slip` | Boleto | | `collection_slip` | Collection invoice | :::danger Warning The enumerator `bank_slip` does not apply to the collection invoice flow, and the bank_slip object will always be null. ::: ### Enumeradores payment_schedule_status | Enumerator | Description | |---------------------------|------------------------------------------------------------------------------------------------| | `pending_2fa_approval` | Schedule pending two-factor authentication (2FA) | | `scheduled` | Payment successfully scheduled | | `executed` | The payment related to the schedule was successfully executed | | `rejected` | The payment related to the schedule was rejected | | `canceled` | Schedule canceled | | `error` | Error during scheduling | ### Object collection_slip | Field | Type | Description | |---------------------------|-----------|-----------------------------------------------------------------------------------| | `barcode` | string | Barcode. | | `digitable_line` | string | Digitable line. | | `collection_name` * | string | Name of the agreement. | | `collection_document_number` | string | Document number of the agreement (CPF/CNPJ). | | `expiration_date` * | string | Due date. | | `total_amount` * | number | Total amount. | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Description em portuguese", "code": "Código" } ``` | HTTP Code | QI Code | Title | Description (eng) | Description (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. | ## Sandbox Environment In our sandbox environment, we provide mocked digitable lines for simulating successful payments and testing error scenarios. ### Success scenarios | Digitable line | |---| | 828300000007411100972013905080001546763201900028 | | 838000000009235700481007241345219112001474229880 | | 848000000006308600802021201071261517689002201070 | | 858200000015000000643025703477209504800448091020 | ### Error Scenarios | Digitable line | Error code0 | |---|---| | 858500000037350000643217212883260006147448091022 | BIP000035 | --- # Cancel schedule URL: /en/documentation/baas/cobranca/agendamento/cancelar_agendamento This endpoint is used to cancel a scheduled payment of a Boleto or Collection Invoice. :::info Boleto This is the conventional boleto (with digitable lines not starting with the digit 8). It is registered with the Interbank Payment Clearinghouse (CIP/Núclea) and can be paid at financial institutions and payment institutions authorized to operate by the Central Bank. ::: :::info Collection Invoice This type of charge is issued by utility companies (water, electricity, telephone, and gas bills) and public entities (taxes). They are not registered with the Interbank Payment Clearinghouse (CIP/Núclea) and, therefore, do not return the same information as a boleto. ::: ## Request ENDPOINT /account/ ACCOUNT_KEY /payment_schedule/ PAYMENT_SCHEDULE_KEY /cancel METHOD PATCH ### Request Path Params | Field | Type | Description | Characters | |-------------------------|--------|-----------------------------------------------|------------| | `account_key` * | uuidv4 | Unique account identification key. | 36 | | `payment_schedule_key` *| uuidv4 | Unique schedule identification key. | 36 | ## Response ### Success Response STATUS 200 Response Body: Scheduled payment of boleto cancelled ```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: Scheduled payment of collection invoice cancelled ```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 | Field | Type | Description | |---------------------------|--------|----------------------------------------------------------------| | `payment_key` * | uuid4 | Unique payment identification key. | | `request_control_key` * | uuid4 | Unique identification key for the client's request. | | `payer_name` * | string | Name of the effective payer. | | `payer_document_number` * | string | Document number of the effective payer (CPF/CNPJ). | | `source_account_key` * | uuid4 | Key of the debited account. | | `paid_amount` * | number | Amount effectively paid. | | `payment_date` * | string | Scheduling date. | | `payment_type` * | [enum](#enumeradores-payment_type) | Payment type. | | `bank_slip` | [object](#object-bank_slip) | Boleto. | | `collection_slip` | object | Collection invoice. | | `payment_schedule_status` * | [enum](#enumeradores-payment_schedule_status) | Schedule status. | ### Enumerators payment_type | Enumerator | Type | Description | |-------------------|--------|---------------------------| | `bank_slip` | string | Boleto | | `collection_slip` | string | Collection invoice | ### Enumerators payment_schedule_status | Enumerator | Description | |-------------------|---------------------------| | `canceled` | Schedule canceled | ### Object bank_slip | Field | Type | Description | |--------------------------------|-----------|---------------------------------------------------------------------------| | `barcode` * | string | Barcode. | | `digitable_line` * | string | Digitable line. | | `payer_name` * | string | Payer's name. | | `payer_document_number` * | string | Payer's document number (CPF/CNPJ). | | `beneficiary_name` * | string | Beneficiary's name. | | `beneficiary_trading_name` | string | Beneficiary's trade name. | | `beneficiary_document_number` * | string | Beneficiary's document number (CPF/CNPJ). | | `beneficiary_bank_ispb` * | string | ISPB code of the beneficiary's bank. | | `guarantor_name` | string | Name of the guarantor. | | `guarantor_document_number` | string | Guarantor's document number (CPF/CNPJ). | | `expiration_date` * | string | Due date. | | `max_payment_date` * | string | Maximum payment date. | | `partial_payment_indicator` * | [enum](#enumeradores-partial_payment_indicator) | Partial payment indicator. | | `registered_payment_amount` | string | Total registered payment amount. | | `nominal_amount` * | number | Original amount. | | `total_amount` * | number | Total amount. | | `rebate_amount` * | number | Rebate amount. | | `discount_amount` * | number | Discount amount. | | `fine_amount` * | number | Fine amount. | | `interest_amount` * | number | Interest amount. | ### Enumerators partial_payment_indicator | Enumerator | Description | |----------------|---------------------------| | `allowed` | Allowed | | `not_allowed` | Not allowed | ### Object collection_slip | Field | Type | Description | |--------------------------------|-----------|---------------------------------------------------------------------------| | `barcode` | string | Barcode. | | `digitable_line` | string | Digitable line. | | `collection_name` * | string | Name of the agreement. | | `collection_document_number` * | string | Document number of the agreement (CPF/CNPJ). | | `expiration_date` * | string | Due date. | | `total_amount` * | number | Total amount. | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Description em português", "code": "Código" } ``` | HTTP Code | QI Code | Title | Description (eng) | Description (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 | --- # Check scheduling URL: /en/documentation/baas/cobranca/agendamento/consultar_agendamento This endpoint is used to query information about a scheduled payment of a Boleto or Collection Invoice. :::info Boleto This is the conventional boleto (with digitable lines not starting with the digit 8). It is registered with the Interbank Payment Clearinghouse (CIP/Núclea) and can be paid at financial institutions and payment institutions authorized to operate by the Central Bank. ::: :::info Collection Invoice This type of charge is issued by utility companies (water, electricity, telephone, and gas bills) and public entities (taxes). They are not registered with the Interbank Payment Clearinghouse (CIP/Núclea) and, therefore, do not return the same information as a boleto. ::: ## Request ENDPOINT /account/ ACCOUNT_KEY /payment_schedule/ PAYMENT_SCHEDULE_KEY METHOD GET ### Request Path Params | Field | Type | Description | Characters | |-------------------------|--------|-----------------------------------------------|------------| | `account_key` * | uuidv4 | Unique account identification key. | 36 | | `payment_schedule_key` *| uuidv4 | Unique schedule identification key. | 36 | ## Response ### Success Response STATUS 200 Response Body: Scheduled payment of boleto ```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: Scheduled payment of collection invoice ```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 | Field | Type | Description | |----------------------|--------|---------------------------------------------------| | `payment_key` * | uuid4 | Unique payment identification key. | | `request_control_key` *| uuid4 | Unique identification key for the client's request.| | `payer_name` * | string | Name of the effective payer. | | `payer_document_number` *| string | Document number of the effective payer (CPF/CNPJ).| | `source_account_key` *| uuid4 | Key of the debited account. | | `transaction_key` * | uuid4 | Payment transaction key. | | `transaction_revert_key` | uuid4 | Payment reversal transaction key. | | `paid_amount` * | number | Amount effectively paid. | | `payment_date` * | string | Scheduling date. | | `payment_type` * | [enum](#enumerators-payment_type) | Payment type. | | `bank_slip` | [object](#object-bank_slip) | Boleto. | | `collection_slip` | object | Collection invoice. | | `payment_schedule_status` * | [enum](#enumerators-payment_schedule_status) | Schedule status. | ### Enumerators payment_type | Enumerator | Type | Description | |---------------------|--------|---------------------------| | `bank_slip` | string | Boleto | | `collection_slip` | string | Collection invoice | ### Enumerators payment_schedule_status | Enumerator | Description | |-------------------------|-------------------------------------------------------------------------------------------| | `pending_2fa_approval` | Schedule pending two-factor authentication (2FA) | | `scheduled` | Payment successfully scheduled | | `executed` | The payment related to the schedule was successfully executed | | `rejected` | The payment related to the schedule was rejected | | `canceled` | Schedule canceled | | `error` | Error during scheduling | ### Object bank_slip | Field | Type | Description | |--------------------------------|-----------|-----------------------------------------------------------------------------| | `barcode` * | string | Barcode. | | `digitable_line` * | string | Digitable line. | | `payer_name` * | string | Payer's name. | | `payer_document_number` * | string | Payer's document number (CPF/CNPJ). | | `beneficiary_name` * | string | Beneficiary's name. | | `beneficiary_trading_name` | string | Beneficiary's trade name. | | `beneficiary_document_number` * | string | Beneficiary's document number (CPF/CNPJ). | | `beneficiary_bank_ispb` * | string | ISPB code of the beneficiary's bank. | | `guarantor_name` | string | Name of the guarantor. | | `guarantor_document_number` | string | Guarantor's document number (CPF/CNPJ). | | `expiration_date` * | string | Due date. | | `max_payment_date` * | string | Maximum payment date. | | `partial_payment_indicator` * | [enum](#enumerators-partial_payment_indicator) | Partial payment indicator. | | `registered_payment_amount` | string | Total registered payment amount. | | `nominal_amount` * | number | Original amount. | | `total_amount` * | number | Total amount. | | `rebate_amount` * | number | Rebate amount. | | `discount_amount` * | number | Discount amount. | | `fine_amount` * | number | Fine amount. | | `interest_amount` * | number | Interest amount. | ### Enumerators partial_payment_indicator | Enumerator | Description | |--------------- |-----------------------| | `allowed` | Allowed | | `not_allowed` | Not allowed | ### Object collection_slip | Field | Type | Description | |--------------------------------|-----------|-----------------------------------------------------------------------------| | `barcode` | string | Barcode. | | `digitable_line` | string | Digitable line. | | `collection_name` * | string | Name of the agreement. | | `collection_document_number` | string | Document number of the agreement (CPF/CNPJ). | | `expiration_date` * | string | Due date. | | `total_amount` * | number | Total amount. | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Description em português", "code": "Código" } ``` | HTTP Code | QI Code | Title | Description (eng) | Description (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 | --- # List schedules URL: /en/documentation/baas/cobranca/agendamento/listar_agendamentos This endpoint aims to provide details of all schedules made by the integration partner, including boletos and collection invoices. :::info Boleto This is the conventional boleto (with digitable lines not starting with the digit 8). It is registered with the Interbank Payment Clearinghouse (CIP/Núclea) and can be paid at financial institutions and payment institutions authorized to operate by the Central Bank. ::: :::info Collection Invoice This type of charge is issued by utility companies (water, electricity, telephone, and gas bills) and public entities (taxes). They are not registered with the Interbank Payment Clearinghouse (CIP/Núclea) and, therefore, do not return the same information as a boleto. ::: ## Request ENDPOINT /account/ ACCOUNT_KEY /payment_schedules MÉTODO GET ### Request Path Params | Field | Type | Description | Characters | |----------------|--------|-------------------------------------------|------------| | `account_key` *| uuidv4 | Unique account identification key. | 36 | ### Request Query String Params | Field | Type | Description | |------------------------|-----------|--------------------------------------------------------------------| | `request_control_key` | uuidv4 | Unique identification key for the client's request. | | `payment_schedule_key` | uuidv4 | Unique schedule identification key. | | `payment_type` | [enum](#enumerators-payment_type) | Payment type. | | `date_from` | string | Start date. Format "YYYY-MM-DD". | | `date_to` | string | End date. Format "YYYY-MM-DD". | | `page` | string | Requested page number. 1 by default. | | `page_size` | string | Requested page size in the query. 30 by default and maximum value. | ### Enumerators payment_type | Enumerator | Type | Description | |-------------------|--------|---------------------------| | `bank_slip` | string | Boleto | | `collection_slip` | string | Collection invoice | ## Response ### Success Response STATUS 200 Response Body: Payment query ```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 | Field | Type | Description | |----------------------|--------|---------------------------------------------------| | `payment_key` * | uuid4 | Unique payment identification key. | | `request_control_key` *| uuid4 | Unique identification key for the client's request.| | `payer_name` * | string | Name of the effective payer. | | `payer_document_number` *| string | Document number of the effective payer (CPF/CNPJ).| | `source_account_key` *| uuid4 | Key of the debited account. | | `paid_amount` * | number | Amount effectively paid. | | `payment_date` * | string | Payment date. | | `payment_type` * | [enum](#enumerators-payment_type-1) | Payment type. | | `bank_slip` | [object](#object-bank_slip) | Boleto. | | `collection_slip` | [object](#object-collection_slip) | Collection invoice. | | `payment_schedule_status` * | [enum](#enumerators-payment_schedule_status) | Schedule status. | ### Enumerators payment_type | Enumerator | Type | Description | |---------------------|--------|-------------------------------| | `bank_slip` | string | Boleto | | `collection_slip` | string | Collection invoice | ### Enumerators payment_schedule_status | Enumerator | Description | |-------------------------|------------------------------------------------------------------------| | `pending_2fa_approval` | Schedule pending two-factor authentication (2FA) | | `scheduled` | Payment successfully scheduled | | `executed` | The payment related to the schedule was successfully executed | | `rejected` | The payment related to the schedule was rejected | | `canceled` | Schedule canceled | | `error` | Error during scheduling | ### Object bank_slip | Field | Type | Description | |--------------------------------|-----------|-----------------------------------------------------------------------------| | `barcode` * | string | Barcode. | | `digitable_line` * | string | Digitable line. | | `payer_name` * | string | Payer's name. | | `payer_document_number` * | string | Payer's document number (CPF/CNPJ). | | `beneficiary_name` * | string | Beneficiary's name. | | `beneficiary_trading_name` | string | Beneficiary's trade name. | | `beneficiary_document_number` * | string | Beneficiary's document number (CPF/CNPJ). | | `beneficiary_bank_ispb` * | string | ISPB code of the beneficiary's bank. | | `guarantor_name` | string | Name of the guarantor. | | `guarantor_document_number` | string | Guarantor's document number (CPF/CNPJ). | | `expiration_date` * | string | Due date. | | `max_payment_date` * | string | Maximum payment date. | | `partial_payment_indicator` * | [enum](#enumerators-partial_payment_indicator) | Partial payment indicator. | | `registered_payment_amount` | string | Total registered payment amount. | | `nominal_amount` * | number | Original amount. | | `total_amount` * | number | Total amount. | | `rebate_amount` * | number | Rebate amount. | | `discount_amount` * | number | Discount amount. | | `fine_amount` * | number | Fine amount. | | `interest_amount` * | number | Interest amount. | ### Enumerators partial_payment_indicator | Enumerator | Type | Description | |----------------|--------|---------------------------| | `allowed` | string | Allowed | | `not_allowed` | string | Not allowed | ### Object collection_slip | Field | Type | Description | |--------------------------------|-----------|------------------------------------| | `barcode` * | string | Barcode. | | `digitable_line` * | string | Digitable line. | | `collection_name` * | string | Name of the agreement. | | `collection_document_number` * | string | Document number of the agreement (CPF/CNPJ). | | `expiration_date` * | string | Due date. | | `total_amount` * | number | Total amount. | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Description in portuguese", "code": "Código" } ``` | HTTP Code| QI Code | Title | Description (eng) | Description (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. | --- # Request batch scheduling of bank slip payments URL: /en/documentation/baas/cobranca/agendamento/solicitar_agendamento_em_lote_de_boleto_bancario This endpoint allows you to **schedule multiple bank slips in a single request**. :::info Bank slip This is the conventional bank slip (digitable lines not starting with the digit 8). It is registered with the Interbank Payment Clearinghouse (CIP/Núclea) and can be paid at financial institutions and payment institutions authorized to operate by the Central Bank. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments_schedule/batch_bank_slip METHOD POST ### Request Path Params | Field | Type | Description | Characters | |---------------------|---------|-------------------------------------------|------------| | `account_key` * | uuid4 | Unique account identification key. | 36 | Request Body: Batch scheduling of bank slips ```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 | Field | Type | Description | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Unique client request key (batch). | | `bank_slip_payment_schedules` * | array | List of bank slip schedules. **1000** items maximum per request. | Each element of `bank_slip_payment_schedules` must contain: | Field | Type | Description | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Unique client request key for that batch item. | | `barcode` | string | Barcode. | | `digitable_line` | string | Digitable line. | | `payment_amount` * | number | Amount to pay. | | `payment_date` * | string | Scheduled payment date for the item. | :::danger Warning For each item, `payment_amount` must follow the rules for the title returned in the bank slip inquiry. If partial payment is not allowed, the amount must match the updated total of the title. ::: ## Response ### Success Response STATUS 202 Response Body: Batch schedule created ```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 | Field | Type | Description | |---------------------|---------|-----------------------------------| | `batch_payment_schedule_key` * | uuid4 | Unique batch schedule key. | | `request_control_key` * | uuid4 | Unique client request key (batch). | | `account_key` * | uuid4 | Debited account key. | | `total_amount` * | number | Sum of item `payment_amount` values in the batch. | | `batch_payment_schedule_status` * | [enum](#enumeradores-batch_payment_schedule_status) | Batch schedule status after the request. | | `payment_type` * | [enum](#enumeradores-payment_type) | Payment type. | ### Enumeradores batch_payment_schedule_status | Value | Description | |---------------|---------------| | `pending_2fa_approval` | Pending 2FA approval | | `scheduled` | Scheduled | | `rejected` | Rejected | | `error` | Scheduling error | ### Enumeradores payment_type | Value | Type | Description | |---------------|-----------|---------------| | `bank_slip` | string | Bank slip | | `collection_slip` | string | Collection slip | :::danger Warning The `collection_slip` value does not apply to this bank slip batch scheduling endpoint; for this flow, `payment_type` must be `bank_slip`. ::: ### Error Response STATUS 4XX Response Body ```json { "title": "Title", "description": "Description in english", "translation": "Portuguese description", "code": "Code" } ``` | HTTP code | QI code | Title | Description (eng) | Description (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. | --- # Request batch scheduling of collection slip payments URL: /en/documentation/baas/cobranca/agendamento/solicitar_agendamento_em_lote_de_fatura_de_recolhimento This endpoint allows you to **schedule multiple collection slips (utility/tax) in a single request**. :::info Collection slip This charge type is issued by utility companies (water, electricity, phone, gas) and public agencies (taxes). They are not registered with the Interbank Payment Clearinghouse (CIP/Núclea), so they do not return the same information as a bank slip. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments_schedule/batch_collection_slip METHOD POST ### Request Path Params | Field | Type | Description | Characters | |---------------------|---------|-------------------------------------------|------------| | `account_key` * | uuid4 | Unique account identification key. | 36 | Request Body: Batch scheduling of collection slips ```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 | Field | Type | Description | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Unique client request key (batch). | | `collection_slip_payment_schedules` * | array | List of collection slip schedules. **1000** items maximum per request. | Each element of `collection_slip_payment_schedules` must contain: | Field | Type | Description | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Unique client request key for that batch item. | | `barcode` | string | Barcode. | | `digitable_line` | string | Digitable line. | | `payment_amount` * | number | Amount to pay. | | `payment_date` * | string | Scheduled payment date for the item. | ## Response ### Success Response STATUS 202 Response Body: Batch schedule created ```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 | Field | Type | Description | |---------------------|---------|-----------------------------------| | `batch_payment_schedule_key` * | uuid4 | Unique batch schedule key. | | `request_control_key` * | uuid4 | Unique client request key (batch). | | `account_key` * | uuid4 | Debited account key. | | `total_amount` * | number | Sum of item `payment_amount` values in the batch. | | `batch_payment_schedule_status` * | [enum](#enumeradores-batch_payment_schedule_status) | Batch schedule status after the request. | | `payment_type` * | [enum](#enumeradores-payment_type) | Payment type. | ### Enumeradores batch_payment_schedule_status | Value | Description | |---------------|---------------| | `pending_2fa_approval` | Pending 2FA approval | | `scheduled` | Scheduled | | `rejected` | Rejected | | `error` | Scheduling error | ### Enumeradores payment_type | Value | Type | Description | |---------------|-----------|---------------| | `bank_slip` | string | Bank slip | | `collection_slip` | string | Collection slip | :::danger Warning The `bank_slip` value does not apply to this collection slip batch scheduling endpoint; for this flow, `payment_type` must be `collection_slip`. ::: ### Error Response STATUS 4XX Response Body ```json { "title": "Title", "description": "Description in english", "translation": "Portuguese description", "code": "Code" } ``` | HTTP code | QI code | Title | Description (eng) | Description (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: /en/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: /en/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. | --- # Consult boleto URL: /en/documentation/baas/cobranca/consultar_boleto_bancario This endpoint is used to query information about a boleto. :::info Boleto This is the conventional boleto (with digitable lines not starting with the digit 8). It is registered with the Interbank Payment Clearinghouse (CIP/Núclea) and can be paid at financial institutions and payment institutions authorized to operate by the Central Bank. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/bank_slip/ DIGITABLE_LINE or BARCODE MÉTODO GET ### Request Path Params | Field | Type | Description | Characters | |---------------------|---------|-----------------------------------|------------| | `digitable_line` | string | Digitable line to be queried. | 47 | | `barcode` | string | Barcode to be queried. | 44 | ## Response ### Success Response STATUS 200 Response Body: Boleto available for payment ```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 | Field | Type | Description | |---------------------|---------|-----------------------------------| | `barcode` * | string | Barcode. | | `digitable_line` * | string | Digitable line. | | `payer_name` * | string | Payer's name.| | `payer_document_number` * | string | Payer's document number (CPF/CNPJ). | | `beneficiary_name` * | string | Beneficiary's name. | | `beneficiary_trading_name` | string | Beneficiary's trade name. | | `beneficiary_document_number` * | string | Beneficiary's document number (CPF/CNPJ). | | `beneficiary_bank_ispb` * | string | ISPB code of the beneficiary's bank. | | `guarantor_name` | string | Name of the guarantor. | | `guarantor_document_number` | string | Guarantor's document number (CPF/CNPJ). | | `expiration_date` * | string | Due date. | | `max_payment_date` * | string | Maximum payment date. | | `partial_payment_indicator` * | [enum](#enumerators-partial_payment_indicator) | Partial payment indicator | | `registered_payment_amount` | string | Total registered payment amount. | | `nominal_amount` * | number | Original amount. | | `total_amount` * | number | Total amount. | | `rebate_amount` * | number | Rebate amount. | | `discount_amount` * | number | Discount amount. | | `fine_amount` * | number | Fine amount. | | `interest_amount` * | number | Interest amount. | ### Enumerators partial_payment_indicator | Enumerator | Type | Description | |---------------|-----------|---------------| | `allowed` | string | Allowed | | `not_allowed` | string | Not allowed | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Description in portuguese", "code": "Código" } ``` | HTTP Code | QI Code | Title | Description (eng) | Description (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 boleto was not found. | O boleto não foi encontrado. | | 400 | BIP000005 | Bad Request | It was not possible to consult the boleto 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 | Boleto already written off | Boleto já baixado | | 400 | BIP000007 | Bad Request | Boleto blocked for payment | Boleto bloqueado para pagamento | | 400 | BIP000008 | Bad Request | Boleto already paid | Boleto já pago | | 400 | BIP000009 | Bad Request | Invalid boleto. Please consult issuing bank | Boleto inválido. Favor consultar banco emissor | ## Sandbox Environment In our sandbox environment, we provide mocked digitable lines for simulating successful payments and testing error scenarios. ### Success Scenarios | Digitable Line | |---| | 00190000090361557400500000024174396700000991000 | | 00190000090282802601919212747174596760001294161 | | 23793390014000000455277000249001596900000103995 | | 75691434020137513680900001040013196770002417240 | | 21390001171200000570700168167484796770000148206 | ### Error Scenarios | Digitable Line | Error Code | |---|---| | 34191090083273252027893634770007296690012513600 | BIP000007 | | 07090010287045349010776686070590896770001160123 | BIP000007 | | 42297048060005815702500130494123896770000239491 | BIP000006 | | 74891123702849020818918378871083196690000050000 | BIP000009 | | 23792374119000209350986000372408496610000122810 | BIP000008 | --- # Consult collection invoice (agreement/tribute) URL: /en/documentation/baas/cobranca/consultar_fatura_de_recolhimento This endpoint is used to query information about a collection invoice. :::info Collection Invoice This type of charge is issued by utility companies (water, electricity, telephone, and gas bills) and public entities (taxes). They are not registered with the Interbank Payment Clearinghouse (CIP/Núclea) and, therefore, do not return the same information as a boleto. ::: ## Request ### Request Endpoint ENDPOINT /bill_payment/collection_slip/ DIGITABLE_LINE or BARCODE MÉTODO GET ### Request Path Params | Field | Type | Description | Characters | |---------------------|---------|-----------------------------------|------------| | `digitable_line` | string | Digitable line to be queried. | 48 | | `barcode` | string | Barcode to be queried. | 44 | ## Response ### Success Response STATUS 200 Response Body: Collection invoice available for payment ```json { "barcode": null, "digitable_line": "836200000138892100450006762142420244046000010192", "collection_name": "CIA ULTRAGAZ SA-COD", "expiration_date": "2024-04-15", "total_amount": 1389.21 } ``` ### Response Body Params | Field | Type | Description | |---------------------|---------|-----------------------------------| | `barcode` | string | Barcode. | | `digitable_line` | string | Digitable line. | | `collection_name` * | string | Name of the agreement. | | `expiration_date` * | string | Due date. | | `total_amount` * | number | Total amount. | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Description in portuguese", "code": "Código" } ``` | HTTP Code | QI Code | Title | Description (eng) | Description (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. | ## Sandbox Environment In our sandbox environment, we provide mocked digitable lines for simulating successful payments and testing error scenarios. ### Success Scenarios | Digitable Line | |---| | 828300000007411100972013905080001546763201900028 | | 838000000009235700481007241345219112001474229880 | | 848000000006308600802021201071261517689002201070 | | 858200000015000000643025703477209504800448091020 | ### Error Scenarios | Digitable Line | Error Code | |---|---| | 858500000037350000643217212883260006147448091022 | BIP000035 | --- # Consultar lote de pagamento URL: /en/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: /en/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. | --- # List payments URL: /en/documentation/baas/cobranca/listar_pagamentos This endpoint aims to provide details of all charges paid by the client, including boletos and collection invoices. :::info Boleto This is the conventional boleto (with digitable lines not starting with the digit 8). It is registered with the Interbank Payment Clearinghouse (CIP/Núclea) and can be paid at financial institutions and payment institutions authorized to operate by the Central Bank. ::: :::info Collection Invoice This type of charge is issued by utility companies (water, electricity, telephone, and gas bills) and public entities (taxes). They are not registered with the Interbank Payment Clearinghouse (CIP/Núclea) and, therefore, do not return the same information as a boleto. ::: ## 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 | Field | Type | Description | |---------------------|-------------|-----------------------------------| | `request_control_key` | uuid4 | Unique identification key for the client's request. | | `payment_key` | uuid4 | Unique payment identification key. | | `payment_type` | [enum](#enumerators-payment_type) | Payment type. | | `date_from` | string | Start date. Format "YYYY-MM-DD". | | `date_to` | string | End date. Format "YYYY-MM-DD". | | `page` | string | Requested page number. 1 by default. | | `page_size` | string | Requested page size in the query. 30 by default and maximum value. | ### Enumerators payment_type | Enumerator | Type | Description | |---------------|-----------|---------------| | `bank_slip` | string | Boleto | | `collection_slip` | string | Collection invoice | ## Response ### Success Response STATUS 200 Response Body: Payment query ```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 | Field | Type | Description | |---------------------|---------|-----------------------------------| | `payment_key` * | uuid4 | Unique payment identification key. | | `request_control_key` * | uuid4 | Unique identification key for the client's request. | | `payer_name` * | string | Name of the effective payer.| | `payer_document_number` * | string | Document number of the effective payer (CPF/CNPJ). | | `source_account_key` * | uuid4 | Key of the debited account. | | `transaction_key` * | uuid4 | Payment transaction key. | | `transaction_revert_key` | uuid4 | Payment reversal transaction key. | | `paid_amount` * | number | Amount effectively paid. | | `payment_date` * | string | Payment date. | | `payment_type` * | [enum](#enumerators-payment_type-1) | Payment type. | | `bank_slip` | [object](#object-bank_slip) | Boleto. | | `collection_slip` | [object](#object-collection_slip) | Collection invoice. | | `payment_status` * | [enum](#enumerators-payment_status) | Payment status. | ### Enumerators payment_type | Enumerator | Description | |---------------|---------------| | `bank_slip` | Boleto | | `collection_slip` | Collection invoice | ### Enumerators payment_status | Enumerator | Description | |---------------|---------------| | `pending_execution` | Pending execution | | `executed` | Executed | | `reverted` | Reverted | | `rejected` | Rejected | | `error` | Error | ### Object bank_slip | Field | Type | Description | |-----------------------------------|---------|-----------------------------------| | `barcode` * | string | Barcode. | | `digitable_line` * | string | Digitable line. | | `payer_name` * | string | Payer's name.| | `payer_document_number` * | string | Payer's document number (CPF/CNPJ). | | `beneficiary_name` * | string | Beneficiary's name. | | `beneficiary_trading_name` | string | Beneficiary's trade name. | | `beneficiary_document_number` * | string | Beneficiary's document number (CPF/CNPJ). | | `beneficiary_bank_ispb` * | string | ISPB code of the beneficiary's bank. | | `guarantor_name` | string | Name of the guarantor. | | `guarantor_document_number` | string | Guarantor's document number (CPF/CNPJ). | | `expiration_date` * | string | Due date. | | `max_payment_date` * | string | Maximum payment date. | | `partial_payment_indicator` * | [enum](#enumerators-partial_payment_indicator) | Partial payment indicator. | | `registered_payment_amount` | string | Total registered payment amount. | | `nominal_amount` * | number | Original amount. | | `total_amount` * | number | Total amount. | | `rebate_amount` * | number | Rebate amount. | | `discount_amount` * | number | Discount amount. | | `fine_amount` * | number | Fine amount. | | `interest_amount` * | number | Interest amount. | ### Enumerators partial_payment_indicator | Enumerator | Description | |---------------|---------------| | `allowed` | Allowed | | `not_allowed` | Not allowed | ### Object collection_slip | Field | Type | Description | |-----------------------------------|---------|-----------------------------------| | `barcode` * | string | Barcode. | | `digitable_line` * | string | Digitable line. | | `collection_name` * | string | Name of the agreement.| | `collection_document_number` * | string | Document number of the agreement (CPF/CNPJ). | | `expiration_date` * | string | Due date. | | `total_amount` * | number | Total amount. | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Description in portuguese", "code": "Código" } ``` | HTTP Code | QI Code | Title | Description (eng) | Description (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. | --- # Make payment of Boleto URL: /en/documentation/baas/cobranca/pagar_boleto_bancario This endpoint allows the payment of bank slips (boletos). The payment should be made after a consultation, using the returned information to ensure the correct flow, avoiding failures during the payment process. :::info Bank Slip This is the conventional bank slip (with digitable lines not starting with the digit 8). It is registered with the Interbank Payment Clearinghouse (CIP/Núclea) and can be paid at financial institutions and payment institutions authorized to operate by the Central Bank. ::: ## Request ### Request Endpoint ENDPOINT /account/ ACCOUNT_KEY /payment/bank_slip MÉTODO POST ### Request Path Params | Field | Type | Description | Characters | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Unique account identification key. | 36 | Request Body: Payment of boleto with digitable line ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "digitable_line": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8 } ``` Request Body: Payment of boleto with barcode ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "barcode": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8 } ``` ### Body Params | Field | Type | Description | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Unique identification key for the client's request. | | `barcode` | string | Barcode. | | `digitable_line` | string | Digitable line. | | `payment_amount` * | number | Amount to be paid. | :::danger Warning The `payment_amount` must always be equal to the `total_amount` returned in the bank slip query if partial payment is not allowed for the bank slip. For titles where partial payment is allowed, the client can choose the `payment_amount`, as long as its sum with the bank slip's `registered_payment_amount` does not exceed the `total_amount`. ::: ## Response ### Success Response STATUS 201 Response Body: Payment executed ```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: Payment pending execution ```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 Information If **HTTP Status 202** is returned with the field `payment_status` having the value **pending_execution**, the payment should not be retried. This payment will be processed asynchronously. It is necessary to check the transfer status through the payment query, or wait for the pending payment webhook described on the [webhooks page](/documentation/baas_v2/cobranca/webhooks). ::: ### Response Body Params | Field | Type | Description | |---------------------|---------|-----------------------------------| | `payment_key` * | uuid4 | Unique payment identification key. | | `request_control_key` * | uuid4 | Unique identification key for the client's request. | | `payer_name` * | string | Name of the effective payer. | | `payer_document_number` * | string | Document number of the effective payer (CPF/CNPJ). | | `source_account_key` * | uuid4 | Key of the debited account. | | `transaction_key` * | uuid4 | Payment transaction key. | | `transaction_revert_key` | uuid4 | Payment reversal transaction key. | | `paid_amount` * | number | Amount effectively paid. | | `payment_date` * | string | Payment date. | | `payment_type` * | [enum](#enumerators-payment_type) | Payment type. | | `bank_slip` | [object](#object-bank_slip) | Bank slip. | | `collection_slip` | object | Collection invoice. | | `payment_status` * | [enum](#enumerators-payment_status) | Payment status. | ### Enumerators payment_type | Enumerator | Type | Description | |---------------|-----------|---------------| | `bank_slip` | string | Bank slip | | `collection_slip` | string | Collection invoice | :::danger Warning The enumerator `collection_slip` does not apply to the bank slip flow, and the collection_slip object will always be null. ::: ### Enumerators payment_status | Enumerator | Description | |---------------|---------------| | `pending_execution` | Pending execution | | `executed` | Executed | | `reverted` | Reverted | | `rejected` | Rejected | | `error` | Error | :::danger Warning For payments where QI does not receive a response from CIP within two minutes, the payment will be returned with the status `pending_execution`. After QI receives the response from CIP, the pending payment webhook described on the [webhooks page](/documentation/baas_v2/cobranca/webhooks) will be sent to the client. ::: ### Object bank_slip | Field | Type | Description | |-----------------------------------|---------|-----------------------------------| | `barcode` * | string | Barcode. | | `digitable_line` * | string | Digitable line. | | `payer_name` * | string | Payer's name.| | `payer_document_number` * | string | Payer's document number (CPF/CNPJ). | | `beneficiary_name` * | string | Beneficiary's name. | | `beneficiary_trading_name` | string | Beneficiary's trade name. | | `beneficiary_document_number` * | string | Beneficiary's document number (CPF/CNPJ). | | `beneficiary_bank_ispb` * | string | ISPB code of the beneficiary's bank. | | `guarantor_name` | string | Name of the guarantor. | | `guarantor_document_number` | string | Guarantor's document number (CPF/CNPJ). | | `expiration_date` * | string | Due date. | | `max_payment_date` * | string | Maximum payment date. | | `partial_payment_indicator` * | [enum](#enumerators-partial_payment_indicator) | Partial payment indicator. | | `registered_payment_amount` | string | Total registered payment amount. | | `nominal_amount` * | number | Original amount. | | `total_amount` * | number | Total amount. | | `rebate_amount` * | number | Rebate amount. | | `discount_amount` * | number | Discount amount. | | `fine_amount` * | number | Fine amount. | | `interest_amount` * | number | Interest amount. | ### Enumerators partial_payment_indicator | Enumerator | Type | Description | |---------------|-----------|---------------| | `allowed` | string | Allowed | | `not_allowed` | string | Not allowed | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Description in portuguese", "code": "Código" } ``` | HTTP Code | QI Code | Title | Description (eng) | Description (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. | ## Sandbox Environment In our sandbox environment, we provide mocked digitable lines for simulating successful payments and testing error scenarios. ### Success scenarios | Digitable line | |---| | 00190000090361557400500000024174396700000991000 | | 00190000090282802601919212747174596760001294161 | | 23793390014000000455277000249001596900000103995 | | 75691434020137513680900001040013196770002417240 | | 21390001171200000570700168167484796770000148206 | ### `pending_execution` scenarios The simulation of this scenario is better described on the [simulation page](/documentation/baas_v2/cobranca/simulacao). | Digitable line | |---| | 75691333790100505390300569460017397220000306867 | ### Error scenarios | Digitable line | Error code | |---|---| | 34191090083273252027893634770007296690012513600 | BIP000007 | | 07090010287045349010776686070590896770001160123 | BIP000007 | | 42297048060005815702500130494123896770000239491 | BIP000006 | | 74891123702849020818918378871083196690000050000 | BIP000009 | | 23792374119000209350986000372408496610000122810 | BIP000008 | --- # Make payment of collection invoice (agreement/tribute) URL: /en/documentation/baas/cobranca/pagar_fatura_de_recolhimento This endpoint allows the payment of collection invoices. The payment should be made after a consultation, using the information returned in it, to ensure the correct flow and avoid failures during the payment process. :::info Collection Invoice This type of charge is issued by utility companies (water, electricity, telephone, and gas bills) and public entities (taxes). They are not registered with the Interbank Payment Clearinghouse (CIP/Núclea), and thus, do not return the same information as a bank slip. ::: ## Request ### Request Endpoint ENDPOINT /account/ ACCOUNT_KEY /payment/collection_slip MÉTODO POST ### Request Path Params | Field | Type | Description | Characters | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Unique account identification key. | 36 | Request Body: Payment of collection invoice with digitable line ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "digitable_line": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8 } ``` Request Body: Payment of collection invoice with barcode ```json { "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "barcode": "00190000090361557400500000024174396700000991000", "payment_amount": 1156.8 } ``` ### Body Params | Field | Type | Description | |---------------------|---------------|-----------------------------------| | `request_control_key` * | uuid4 | Unique identification key for the client's request. | | `barcode` | string | Barcode. | | `digitable_line` | string | Digitable line. | | `payment_amount` * | number | Amount to be paid. | :::danger Warning The `payment_amount` must always be equal to the `total_amount` returned in the bank slip query. ::: ## Response ### Success Response STATUS 201 Response Body: Payment executed ```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 When the payment returns status `202`, processing is still in progress. **Do not retry the payment** until you receive the final status update via webhook. ::: Response Body: Pending payment ```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 | Field | Type | Description | |---------------------|---------|-----------------------------------| | `payment_key` * | uuid4 | Unique payment identification key. | | `request_control_key` * | uuid4 | Unique identification key for the client's request. | | `payer_name` * | string | Name of the effective payer.| | `payer_document_number` * | string | Document number of the effective payer (CPF/CNPJ). | | `source_account_key` * | uuid4 | Key of the debited account. | | `transaction_key` * | uuid4 | Payment transaction key. | | `transaction_revert_key` | uuid4 | Payment reversal transaction key. | | `paid_amount` * | number | Amount effectively paid. | | `payment_date` * | string | Payment date. | | `payment_type` * | [enum](#enumerators-payment_type) | Payment type. | | `bank_slip` | object | Bank slip. | | `collection_slip` | [object](#object-collection_slip) | Collection invoice. | | `payment_status` * | [enum](#enumerators-payment_status) | Payment status. | ### Enumerators payment_type | Enumerator | Type | Description | |---------------|-----------|---------------| | `bank_slip` | string | Bank slip | | `collection_slip` | string | Collection invoice | :::danger Warning The enumerator `bank_slip` does not apply to the collection invoice flow, and the bank_slip object will always be null. ::: ### Enumerators payment_status | Enumerator | Description | |---------------|---------------| | `pending` | Pending | | `executed` | Executed | | `reverted` | Reverted | | `rejected` | Rejected | | `error` | Error | ### Object collection_slip | Field | Type | Description | |-----------------------------------|---------|-----------------------------------| | `barcode` | string | Barcode. | | `digitable_line` | string | Digitable line. | | `collection_name` * | string | Name of the agreement.| | `collection_document_number` | string | Document number of the agreement (CPF/CNPJ).| | `expiration_date` * | string | Due date. | | `total_amount` * | number | Total amount. | ### Error Response STATUS 4XX Response Body ```json { "title": "Título", "description": "Description in english", "translation": "Descrição em português", "code": "Código" } ``` | HTTP Code | QI Code | Title | Description (eng) | Description (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. | ## Sandbox Environment In our sandbox environment, we provide mocked digitable lines for simulating successful payments and testing error scenarios. ### Success Scenarios | Digitable Line | |---| | 828300000007411100972013905080001546763201900028 | | 838000000009235700481007241345219112001474229880 | | 848000000006308600802021201071261517689002201070 | | 858200000015000000643025703477209504800448091020 | ### Error Scenarios | Digitable Line | Error Code | |---|---| | 858500000037350000643217212883260006147448091022 | BIP000035 | --- # Scenario Simulation URL: /en/documentation/baas/cobranca/simulacao_de_cenarios ## 1 - Simulating Payment in Pending Execution State For payments where QI does not receive a response from CIP within two minutes, the payment will be returned with the status `pending_execution`. After QI receives the response from CIP, the pending payment webhook described on the [webhooks page](/documentation/baas/cobranca/webhooks) will be sent to the client. To simulate this scenario, make a payment with the digitable line `"digitable_line": "75691333790100505390300569460017397220000306867"`. To update the payment status, make the request below with `payment_status` as **approved** to approve the payment, or **rejected** to reject it. ## Request ### Request Endpoint ENDPOINT /mock/account/ ACCOUNT_KEY /payment/ PAYMENT_KEY /bank_slip/confirmation MÉTODO PATCH ### Request Path Params | Field | Type | Description | Characters | |---------------------|---------|-----------------------------------------|------------| | `account_key` * | uuid4 | Unique account identification key. | 36 | | `payment_key` * | uuid4 | Unique payment identification key. | 36 | Request Body: Simulating payment confirmation ```json { "payment_status": "approved", } ``` ### Body Parameters | Field | Type | Description | |-----------------------------|--------|-----------------------------------------------------------------------| | `payment_status` * | [enum](#enumerators-payment_status) | Payment status | ### Enumerators payment_status | Enumerator | Description | |--------------|-----------| | `approved` | Approve and complete the payment | | `rejected` | Reject and revert the payment | ## Response ### Success Response STATUS 204 Response Body: Simulation completed ```json {} ``` --- # Solicitar Pagamento em Lote de Boleto Bancário URL: /en/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: /en/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: /en/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: /en/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: /en/documentation/baas/cobranca/webhooks :::danger Warning! QI Tech webhooks should not be mapped in a restrictive manner. Additional fields may be included in the payloads of the webhooks returned by our APIs. ::: ## Webhook for Pending Payments Webhook intended to update the status of payments that were pending (status 202) when making a boleto payment. ### Webhook Request Body Request Body: Payment executed ```json { "webhook_type": "baas.bill_payment.payment", "webhook_datetime": "2021-10-22T20:30:23.459Z", "data": { "payment_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "barcode":"00193967000009910000000003615574000000002417", "digitable_line":"00190000090361557400500000024174396700000991000", "payment_status": "executed", "payment_type":"bank_slip" } } ``` Request Body: Payment reverted ```json { "webhook_type": "baas.bill_payment.payment", "webhook_datetime": "2021-10-22T20:30:23.459Z", "data": { "payment_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6", "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec", "barcode":"81620000000000336592028110120200020214942099", "digitable_line":"816200000007000336592027811012020004202149420996", "payment_status": "reverted", "payment_type":"collection_slip" } } ``` ### Webhook Body Params | Field | Type | Description | |-----------------------|--------|-----------------------------------------------------------| | `webhook_type` | string | An enumerator that defines the type of event being reported. | | `webhook_datetime` | string | Date and time the webhook was sent. | | `request_control_key` | uuid4 | Unique identification key for the client's request. | | `payment_key` * | uuid4 | Unique payment identification key. | | `barcode` * | string | Barcode. | | `digitable_line` * | string | Digitable line. | | `payment_type` * | [enum](#enumerators-payment_type) | Payment type. | | `payment_status` * | [enum](#enumerators-payment_status) | Payment status. | ### Enumerators payment_type | Enumerator | Type | Description | |---------------|-----------|---------------| | `bank_slip` | string | Boleto | | `collection_slip` | string | Collection invoice | ### Enumerators payment_status | Enumerator | Type | Description | |---------------|-----------|---------------| | `executed` | string | Executed | | `reverted` | string | Reverted |