Pix

发起 Pix 交易

Request

ENDPOINT

/account/ACCOUNT_KEY/pix_transfer

MÉTODO

POST

路径参数

字段	类型	描述	字符数
`account_key`	uuidv4	账户唯一标识密钥。	36

Chave
Manual
Qr Code

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	Pix 交易在 SPI（即时支付系统）内的幂等键。此密钥在 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 时发送。	target_account 对象
`transaction_amount` *	number	转账金额。	10
`pix_message`	string	随 Pix 转账发送的消息。	140

target_account 对象

字段	类型	描述	字符数
`account_branch` *	string	账户支行号。	6
`account_digit` *	string	账户验证码。	1
`account_number` *	string	账户号码。	20
`owner_document_number` *	string	账户持有人 CPF 或 CNPJ（仅数字）。	14
`owner_name` *	string	账户持有人姓名。	150
`account_type`*	enumerator	账户类型。	account_type 枚举值
`ispb` *	string	金融机构 CNPJ 的前八位数字。	8

account_type 枚举值

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

Request Body: 通过 QR Code 转账

{
  "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	Pix 交易在 SPI（即时支付系统）内的幂等键。此密钥在 Pix 密钥查询中返回。仅当 `pix_transfer_type` 为 key、static_qr_code 或 static_qr_code 时才应发送。	32
`pix_message`	string	随 Pix 转账发送的消息。	140

提示

end_to_end_id 在解码 Pix QR Code 时返回，使用 Pix 复制粘贴的 URI。

注意

查询使用的 end_to_end_id 必须是以将发起转账的账户名义查询的！

注意

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

Response

STATUS

201

Response Body: 转账已发送

{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "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",
  "pix_transfer_status": "pending",
  "created_at": "2021-10-22T20:30:23.459Z"
}

说明

若返回 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: 错误

{
  "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
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	PXT000048	Bad Request	Emoji not allowed in pix message.	Emoji não é permitido na mensagem pix.
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
404	PXT000004	Account not found	Account not found for: {account_datum}	Conta não encontrada para: {account_datum}
400	PXT000003	Account is Closed	Account {account_key} is closed.	Conta {account_key} está fechada.
422	PXT000092	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	PIT000001	User is not allowed to do this transaction		Usuário não tem autorização para fazer essa transação
400	PXT000010	Account is Blocked	Account {account_key} is blocked.	Conta {account_key} está bloqueada.
400	PIT000003	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
404	PXT000120	Alias sent not found	Alias key attached to this account not found	Alias key vinculada à conta não encontrada
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	PXT000079	Bad Request	Insufficient billing account balance for fee.	Saldo de conta de cobrança insuficiente para a taxa.
400	PIT000004	Bad Request	Transaction amount is over limit.	O total da transferência é superior ao limite.
404	PIX000056	Not Found	Pix key inquiry not found	Consulta de chave pix não encontrada
404	PXT000041	Not Found	Qr Code not found	Qr Code não encontrado
400	PXT000053	Bad Request	QrCode already paid	Qr Code já Pago
400	PXT000115	Bad Request	Insufficient account balance for transfer and fee amount.	Saldo de conta insuficiente para a transferência e a taxa
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
409	PXT000109	Bad Request	request_control_key {request_control_key} already in use	request_control_key {request_control_key} já utilizada
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	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}
400	PXT000159	QR code inactive	QR code is not active at the time of payment	QR code não está ativo no instante do pagamento

在巴西中央银行查询 Pix 密钥

Request

ENDPOINT

/pix_key/PIX_KEY?account_key=ACCOUNT_KEY

MÉTODO

GET

路径参数

字段	类型	描述	字符数
`pix_key` *	string	将被查询的 Pix 密钥。	77

Pix 密钥类型

pix_key 可以是 CPF、CNPJ、电子邮件、手机号或随机密钥（UUID），格式如下：

CPF：11 位整数。

CNPJ：14 位整数。

电子邮件：包含至少一个"@"的文本。

手机号：包含以下值的文本："+55" + "手机区号" + "至少 8 位至多 9 位的整数手机号码"。例如："+5511987654321"。

随机密钥：UUID4。

查询参数

字段	类型	描述	字符数
`account_key` *	uuidv4	账户唯一标识密钥。	36

查询 token 的使用

为确保 Pix 密钥查询 token 向正确的人收费，必须发送 account_key。

Response

STATUS

200

Response Body: 密钥有效

{
  "account_branch": "0001",
  "account_created_at": "2023-09-06T22:03:34.000Z",
  "account_digit": "8",
  "account_number": "2897775",
  "account_type": "checking",
  "bank_code": null,
  "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
  "financial_institution": "BANCO INDIRETO PRUPRU",
  "ispb": "32402502",
  "owner_masked_document_number": "**.458.****/0001-**",
  "owner_name": "Empresa teste 01",
  "owner_person_type": "legal",
  "owner_trading_name": null,
  "pix_key": "0f723f66-b333-4187-be16-97fc37c86052"
}

STATUS

4xx

Response Body: 错误

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

HTTP 状态码 `status`	QI 代码 `code`	标题 `title`	英文描述 `description`	葡语描述 `translation`
404	PIX000017	Pix Key is Unregistered	Pix key {pix_key} is not currently used	A chave pix {pix_key} não está sendo utilizada
400	PIX000081	Rate Limit Exceeded	Rate Limit Exceeded	Limite de requisições excedido

退还一笔 Pix

Pix 退还可在收款后 90 天内进行。

Request

ENDPOINT

/account/ACCOUNT_KEY/pix_transfer/PIX_TRANSFER_KEY/reversal

MÉTODO

POST

路径参数

字段	类型	描述	字符数
`account_key` *	uuidv4	账户唯一标识密钥。	36
`pix_transfer_key` *	uuidv4	QI 系统中 Pix 转账的唯一标识密钥。	36

Request Body

{
  "request_control_key": "303393bf-8f2e-4ff0-b326-ee7ad612e8ca",
  "reversal_amount": 147,
  "reversal_reason": "client_request",
  "reversal_message": "Mensagem Pix da Devolução"
}

请求体

字段	类型	描述	字符数
`request_control_key` *	uuidv4	请求的唯一性密钥。	36
`reversal_amount` *	number	退还金额。	11
`reversal_reason` *	string	退还原因。	reversal_reason 枚举值
`reversal_message`	string	退还消息。	140

reversal_reason 枚举值

枚举值	描述
client_request	由账户持有人提出的要求。
reconciliation	因操作错误进行对账。

Response

STATUS

201

Response Body: 退还已发送

{
  "reversal_status": "sent",
  "transfer_amount": 147,
  "pix_transfer_key": "cdcf0d25-08a1-46e3-902a-6d7ca75e6c48",
  "end_to_end_id": "E32402502202407112211Id9JbxoaiTf",
  "request_control_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
  "created_at": "2021-10-22T20:30:23.459Z"
}

STATUS

202

Response Body: 退还待处理

{
  "reversal_status": "pending",
  "transfer_amount": 147,
  "pix_transfer_key": "cdcf0d25-08a1-46e3-902a-6d7ca75e6c48",
  "end_to_end_id": "E32402502202407112211Id9JbxoaiTf",
  "request_control_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
  "created_at": "2021-10-22T20:30:23.459Z"
}

说明

若返回 HTTP Status 202 且 pix_transfer_status 值为 pending，则不应重试 Pix 请求。

该转账将被重新处理。需通过查询 Pix 转账验证转账状态。

响应体

字段	类型	描述	字符数
`reversal_status`	enumerator	退还交易状态枚举值。	reversal_status 枚举值
`transfer_amount`	number	退还转账金额。	11
`pix_transfer_key`	uuidv4	退还执行的 Pix 交易密钥。	36
`end_to_end_id`	string	Pix 交易在 SPI（即时支付系统）内的幂等键	32
`request_control_key`	uuidv4	客户使用的请求唯一标识密钥。	36
`created_at`	string	退还日期和时间。	10

reversal_status 枚举值

枚举值	描述
sent	Pix 转账执行成功。
pending	Pix 转账待处理。
rejected	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"
    }
  }
}

