Realizar transferência de Pix temporário

Executa uma transferência Pix consumindo o volume de um limite Pix temporário aprovado da conta, sem tocar no limite Pix padrão. O endpoint resolve sozinho o limite temporário ativo da conta — não é necessário informar a pix_request_key.

Request

ENDPOINT

/account/ACCOUNT_KEY/exceptional_pix_transfer

MÉTODO

POST

cuidado

Disponível das 06:00 às 20:00 (horário de Brasília). Fora dessa janela a resposta é PXT000204, ainda que haja volume disponível.

Path Params

Campo	Tipo	Descrição	Caracteres
account_key	uuidv4	Chave única de identificação da conta de origem, que deve possuir um limite Pix temporário aprovado.	36

Request Body

{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_type": "manual",
  "transaction_amount": 300000.00,
  "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"
  },
  "pix_message": "Pagamento de folha"
}

Body Params

Campo	Tipo	Descrição	Caracteres
pix_transfer_type *	enumerator	Tipo do Pix a ser realizado. Neste endpoint aceita somente o valor manual.	"manual"
transaction_amount *	number	Valor da transferência. Somado ao volume já transacionado, não pode exceder o total_amount aprovado.	—
target_account *	object	Dados da conta de destino. Ver Target Account.	—
request_control_key	uuidv4	Chave de idempotência da requisição, definida pelo parceiro. Ver Idempotência.	36
pix_message	string	Mensagem a ser enviada junto à transferência Pix.	140

informação

Transferência por chave Pix, QR Code estático ou QR Code dinâmico não é suportada neste endpoint. Para esses tipos, use Realizar transferência Pix, que consome o limite Pix padrão.

Target Account

Campo	Tipo	Descrição	Caracteres
account_branch *	string	Agência da conta de destino.	4
account_digit *	string	Dígito da conta de destino.	1
account_number *	string	Número da conta de destino.	20
owner_document_number *	string	CPF ou CNPJ do titular da conta de destino, somente números.	11 ou 14
owner_name *	string	Nome do titular da conta de destino.	100
account_type *	enumerator	Tipo da conta de destino.	—
ispb *	string	ISPB da instituição da conta de destino.	8

Idempotência

A request_control_key é a chave de idempotência da requisição.

Reuso é rejeitado, não reprocessado

Ao reenviar uma request_control_key já utilizada, a requisição é recusada — a transferência original não é retornada nem reexecutada, e nenhum volume de Pix temporário é consumido. Use uma chave nova em cada transferência.

Response

O código de resposta depende do modo de execução configurado para o solicitante, exatamente como na transferência Pix comum:

Código HTTP	pix_transfer_status	Significado
201	sent	Transferência enviada de forma síncrona
202	pending	Transferência aceita e sendo processada de forma assíncrona
202	pending_2fa_approval	Transferência aguardando aprovação por autenticação de dois fatores

Response Body: 201 Created

{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_key": "4f1c8b7a-2d3e-4f5a-9b8c-7d6e5f4a3b2c",
  "transaction_key": "8a7b6c5d-4e3f-2a1b-9c8d-7e6f5a4b3c2d",
  "end_to_end_id": "E32402502202608141530abcdefghijk",
  "pix_transfer_status": "sent",
  "created_at": "2026-08-14 15:30:00"
}

Response Body Params

Campo	Tipo	Descrição
request_control_key	uuidv4	Chave de idempotência informada na requisição.
pix_transfer_key	uuidv4	Chave única de identificação da transferência Pix no sistema QI.
transaction_key	uuidv4	Chave única de identificação da transação.
end_to_end_id	string	Chave de idempotência da transação Pix dentro do SPI.
pix_transfer_status	enumerator	Status da transferência.
created_at	string	Data e hora de criação da transferência.

informação

O volume do limite Pix temporário é reservado no momento desta chamada, antes da execução, e é liberado caso a transferência seja rejeitada. Nos modos assíncrono e 2FA a reserva atravessa o processamento — o volume permanece reservado enquanto a transferência estiver pendente.

Erros

Os erros específicos de Pix temporário estão em Erros de Pix temporário. Nesta operação podem ocorrer PXT000201, PXT000203 e PXT000204.

Além deles, valem todos os erros da transferência Pix comum — veja Realizar transferência Pix.