Solicitar Agendamento de Transação Pix em Lote

A QI Tech oferece a possibilidade de realizar várias transações agendadas pix com uma única chamada. Nesse sistema os agendamentos são realizados de forma assíncrona. Caso na chamada inicial seja retornado um http status 4xx, nenhum dos agendamentos será realizado. Após a solicitação, o parceiro integrador receberá um webhook para cada **pix_schedule ** rejeitado no ato da criação.

Neste tipo de agendamento, é necessário a confirmação da programação de pagamento via token enviado à pessoa com poderes de aprovação de movimentação na conta credora.

A solicitação de agendamento Pix em lote por parceiros integradores configurados para a utilização de autenticação de dois fatores é realizada de forma similar ao descrito em solicitar agendamento de_transação_pix_em_lote. A diferença ocorre na adição do objeto tfa_info, contento informações sobre o aprovador da transferência e a forma de contato, e o status de uma solicitação bem sucedida que será sempre pending_2fa_approval.

O evento de notificação para o envio de token ao aprovador é baas.token_validation.pix_transfer.schedule.batch. É possível personalizar a mensagem enviada.

Request

ENDPOINT

/account/ACCOUNT_KEY/pix_schedule_batch

MÉTODO

POST

Autenticação via Email e SMS

Request Body: Agendamento em Lote com TFA por SMS ou Email

{
  "request_control_key": "6e4fc980-f8a1-4462-b6e2-d8a49f0ac055",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  },
  "pix_schedules": [
    {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "pix_transfer_type": "key",
      "target_pix_key": "target_pix_key@email.com",
      "transaction_amount": 500.65,
      "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
      "pix_message": "Ola Mundo",
      "schedule_date": "2024-12-01"
    },
    {
      "request_control_key": "c6804f35-101e-4702-8fbc-c2dbc4c2caea",
      "pix_transfer_type": "manual",
      "target_account": {
        "account_branch": "0001",
        "account_digit": "3",
        "account_number": "12345678",
        "owner_document_number": "32402502000135",
        "owner_name": "Qi Tech",
        "account_type": "checking_account",
        "ispb": "32402502"
      },
      "transaction_amount": 500.65,
      "pix_message": "Ola Mundo",
      "schedule_date": "2024-12-01"
    },
    {
      "request_control_key": "a6804f42-101e-4702-8fbc-c2dbc4c2caed",
      "pix_transfer_type": "static_qr_code",
      "transaction_amount": 500.65,
      "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
      "receiver_conciliation_id": "REC00000000000000000000009459463343",
      "target_pix_key": "target_pix_key@email.com",
      "pix_message": "Ola Mundo"
    }
  ]
}

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. Nesse caso, o session_id deve ser obtido na Device Scan e enviado no tfa_info.

Request Body: Agendamento em Lote com TFA por Dispositivo

{
  "request_control_key": "6e4fc980-f8a1-4462-b6e2-d8a49f0ac055",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
    "contact_type": "device"
  },
  "pix_schedules": [
    {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "pix_transfer_type": "key",
      "target_pix_key": "target_pix_key@email.com",
      "transaction_amount": 500.65,
      "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
      "pix_message": "Ola Mundo",
      "schedule_date": "2024-12-01"
    },
    {
      "request_control_key": "c6804f35-101e-4702-8fbc-c2dbc4c2caea",
      "pix_transfer_type": "manual",
      "target_account": {
        "account_branch": "0001",
        "account_digit": "3",
        "account_number": "12345678",
        "owner_document_number": "32402502000135",
        "owner_name": "Qi Tech",
        "account_type": "checking_account",
        "ispb": "32402502"
      },
      "transaction_amount": 500.65,
      "pix_message": "Ola Mundo",
      "schedule_date": "2024-12-01"
    },
    {
      "request_control_key": "a6804f42-101e-4702-8fbc-c2dbc4c2caed",
      "pix_transfer_type": "static_qr_code",
      "transaction_amount": 500.65,
      "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
      "receiver_conciliation_id": "REC00000000000000000000009459463343",
      "target_pix_key": "target_pix_key@email.com",
      "pix_message": "Ola Mundo"
    }
  ]
}

