Realizar Transação Pix em Lote com Autenticação de Dois Fatores

A QI Tech oferece a possibilidade de realizar várias transações pix com uma única chamada. Nesse sistema as transações são realizadas de forma assíncrona. Caso na chamada inicial seja retornado um http status 4xx, nenhuma das transações será realizada. Após a solicitação, o parceiro integrador receberá um webhook para cada transação informando o status final da tentativa, podendo ser rejected ou sent.

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

A solicitação de transação Pix por parceiros integradores configurados para a utilização de autenticação de dois fatores é realizada de forma similar ao descrito em realizar 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.batch. É possível personalizar a mensagem enviada.

Request

ENDPOINT

/account/ACCOUNT_KEY/pix_transfer_batch

MÉTODO

POST

Request Body

{
  "request_control_key": "6e4fc980-f8a1-4462-b6e2-d8a49f0ac055",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  },
  "pix_transfers": [
    {
      "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"
    },
    {
      "request_control_key": "5fb20e2e-78e3-4ca7-bb36-515640ec2e78",
      "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"
    },
    {
      "request_control_key": "10ad6e08-1a4c-403c-8122-178b0acf1dfa",
      "pix_transfer_type": "static_qr_code",
      "transaction_amount": 500.65,
      "end_to_end_id": "E73856642202309201429bZKfklNlbrb",
      "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_transfers *	array	Lista de objetos pix_transfer vinculados ao lote.	lista de Objeto pix_transfer
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
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

Objeto pix_transfer

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 do pix a ser realizado.	Enumerador pix_transfer_type
target_pix_key	string	Chave pix da conta a ser enviada a transação.	100
target_account	Object	Conta destino - Só deve ser enviada em transferências com pix_transfer_type do tipo manual.	Objeto target_account
receiver_conciliation_id	string	Identicação de conciliação do recebedor.	35
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

201

Response Body: Transferência em Lote Solicitada

{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "pix_transfer_batch_status": "pending_2fa_approval"
}

Enumerador pix_transfer_batch_status

Enumerador	Descrição
approved	Transferência em lote aprovada e transações em processo de execução.
rejected	Transferência em lote rejeitada
pending_2fa_approval	Agendamento em lote pendente de aprovação por autenticação de dois fatores

STATUS

4xx

Response Body: Transferência Rejeitada

{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {
    "pix_transfer_batch_data": {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "pix_transfer_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "pix_transfer_batch_status": "rejected"
    }
  }
}

STATUS

4xx

Response Body: Error

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

Informação

Os erros anteriormente listados para transferência Pix são passiveis de serem retornados por este endpoint além dos erros listados abaixo.

Código HTTP status	Código QI code	Título title	Descrição (eng) description	Descrição (ptbr) translation
400	PXT000168	No approver permission	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	PXT000169	tfa_info is required	Client must send object tfa_info	Cliente deve enviar objeto tfa_info
400	PXT000170	Error occurred while sending token	An unexpected error occurred while sending token	Um erro inexperado ocorreu ao tentar enviar token