说明

除上述 Pix 转账错误外，Pix 退还还可能返回以下错误。

HTTP 状态码 `status`	QI 代码 `code`	标题 `title`	英文描述 `description`	葡语描述 `translation`
400	QIT000001	Bad Request	Schema Error	Erro de Schema
404	PXT000018	Reversal Original Transfer not Found	Reversal original pix transfer not found.	Transferência original da devolução não foi encontrada.
400	PXT000017	Reversal Too Great	Reversal transfers sum amount surpasses that of original pix transfer.	A soma das transferências de devolução ultrapassam o valor da transferência pix original.
400	PXT000015	Reversal date expired	Reversal original transaction is older than 90 days	A data de criação da transação original é mais antiga que 90 dias
400	PXT0000127	Invalid Reversal Reason	Reversal reason {reversal_reason} is not valid	Razão de reversão {reversal_reason} não é válida

通过 pix_transfer_key 查询 Pix 交易

Request

ENDPOINT

/account/ACCOUNT_KEY/pix_transfer/PIX_TRANSFER_KEY/PIX_TRANSFER_DIRECTION

MÉTODO

GET

路径参数

字段	类型	描述	字符数
`pix_transfer_direction` *	enumerator	交易方向指示符（入账或出账）。	pix_transfer_direction 枚举值
`account_key` *	uuidv4	QI 账户唯一标识密钥。	36
`pix_transfer_key` *	uuidv4	Pix 转账唯一标识密钥。	36

