Perform batch Pix transaction with Two-Factor Authentication

QI Tech offers the possibility to perform multiple Pix transactions with a single call. In this system, transactions are performed asynchronously. If a http status 4xx is returned on the initial call, none of the transactions will be executed. After the request, the integration partner will receive a webhook for each transaction informing the final status of the attempt, which can be rejected or sent. In this type of transaction, payment confirmation via a token sent to the person with approval powers for movements in the creditor account is required.

The request for a Pix transaction by integration partners configured to use two-factor authentication is made similarly to what is described in perform batch Pix transaction. The difference is the addition of the tfa_info object, containing information about the transfer approver and the means of contact, and the status of a successful request, which will always be pending_2fa_approval.

The notification event for sending the token to the approver is baas.token_validation.pix_transfer.batch. It is possible to customize the sent message.

Request

ENDPOINT

/account/ACCOUNT_KEY/pix_transfer_batch

METHOD

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

Field	Type	Description	Characters
account_key	uuidv4	Unique account identification key.	36

Body Params

Field	Type	Description	Characters
request_control_key *	uuidv4	Unique identification key for the request used by the client in uuid v4 format.	36
pix_transfers *	array	List of pix_transfer objects linked to the batch.	list of Object pix_transfer
tfa_info *	Object	Object containing the document of the account approver and the means of contact.	Object tfa_info

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

Object pix_transfer

Field	Type	Description	Characters
request_control_key *	uuidv4	Unique identification key for the request used by the client in uuid v4 format.	36
pix_transfer_type *	enumerator	Type of the pix to be performed.	Enumerator pix_transfer_type
target_pix_key	string	Pix key of the account to which the transaction will be sent.	100
target_account	Object	Destination account - Should only be sent for transfers with pix_transfer_type of type manual.	Object target_account
receiver_conciliation_id	string	Reconciliation ID of the receiver.	35
transaction_amount *	number	Transfer amount.	10
end_to_end_id	string	Idempotency key for a Pix transaction within the SPI (Instant Payment System). This key is returned in Pix key queries. Should only be sent if pix_transfer_type is key, static_qr_code, or dynamic_qr_code.	32
pix_message	string	Message to be sent along with the Pix transfer.	140

Object target_account

Field	Type	Description	Characters
account_branch *	string	Account branch.	6
account_digit *	string	Account digit.	1
account_number *	string	Account number.	20
owner_document_number *	string	CPF or CNPJ (numbers only) of the account holder.	14
owner_name *	string	Name of the account holder.	150
account_type *	enumerator	Account type.	Enumerator account_type
ispb *	string	Based on the CNPJ of the financial institution (8 digits).	8

Enumerator account_type

Enumerator	Description
checking_account	Checking Account
salary_account	Salary Account
saving_account	Savings Account
payment_account	Payment Account

Enumerator pix_transfer_type

Enumerator	Description
manual	Pix using destination account details. Must send target_account.
key	Pix using a pix key. Must send target_pix_key. Recommended to send end_to_end_id from the pix key query if previously performed
static_qr_code	Pix using a static QR code. Must send the end_to_end_id returned in the QR code decode
dynamic_qr_code	Pix using a dynamic QR code. Must send the end_to_end_id returned in the QR code decode

Response

STATUS

201

Response Body: Batch Transfer Requested

{
  "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

Enumerator	Description
approved	Batch transfer approved and transactions in the process of execution.
rejected	Batch transfer rejected
pending_2fa_approval	Batch transfer pending manual approval

STATUS

4xx

Response Body: Transfer rejected

{
  "title": "titulo",
  "description": "description in English",
  "translation": "description in portuguese",
  "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.

HTTP Code status	QI Code code	Title title	Description (eng) description	Description (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