Path Params

Campo	Tipo	Descrição	Caracteres
`account_key`	uuidv4	Chave única de identificação da conta.	36

Body Params

Campo	Tipo	Descrição	Caracteres
`request_control_key` *	uuidv4	Chave única de identificação da request utilizada pelo cliente no formato uuid v4.	36
`pix_schedules` *	array	Lista de objetos pix_schedule vinculados ao lote.	lista de Objeto pix_schedule
`tfa_info`*	Object	Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato.	Objeto tfa_info

Objeto tfa_info

Campo	Tipo	Descrição	Caracteres
`approver_document_number`*	string	Número de documento da pessoa aprovadora da conta.	11
`session_id`	string	Chave única de identificação da sessão do dispositivo no formato UUID v4 (obrigatório para TFA via dispositivo).	36
`contact_type`*	string	Forma de contato com a pessoa aprovadora da conta, podendo ser sms, email ou device

Objeto pix_schedule

Campo	Tipo	Descrição	Caracteres
`request_control_key`*	uuidv4	Chave única de identificação da request utilizada pelo cliente no formato uuid v4.	36
`pix_transfer_type`*	enumerator	Tipo de transferência Pix.	Enumerador pix_transfer_type
`target_pix_key`	string	Chave pix da conta a ser enviada a transação.	100
`receiver_conciliation_id`	string	Identicação de conciliação do recebedor.	35
`target_account` *	Object	Conta destino - Só deve ser enviada em transferências com `pix_transfer_type` do tipo manual.	Objeto target_account
`transaction_amount`*	number	Valor da transferência.	10
`end_to_end_id`	string	Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo). Esta chave é retornada na consulta de chave Pix. Só deve ser enviado se o `pix_transfer_type` for key, static_qr_code ou static_qr_code.	32
`pix_message`	string	Mensagem a ser enviada junto à transferência Pix.	140

Objeto target_account

Campo	Tipo	Descrição	Caracteres
`account_branch` *	string	Agência da conta.	6
`account_digit` *	string	Dígito da conta.	1
`account_number` *	string	Número da conta.	20
`owner_document_number` *	string	CPF ou CNPJ (apenas números) do titular da conta.	14
`owner_name` *	string	Nome do titular da conta.	150
`account_type`*	enumerator	Tipo da conta.	Enumerador account_type
`ispb` *	string	Base no CNPJ da instituição financeira (8 dígitos).	8

Enumerador account_type

Enumerador	Descrição
checking_account	Conta Corrente
salary_account	Conta Salário
saving_account	Conta Poupança
payment_account	Conta de Pagamentos

Enumerador pix_transfer_type

Enumerador	Descrição
manual	Pix utilizando os dados da conta destino. Obrigatório enviar `target_account`
key	Pix utilizando uma chave pix. Obrigatório enviar `target_pix_key`. Recomendado enviar `end_to_end_id` da consulta de chave pix caso tenha sido realizada
static_qr_code	Pix utilizando um QR code estático. Obrigatório enviar o `end_to_end_id` retornado na decodificação do QR code
dynamic_qr_code	Pix utilizando um QR code dinâmico. Obrigatório enviar o `end_to_end_id` retornado na decodificação do QR code

Response

STATUS

202

Response Body: Agendamento em lote Aprovado

{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "schedule_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "schedule_batch_status": "pending_2fa_approval",
  "created_at": "2021-10-22T20:30:23.459Z"
} 

Enumerador schedule_batch_status

Enumerador	Descrição
created	Agendamento em lote criado
approved	Agendamento em lote aprovado
rejected	Agendamento em lote rejeitado
pending_2fa_approval	Agendamento em lote pendente de aprovação por autenticação de dois fatores

STATUS

4xx

Response Body: Error

{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}