pix_transfer_direction 枚举值

枚举值	描述
incoming	Pix 转账执行成功。
outgoing	Pix 转账执行成功。

Response

STATUS

201

Response Body: 转账已发送（outgoing）

{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "pix_message": "Bom dia",
  "pix_transfer_type": "manual",
  "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "updated_at": "2021-10-22T20:30:23.459Z",
  "created_at": "2021-10-22T20:30:23.459Z",
  "target_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "12345678",
    "owner_document_number": "***02502000***",
    "owner_person_type": "legal",
    "owner_name": "Qi Tech",
    "account_type": "checking_account",
    "ispb": "32402502",
    "pix_key": null
  },
  "receiver_conciliation_id": null,
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "end_to_end_id": "E3240250220211022203051750897529",
  "pix_transfer_status": "sent",
  "transfer_amount": 126.97,
  "fee_amount": 0.0,
  "rejection_reason": null,
  "reversals": [
    {
      "end_to_end_id": "D35713491202309182058jlqdBkkHSWU",
      "transfer_amount": 0.01,
      "reversal_reason": "client_request",
      "pix_transfer_status": "received",
      "pix_transfer_key": "423866cd-0f3f-4cdd-904b-0d2e33273afd",
      "request_control_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0a",
      "created_at": "2021-10-23T20:30.459Z"
    }
  ]
}

Response Body: 转账已拒绝（outgoing）

{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "pix_message": "Bom dia",
  "pix_transfer_type": "manual",
  "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "updated_at": "2021-10-22T20:30:23.459Z",
  "created_at": "2021-10-22T20:30:23.459Z",
  "target_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "12345678",
    "owner_document_number": "***02502000***",
    "owner_person_type": "legal",
    "owner_name": "Qi Tech",
    "account_type": "checking_account",
    "ispb": "32402502",
    "pix_key": null
  },
  "receiver_conciliation_id": null,
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "end_to_end_id": "E3240250220211022203051750897529",
  "pix_transfer_status": "rejected",
  "transfer_amount": 126.97,
  "fee_amount": 0.0,
  "error_code": "PXT000132",
  "error_description": "Target account number is invalid.",
  "error_translation": "Número da conta de destino é inexistente ou inválido.",
  "reversals": []
}

Response Body: 退还已发送（outgoing）

{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "pix_message": "Bom dia",
  "pix_transfer_type": "reversal",
  "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "updated_at": "2021-10-22T20:30:23.459Z",
  "created_at": "2021-10-22T20:30:23.459Z",
  "target_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "12345678",
    "owner_document_number": "***02502000***",
    "owner_person_type": "legal",
    "owner_name": "Qi Tech",
    "account_type": "checking_account",
    "ispb": "32402502",
    "pix_key": null
  },
  "receiver_conciliation_id": null,
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "end_to_end_id": "E3240250220211022203051750897529",
  "pix_transfer_status": "sent",
  "transfer_amount": 126.97,
  "fee_amount": 0.0,
  "rejection_reason": null,
  "reversals": [],
  "original_incoming_pix_transfer": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3"
}

Response Body: 转账已收到（incoming）

{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "end_to_end_id": "E18236120202308111235s14fddf2801",
  "pix_transfer_status": "received",
  "receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
  "transfer_amount": 126.97,
  "fee_amount": 0.0,
  "source_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "12345678",
    "owner_document_number": "***02502000***",
    "owner_person_type": "legal",
    "owner_name": "Qi Tech",
    "account_type": "checking_account",
    "ispb": "32402502"
  },
  "pix_transfer_type": "dynamic_qr_code",
  "reversals": []
}

