执行 Pix 交易

请求

ENDPOINT

/account/ACCOUNT_KEY/pix_transfer

方法

POST

Path Params

字段	类型	描述	字符数
account_key	uuidv4	账户的唯一标识键。	36

通过 Pix 键转账

Request Body: 通过 Pix 键转账

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

Body Params

字段	类型	描述	字符数
request_control_key *	uuidv4	客户端使用的 uuid v4 格式请求唯一标识键。	36
pix_transfer_type *	enumerator	要执行的 Pix 类型。通过键转账时应为 key。	"key"
target_pix_key *	string	接收交易的账户 Pix 键。	100
transaction_amount *	number	转账金额。	10
end_to_end_id *	string	SPI（即时支付系统）内 Pix 交易的幂等键。该键在 Pix 键查询中返回。仅当 pix_transfer_type 为 key、static_qr_code 或 dynamic_qr_code 时发送。	32
pix_message	string	随 Pix 转账一起发送的消息。	140

手动转账 - 使用账户数据

Request Body: 手动转账

{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "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"
}

Body Params

字段	类型	描述	字符数
request_control_key *	uuidv4	客户端使用的 uuid v4 格式请求唯一标识键。	36
pix_transfer_type *	enumerator	Pix 转账类型。	manual
target_account *	Object	目标账户 - 仅在 pix_transfer_type 为 manual 的转账中发送。	Objeto target_account
transaction_amount *	number	转账金额。	10
pix_message	string	随 Pix 转账一起发送的消息。	140

Objeto target_account

字段	类型	描述	字符数
account_branch *	string	账户支行。	4
account_digit *	string	账户校验位。	1
account_number *	string	账户号码。	20
owner_document_number *	string	账户持有人的 CPF 或 CNPJ（仅数字）。	14
owner_name *	string	账户持有人姓名。	150
account_type*	enumerator	账户类型。	Enumerador account_type
ispb *	string	基于金融机构 CNPJ 的代码（8位数字）。	8

Enumerador account_type

枚举值	描述
checking_account	支票账户
salary_account	工资账户
saving_account	储蓄账户
payment_account	支付账户

通过 Pix QR 码转账

用于 Pix QR 码付款交易的数据必须通过使用 Pix 复制粘贴 URI 来解码 Pix QR 码获得。

I - "end_to_end_id" 字段必须与解码动态 QR 码返回的相同值。

II - 在 "transaction_amount" 字段中填写解码动态 QR 码时 "qr_code_data.amount" 字段返回的相同值；

III - 将 "pix_transfer_type" 字段更改为相应枚举值（static_qr_code 或 dynamic_qr_code），以请求付款。

IV - "receiver_conciliation_id" 字段必须与解码动态 QR 码返回的相同值。

Request Body: 通过 QR 码转账

{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "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"
}

Body Params

字段	类型	描述	字符数
request_control_key *	uuidv4	客户端使用的 uuid v4 格式请求唯一标识键。	36
pix_transfer_type *	enumerator	Pix 转账类型。	static_qr_code 或 dynamic_qr_code
target_pix_key *	string	接收交易的账户 Pix 键。	100
receiver_conciliation_id	string	接收方对账标识。	35
transaction_amount *	number	转账金额。	10
end_to_end_id *	string	SPI（即时支付系统）内 Pix 交易的幂等键。该键在 Pix 键查询中返回。仅当 pix_transfer_type 为 key、static_qr_code 或 dynamic_qr_code 时发送。	32
pix_message	string	随 Pix 转账一起发送的消息。	140

警告

查询的 end_to_end_id 必须是以将发起交易的账户名义进行的！

警告

一个 end_to_end_id 只能用于一次转账，无论该转账是否成功。

响应

STATUS

201

Response Body: 已发送转账

{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "transaction_key": "848d3ff7-4e98-4911-8773-f1d1b48c3068",
  "pix_transfer_status": "sent",
  "created_at": "2021-10-22T20:30:23.459Z"
}

STATUS

202