Código HTTP `status`	Código QI `code`	Título `title`	Descrição (eng) `description`	Descrição (ptbr) `translation`
400	QIT000001	Bad Request	schema error description	Schema Inválido
404	PSC000001	Account not Found	Account was not found	Conta não encontrada
406	PSC000002	Invalid Uuid	key was not accepted for not being a valid uuid v4 string	key não foi aceito por não ser uma palavra uuid v4 válida
400	PSC000003	Bad Request	pix_message can not be longer than 140 characters	pix_message não pode ser maior que 140 caracteres
400	PSC000004	Bad Request	Emoji not allowed in pix message	Emoji não é permitido na mensagem pix
406	PSC000005	Invalid Transaction Amount	Transaction amount of transaction_amount is not valid. It must be a positive value with at maximum 2 decimal places	O valor de transação transaction_amount não é válido. Deve ser um valor positivo com no máximo duas casas decimais
406	PSC000006	Invalid end_to_end_id	The end_to_end_id sent end_to_end_id is not valid	O end_to_end_id enviado end_to_end_id não é válido
400	PSC000007	Invalid date format	Dates must be sent using format YYYY-MM-DD	Datas devem ser enviadas no formato YYYY-MM-DD
400	PSC000008	Invalid Schedule Date	Schedule date must be after current date for UTC-3	Data de agendamento deve ser após a data atual em UTC-3
400	PSC000009	Account is Closed	Account is closed	Conta está fechada
400	PSC000010	Account is Blocked	Account is blocked	Conta está bloqueada
422	PSC000011	Invalid Account Type	Pix is not yet implemented for non-checking or non-escrow account types	Transações Pix não estão implementadas para conta que não sejam escrow ou livres
403	PSC000012	User is not allowed to do this transaction	User is not allowed to do this transaction	Usuário não tem autorização para fazer essa transação
400	PSC000013	Bad Request	For Manual Pix Transfer Type a target account must be provided	Para transação pix do tipo manual, uma conta destino deve ser fornecida
404	PSC000014	Inquiry Not Found	Pix key inquiry was not found	Pesquisa de chave pix não encontrada
400	PSC000015	Bad Request	Pix key sent does match inquiry pix key. Verify if end_to_end_id sent is correct	Chave Pix enviada não condiz com consulta. Verifique se end_to_end_id enviado está correto
404	PSC000016	Account not found	Nonexistent account in destination financial institution	Conta inexistente na instituição financeira de destino
400	PSC000017	Target Account and Source Account must be different	Target Account must not be the same as Source Account	A conta de destino não pode ser a mesma da conta de origem
409	PSC000018	Bad Request	request_control_key request_control_key already in use	request_control_key request_control_key já utilizada
400	PSC000019	Invalid Target	Account does not have permission to transfer to the given target account	A conta não possui permissão para realizar transferências para a conta enviada
404	PSC000020	Decode Inquiry Not Found	QR Code decode inquiry not found	Pesquisa e decodificação de QR code não encontrada
400	PSC000021	Bad Request	Receiver Conciliation Id sent does match decode inquiry receiver_conciliation_id. Verify if end_to_end_id sent is correct	Identificador de transação enviado não condiz com consulta. Verifique se end_to_end_id enviado está correto
400	PSC000022	Bad Request	Dynamic Instant QR codes cannot be scheduled for payment	Pagamentos de vencimento instantâneo não podem ter pagamento agendado
400	PSC000023	Bad Request	Schedule Date sent is after max payment date for target qr code	Data de agendamento enviada é após a data máxima de pagamento para o qr code enviado
400	PSC000024	Bad Request	Pix transfer type sent does match decode inquiry qr code type. Verify if end_to_end_id sent is correct	Tipo de transação pix enviado enviado não condiz com tipo de qr code da consulta. Verifique se end_to_end_id enviado está correto
400	PSC000040	Empty pix-schedule list received	A list of pix schedules must be provided	Uma lista de agendamentos pix deve ser fornecida
409	PSC000041	Bad Request	One or more request_control_key already in use	Uma ou mais request_control_key já está sendo utilizada
403	PSC000045	Requester not allowed to access this endpoint	Requester has no permission to perform pix transfers on this endpoint	Requester não possui permissão de realizar transações pix através deste endpoint

Request​

Autenticação via Email e SMS​

Autenticação via Dispositivo​

Path Params​

Body Params​

Objeto tfa_info​

Objeto pix_schedule​

Objeto target_account​

Enumerador account_type​

Enumerador pix_transfer_type​

Response​

Enumerador schedule_batch_status​