Response Body: 退还已收到（incoming）

{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "end_to_end_id": "E18236120202308111235s14fddf2801",
  "pix_transfer_status": "received",
  "receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
  "transfer_amount": 126.97,
  "fee_amount": 0.0,
  "source_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "12345678",
    "owner_document_number": "***02502000***",
    "owner_person_type": "legal",
    "owner_name": "Qi Tech",
    "account_type": "checking_account",
    "ispb": "32402502"
  },
  "pix_transfer_type": "reversal",
  "reversals": [],
  "original_outgoing_pix_transfer": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3"
}

Response Body: 转账已拒绝（incoming）

{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "end_to_end_id": "E18236120202308111235s14fddf2801",
  "pix_transfer_status": "rejected",
  "receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
  "transfer_amount": 126.97,
  "fee_amount": 0.0,
  "source_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "12345678",
    "owner_document_number": "***02502000***",
    "owner_person_type": "legal",
    "owner_name": "Qi Tech",
    "account_type": "checking_account",
    "ispb": "32402502"
  },
  "pix_transfer_type": "dynamic_qr_code",
  "reversals": []
}

STATUS

4xx

Response Body: 错误

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

HTTP 状态码	QI 代码 `code`	标题 `title`	英文描述 `Description`	葡语描述 `translation`
400	PXT000075	Pix Transfer Key or End To End Not Provided	No pix transfer key or end to end id provided.	Não foram fornecidos uma pix transfer key ou end to end id.
404	PXT000023	Outgoing PIX Transfer Not Found	Pix transfer key {pix_transfer_key} was not found	Transferência PIX de saída com chave {pix_transfer_key} não foi encontrada.
403	PIT000001	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

查询多笔 Pix 交易

Request

ENDPOINT

/account/ACCOUNT_KEY/pix_transfers

MÉTODO

GET

路径参数

字段	类型	描述	字符数
`account_key` *	uuidv4	QI 账户唯一标识密钥	36

查询参数

字段	类型	描述	字符数
`pix_transfer_direction`	enumerator	交易方向指示符（入账或出账）。若未发送，默认为 outgoing	pix_transfer_direction 枚举值
`request_control_key`	uuidv4	客户使用的请求唯一标识密钥。	36
`end_to_end_id`	string	Pix 交易幂等键	32
`transaction_key`	uuidv4	账户变动标识密钥	36
`date_from`	string	起始日期。格式："YYYY-MM-DD"
`date_to`	string	结束日期。格式："YYYY-MM-DD"
`page`	integer	请求的页码，默认为 1
`page_size`	integer	查询请求的页面大小，默认值和最大值为 30	最大值 30

pix_transfer_direction 枚举值

枚举值	描述
incoming	Pix 入账转账
outgoing	Pix 出账转账

Response

STATUS

201

Response Body

{
  "data": [
    {
      "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
      "pix_message": "Bom dia",
      "pix_transfer_type": "manual",
      "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
      "updated_at": "2021-10-22T20:30:23.459Z",
      "created_at": "2021-10-22T20:30:23.459Z",
      "target_account": {
        "account_branch": "0001",
        "account_digit": "3",
        "account_number": "12345678",
        "owner_document_number": "***02502000***",
        "owner_person_type": "legal",
        "owner_name": "Qi Tech",
        "account_type": "checking_account",
        "ispb": "32402502",
        "pix_key": null
      },
      "receiver_conciliation_id": null,
      "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "end_to_end_id": "E3240250220211022203051750897529",
      "pix_transfer_status": "sent",
      "transfer_amount": 126.97,
      "fee_amount": 0.0,
      "rejection_reason": null,
      "reversals": [
        {
          "end_to_end_id": "D35713491202309182058jlqdBkkHSWU",
          "transfer_amount": 0.01,
          "reversal_reason": "client_request",
          "pix_transfer_status": "received",
          "pix_transfer_key": "423866cd-0f3f-4cdd-904b-0d2e33273afd",
          "request_control_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0a",
          "created_at": "2021-10-23T20:30.459Z"
        }
      ]
    }
  ],
  "pagination": {
    "current_page": 1,
    "rows_per_page": 30
  }
}

待处理交易的 Webhook

此 Webhook 用于通知最初响应为待处理（返回 HTTP 状态码 202）的交易完成情况。