Response Body: 待处理转账

{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "transaction_key": "848d3ff7-4e98-4911-8773-f1d1b48c3068",
  "pix_transfer_status": "pending",
  "created_at": "2021-10-22T20:30:23.459Z",
  "transaction_key": "8ea90347-330d-4b3a-8ebb-2ac217ad6eb3"
}

信息

如果返回 HTTP Status 202 且 pix_transfer_status 字段值为 pending，则不应重试 Pix 申请。

该转账将被重新处理。需要通过查询 Pix 转账来检查转账状态。

STATUS

4xx

Response Body: 转账被拒绝

{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {
    "pix_transfer_data": {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "pix_transfer_status": "rejected",
      "created_at": "2021-10-22T20:30:23.459Z"
    }
  }
}

STATUS

4xx

Response Body: Error

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

HTTP 状态码 status	QI 代码 code	标题 title	描述（英文） description	描述（葡文） translation
400	QIT000001	Bad Request	Schema Error	Erro de Schema
403	PIT000001	User is not allowed to do this transaction		Usuário não tem autorização para fazer essa transação
400	PIT000003	Bad Request	Insufficient account balance for transfer and fee amount.	Saldo de conta insuficiente para a transferência e a taxa.
400	PIT000004	Bad Request	Transaction amount is over limit.	O total da transferência é superior ao limite.
400	PXT000003	Account is Closed	Account {account_key} is closed.	Conta {account_key} está fechada.
404	PXT000004	Account not found	Account not found for: {account_datum}	Conta não encontrada para: {account_datum}
400	PXT000010	Account is Blocked	Account {account_key} is blocked.	Conta {account_key} está bloqueada.
404	PXT000018	Reversal Original Transfer not Found	Reversal original pix transfer not found	Transferência original da devolução não foi encontrada
400	PXT000033	Target Account Must Not Be Source Account	Target Account Must Not Be Source Account	A conta de destino não pode ser a conta de origem
404	PXT000041	Not Found	Qr Code not found	Qr Code não encontrado
400	PXT000048	Bad Request	Emoji not allowed in pix message.	Emoji não é permitido na mensagem pix.
400	PXT000053	Bad Request	QrCode already paid	Qr Code já Pago
400	PXT000060	Bad Request	Nonexistent account in destination bank	Conta inexistente no banco de destino
400	PXT000061	Bad Request	End to end id invalid. A pix transfer with the end to end id {end_to_end} has already been registered!	End to end id inválido. Uma transação pix com o identificador único {end_to_end} já foi registrada!
400	PXT000079	Bad Request	Insufficient billing account balance for fee.	Saldo de conta de cobrança insuficiente para a taxa.
400	PXT000083	Bad Request	Pix rejected	Pix rejeitado
406	PXT000103	request_control_key must be a valid uuid v4 string	request_control_key was not accepted for not being a valid uuid v4 string	request_control_key não foi aceito por não ser uma palavra uuid v4 válida
400	PXT000104	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	PXT000105	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	PXT000108	Bad Request	Billing account closed or blocked	Conta de cobrança encerrada ou bloqueada
400	PXT000109	Bad Request	request_control_key {request_control_key} already in use	request_control_key {request_control_key} já utilizada
400	PXT000115	Bad Request	Insufficient account balance for transfer and fee amount.	Saldo de conta insuficiente para a transferência e a taxa
400	PXT000118	Requester is not Pix Participant	The requester sent an alias key but is not a indirect pix participant	O requisitante enviou uma alias key no entanto não é um participante do pix indireto
400	PXT000128	Bad Request	Pix key {pix_key} sent does match inquiry pix key. Verify if end_to_end_id sent is correct	Chave Pix {pix_key} enviada não condiz com consulta. Verifique se end_to_end_id enviado está correto
400	PXT000129	SPI Error message	Message rejected by SPI-ICOM	Mensagem rejeitada pela SPI-ICOM
408	PXT000130	SPI Timeout Control	SPI Timeout Control	Controle de timeout no SPI
400	PXT000131	Receiver Internal Error	Cancelled transaction due to receiver's internal error	Transação interrompida devido a erro no PSP do Recebedor
400	PXT000132	Invalid Target Account Number	Target account number is invalid	Número da conta de destino é inexistente ou inválido
400	PXT000133	Blocked Target Account	Target account is blocked.	A conta de destino encontra-se bloqueada.
400	PXT000134	Closed Target Account	Target account is closed.	A conta de destino encontra-se encerrada.
400	PXT000135	Unsupported Transaction	Unsupported transaction for given target account.	A conta de destino não suporta este tipo de transação.
400	PXT000136	Invalid Participant	SPI participant is not PSP settler agent of payer nor receiver.	Participante direto do SPI não é liquidante do PSP do Pagador / Recebedor.
400	PXT000137	Zero Value Payment Order	Zero value payment order.	Ordem de pagamento com valor zero.
400	PXT000138	Insufficient Funds	Insufficient funds in PI account from payer.	Saldo insuficiente na conta PI do pagador.
400	PXT000139	Return Value Too Great	Return value greater than corresponding payment order.	Valor de devolução acima do valor de pagamento correspondente.
400	PXT000140	Invalid Transactions Number	Invalid transactions number.	Quantidade de transações inválida.
400	PXT000141	Unrelated Beneficiary Document Number	Beneficiary document number is not that of target account owner.	CPF/CNPJ do usuário recebedor não é compatível com o titular da conta de destino.
400	PXT000142	Invalid Beneficiary Document Number	Invalid beneficiary document number	CPF/CNPJ da conta de destino está incorreto.
400	PXT000143	Incorrect Message Element	Incorrect message element.	Elemento da mensagem incorreto.
403	PXT000144	Rejected Payment Order	Beneficiary's PSP has rejected payment order.	Ordem de pagamento foi rejeitada pelo banco recebedor.
403	PXT000145	Unauthorized Payer	Signing participant is unauthorized to make a payment order for paying account.	Participante que assinou a mensagem não é autorizado a realizar a operação na conta PI debitada.
400	PXT000146	Invalid Datetime	Invalid datetime for message delivery.	Data e Hora do envio da mensagem inválida.
400	PXT000147	Generic Error	Error while processing payment (generic error).	Erro no processamento do pagamento (erro genérico).
400	PXT000148	Bad Format Operation Identifier	Badly formatted operation's identifier.	Identificador da operação mal formatado.
400	PXT000149	Invalid Payer ISPB	Invalid or non-existent payer's PSP ISPB number.	Número ISPB do PSP do Pagador é inválido ou inexistente.
400	PXT000150	Invalid Beneficiary ISPB	Invalid or non-existent beneficiary's PSP ISPB number.	Número ISPB do banco recebedor é inválido ou inexistente.
400	PXT000151	Incorrect Type	Incorrect type for target account.	Tipo incorreto para a conta transacional especificada.
400	PXT000152	Repeated End-to-End ID Error	The end_to_end_id was already used	O end_to_end_id já foi utilizado
400	PXT000153	Invalid Target Account Type	The target account type cannot receive PIX transactions	O tipo de conta destino não pode receber transações PIX
400	PXT000154	Invalid ISPB	Invalid or non-existent ISPB number.	Número ISPB é inválido ou inexistente.
400	PXT000155	Amount too Great	Amount too great for credited account.	Valor de pagamento/devolução acima do permitido para a conta de destino creditada.
400	PXT000156	QR Code Rejected	QR Code rejected by beneficiary's PSP.	QR Code rejeitado pelo PSP do usuário recebedor.
503	PXT000157	Bacen Service Unavailable Error	Could not send the message to ICOM after 3 retries	Não pode enviar a mensagem para a ICOM depois de 3 tentativas
400	PXT000158	Invalid Amount	Paid amount diverges from expected amount of {expected_amount}	O valor do pagamento diverge do valor esperado de {expected_amount}
403	PXT000167	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