Validação de token de lote de pagamento de fatura de recolhimento (convênio/tributo)

Este endpoint conclui a etapa de autenticação de dois fatores (2FA) para um lote de faturas de recolhimento que, após a confirmação do lote com tfa_info, encontra-se em batch_status pending_2fa_approval. Com o token validado, o lote segue para processamento assíncrono dos pagamentos, no mesmo sentido da resposta 202 com batch_status: "approved" descrita na confirmação para requesters sem exigência de token nesta etapa. Para solicitar novo envio do token enquanto o lote estiver em pending_2fa_approval, use Reenviar token de confirmação de lote de pagamento de fatura de recolhimento (convênio/tributo).

Fatura de recolhimento

Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta.

Request

Request Endpoint

ENDPOINT

/bill_payment/account/ACCOUNT_KEY/payment/batch_collection_slip/PAYMENT_BATCH_KEY/validate_token

MÉTODO

PATCH

Request Path Params

Campo	Tipo	Descrição	Caracteres
account_key *	uuid4	Chave única de identificação da conta.	36
payment_batch_key *	uuid4	Chave única de identificação do lote (batch_payment_key retornado na criação do lote).	36

Autenticação via Email e SMS

Request Body: Validação de token do lote

{
  "token": "329adf"
}

Autenticação via Dispositivo

Para aprovar e finalizar a autenticação via dispositivo, a requisição deve ser enviada com um payload vazio. A validação ocorre internamente, sem necessidade de informações adicionais no corpo da requisição. Este endpoint só deve ser utilizado após o lote ter entrado em pending_2fa_approval na confirmação do lote.

Request Body: Validação de token do lote

{

}

Body Params

Campo	Tipo	Descrição	Caracteres
token	string	Código de autenticação enviado ao aprovador de movimentações da conta obrigatório para TFA via SMS ou e-mail	6

Response

Success Response

Após a validação bem-sucedida, a API responde com 202 e o lote passa a ser processado de forma assíncrona. O corpo segue o mesmo formato da resposta de lote aprovado para processamento assíncrono na confirmação do lote.

STATUS

202

Response Body: Lote aprovado para processamento assíncrono

{
  "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
  "total_amount": 2778.42,
  "batch_status": "approved",
  "payment_type": "collection_slip"
}

Response Body Params

Campo	Tipo	Descrição
batch_payment_key *	uuid4	Chave única de identificação do pagamento em lote.
request_control_key *	uuid4	Chave única de identificação da requisição do cliente (lote).
account_key *	uuid4	Chave da conta debitada.
total_amount *	number	Soma dos valores dos itens do lote.
batch_status *	string	Após validação do token, espera-se approved enquanto o processamento assíncrono ocorre. Ver ciclo em Solicitar pagamento em lote de fatura de recolhimento — batch_payment_status.
payment_type *	string	Tipo do pagamento; para este fluxo, espera-se collection_slip.

Error Response

STATUS

4XX

Response Body

{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}

Código HTTP	Código QI	Título	Descrição (eng)	Descrição (pt-br)
403	BIP000010	Forbidden	User is not allowed to do this action	Usuário não tem autorização para fazer essa ação
404	BIP000011	Not Found	The source account key was not found.	A chave da conta de origem não foi encontrada.
400	BIP000013	Bad Request	The source account is closed.	A conta de origem está fechada.
400	BIP000050	Bad Request	Requester configuration does not exist	Configuração do requester não existe.
400	BIP000058	Bad Request	Error while validating verification token	Erro ao validar token de verificação
400	BIP000059	Bad Request	Number of verification token validation attempts exceeded.	Número de tentativas de validação de token de verificação excedido.
400	BIP000060	Bad Request	Verification token expired.	Token de verificação expirado.
400	BIP000061	Bad Request	Verification token validation failed.	Falha na validação do token de verificação.
400	BIP000065	Bad Request	Payment verification time window exceeded.	Janela de tempo de verificação de pagamento excedida.
404	BIP000083	Not Found	Batch payment not found by batch payment key.	Lote de pagamentos não encontrado pela chave do lote.
400	BIP000085	Bad Request	Batch payment status is not pending approval.	Status do lote de pagamentos não é de aprovação pendente.
400	BIP000086	Bad Request	A token is required for SMS or email validation.	Um token é necessário para validação via SMS ou email.