Webhook 请求体

Request Body: 交易已发送

{
  "webhook_type": "baas.pix_transfer.outgoing_pix",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
    "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "pix_transfer_status": "sent",
    "created_at": "2021-10-22T20:30:23.459Z"
  }
}

Request Body: 交易已拒绝

{
  "webhook_type": "baas.pix_transfer.outgoing_pix",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "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",
    "error_code": "PXT000132",
    "error_description": "Target account number is invalid.",
    "error_translation": "Número da conta de destino é inexistente ou inválido.",
    "error_short_description": null
  }
}

Webhook Body 参数

字段	类型	描述	最大字符数
`webhook_type`	string	定义正在报告的事件类型的枚举值	23
`webhook_datetime`	string	Webhook 发送的日期和时间	20
`request_control_key`	string	用于查询所发出请求的 UUID4	36
`pix_transfer_key`	string	QI 系统中 Pix 转账的标识密钥	36
`pix_transfer_status`	string	交易状态。	200
`created_at`	string	交易创建日期和时间。	20

入账 Pix 的 Webhook

此 Webhook 用于通知到达某账户的 Pix 交易。

Webhook 请求体

Request Body: 已收到 Pix

{
  "webhook_type": "baas.pix_transfer.incoming_pix",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "end_to_end_id": "E18236120202308111235s14fddf2801",
    "pix_transfer_status": "received",
    "account_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
    "receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
    "transfer_amount": 126.97,
    "fee_amount": 0.0,
    "source_account": {
      "account_branch": "0001",
      "account_digit": "3",
      "account_number": "12345678",
      "owner_document_number": "***02502000***",
      "owner_person_type": "legal",
      "owner_name": "Qi Tech",
      "account_type": "checking_account",
      "ispb": "32402502"
    },
    "pix_transfer_type": "dynamic_qr_code",
    "pix_message": "pix message received",
    "created_at": "2021-10-22T20:30:23.459Z",
    "reversals": []
  }
}

Webhook Body 参数

字段	类型	描述	最大字符数
`webhook_type`	string	定义正在报告的事件类型的枚举值	23
`webhook_datetime`	string	Webhook 发送的日期和时间	20
`pix_transfer_type`	enumerator	已执行的 Pix 类型	pix_transfer_type 枚举值
`target_pix_key`	string	接收交易的账户 Pix 密钥	100
`source_account`	Object	目标账户 - 仅在 "manual" 类型交易中发送	source_account 对象
`transfer_amount`	number	转账金额	10
`receiver_conciliation_id`	string	收款方对账标识	35
`end_to_end_id`	string	Pix 交易幂等键 - 仅在转账类型为 "key" 时发送	32
`pix_message`	string	随 Pix 转账发送的消息	140
`fee_amount`	number	转账金额	10
`pix_transfer_status`	string	Pix 交易状态	10
`account_key`	string	QI 账户唯一标识密钥	36
`pix_transfer_key`	string	Pix 转账唯一标识密钥	36

pix_transfer_type 枚举值

枚举值	描述
manual	使用目标账户数据的 Pix
key	使用 Pix 密钥的 Pix
static_qr_code	使用静态 QR Code 的 Pix
dynamic_qr_code	使用动态 QR Code 的 Pix
reversal	Pix 退还

source_account 对象

字段	类型	描述	字符数
`account_branch` *	string	账户支行号	6
`account_digit` *	string	账户验证码	1
`account_number` *	string	账户号码	20
`owner_document_number` *	string	账户持有人 CPF 或 CNPJ（仅数字）	14
`owner_name`	string	账户持有人姓名	150
`account_type`*	enumerator	账户类型	account_type 枚举值
`ispb` *	string	在巴西中央银行储备转账系统中识别银行的八位数代码	8

account_type 枚举值

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

Pix 退还的 Webhook

此 Webhook 用于通知到达某账户的 Pix 退还。

Webhook 请求体

Request Body: 已收到 Pix

{
  "webhook_type": "baas.pix_transfer.incoming_pix",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "end_to_end_id": "E18236120202308111235s14fddf2801",
    "pix_transfer_status": "received",
    "account_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
    "receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
    "transfer_amount": 126.97,
    "fee_amount": 0.0,
    "source_account": {
      "account_branch": "0001",
      "account_digit": "3",
      "account_number": "12345678",
      "owner_document_number": "***02502000***",
      "owner_person_type": "legal",
      "owner_name": "Qi Tech",
      "account_type": "checking_account",
      "ispb": "32402502"
    },
    "pix_transfer_type": "reversal",
    "pix_message": "pix message received",
    "created_at": "2021-10-22T20:30:23.459Z",
    "reversals": [],
    "original_outgoing_pix_transfer": "b56862c4-2b20-4057-8063-b8809866e494"
  }
}

Webhook Body 参数

字段	类型	描述	最大字符数
`webhook_type`	string	定义正在报告的事件类型的枚举值	23
`webhook_datetime`	string	Webhook 发送的日期和时间	20
`pix_transfer_type`	enumerator	已执行的 Pix 类型	pix_transfer_type 枚举值
`target_pix_key`	string	接收交易的账户 Pix 密钥	100
`source_account`	Object	目标账户 - 仅在 "manual" 类型交易中发送	source_account 对象
`transfer_amount`	number	转账金额	10
`receiver_conciliation_id`	string	收款方对账标识	35
`end_to_end_id`	string	Pix 交易幂等键 - 仅在转账类型为 "key" 时发送	32
`pix_message`	string	随 Pix 转账发送的消息	140
`fee_amount`	number	转账金额	10
`pix_transfer_status`	string	Pix 交易状态	10
`account_key`	string	QI 账户唯一标识密钥	36
`pix_transfer_key`	string	Pix 转账唯一标识密钥	36
`original_outgoing_pix_transfer`	string	原始出账 Pix 转账的唯一标识密钥	36

pix_transfer_type 枚举值

枚举值	描述
manual	使用目标账户数据的 Pix
key	使用 Pix 密钥的 Pix
static_qr_code	使用静态 QR Code 的 Pix
dynamic_qr_code	使用动态 QR Code 的 Pix
reversal	Pix 退还

source_account 对象

字段	类型	描述	字符数
`account_branch`	string	账户支行号	6
`account_digit`	string	账户验证码	1
`account_number`	string	账户号码	20
`owner_document_number`	string	账户持有人 CPF 或 CNPJ（仅数字）	14
`owner_name`	string	账户持有人姓名	150
`account_type`	enumerator	账户类型	account_type 枚举值
`ispb`	string	在巴西中央银行储备转账系统中识别银行的八位数代码	8

account_type 枚举值

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

发起 Pix 交易​

Request​

路径参数​

Body Params​

Body Params​

target_account 对象​

account_type 枚举值​

Body Params​

Response​

在巴西中央银行查询 Pix 密钥​

Request​

路径参数​

查询参数​

Response​

退还一笔 Pix​

Request​

路径参数​

请求体​

reversal_reason 枚举值​

Response​

响应体​

reversal_status 枚举值​

通过 pix_transfer_key 查询 Pix 交易​

Request​

路径参数​

pix_transfer_direction 枚举值​

Response​

查询多笔 Pix 交易​

Request​

路径参数​

查询参数​

pix_transfer_direction 枚举值​

Response​

待处理交易的 Webhook​

Webhook 请求体​

Webhook Body 参数​

入账 Pix 的 Webhook​

Webhook 请求体​

Webhook Body 参数​

pix_transfer_type 枚举值​

source_account 对象​

account_type 枚举值​

Pix 退还的 Webhook​

Webhook 请求体​

Webhook Body 参数​

pix_transfer_type 枚举值​

source_account 对象​

account_type 枚举值​

发起 Pix 交易

Request

路径参数

Body Params

Body Params

target_account 对象

account_type 枚举值

Body Params

Response

在巴西中央银行查询 Pix 密钥

Request

路径参数

查询参数

Response

退还一笔 Pix

Request

路径参数

请求体

reversal_reason 枚举值

Response

响应体

reversal_status 枚举值

通过 pix_transfer_key 查询 Pix 交易

Request

路径参数

pix_transfer_direction 枚举值

Response

查询多笔 Pix 交易

Request

路径参数

查询参数

pix_transfer_direction 枚举值

Response

待处理交易的 Webhook

Webhook 请求体

Webhook Body 参数

入账 Pix 的 Webhook

Webhook 请求体

Webhook Body 参数

pix_transfer_type 枚举值

source_account 对象

account_type 枚举值

Pix 退还的 Webhook

Webhook 请求体

Webhook Body 参数

pix_transfer_type 枚举值

source_account 对象

account_type 枚举值