Manual BaaS - 数字账户

注意

在开始开户流程之前，合作伙伴有责任进行 KYC 和反欺诈分析。

注意！

QI Tech 的 Webhooks 不应以受限方式进行映射。 API 返回的 Webhook payload 中可能会新增额外字段。

重新发送 Webhooks

您可以按照文档中的详细说明查询和重新发送 Webhooks：重新发送 Webhooks。

为此，应使用 /onboarding 中描述的分析端点。

1 - 创建账户

1.1. 上传文件

开户前须先上传公司文件。以下是各类型公司所需的文件列表：

S.A. 公司：

公司章程。
公司法定代表人选举会议纪要。
授权书（如适用）。
每位法定代表人或受托人的带照片证件。

其他情况：

合同协议。
授权书（如适用）。
每位法定代表人或受托人的带照片证件。文件须压缩为 ".zip" 格式，并通过文件上传端点发送（）。

Response

ENDPOINT

/upload

MÉTODO

POST

Response Body

{
    "document_key": "cd639c4a-2279-468a-a047-59865b8159ed",
    "document_md5": "8f5bef84cb07dc047017c0d304dbb6b8",
    "url": "https://storage.googleapis.com/sandbox-doc-api/documents/cd639c4a-2279-468a-a047-59865b8159ed/identificacao_teste.pdf"
}

重要

请保存此 "document_key"，因为在创建账户步骤中将会用到它。

1.2. 创建法人账户（PJ）

Request

ENDPOINT

/account

MÉTODO

POST

Request Body

{
	"account_owner": {
		"annual_revenue_amount": 180000,
		"address": {
			"city": "Limeira",
			"complement": "complemento",
			"neighborhood": "Vila Cidade Jardim",
			"number": "662",
			"postal_code": "13480290",
			"state": "SP",
			"street": "Avenida Campinas"
		},
		"cnae_code": "4721-1/02",
        "company_statute": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
		"company_document_number": "09080702000105",
		"company_type": "ltda",
		"email": "padaria@vovolucia.com.br",
		"foundation_date": "1950-08-21",
		"annual_revenue_amount": "1000000.00",
		"name": "VOVO LUCIA CONVENIENCIA LTDA",
		"person_type": "legal",
		"phone": {
			"area_code": "19",
			"country_code": "55",
			"number": "988888888"
		},
		"trading_name": "Empadaria Vovo Lucia",
		"company_representatives": [{
				"address": {
					"city": "Recife",
					"complement": null,
					"neighborhood": "Fundão",
					"number": "137",
					"postal_code": "52221110",
					"state": "PE",
					"street": "Rua Camapuã"
				},
				"birth_date": "1972-02-02",
				"document_identification_number": "339122924",
                "document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
				"email": "marcos.alves@yopmail.com",
				"individual_document_number": "08531309069",
				"is_pep": false,
				"marital_status": "single",
				"mother_name": "Sueli Isadora Alves",
				"name": "Marcos Felipe Henrique Alves",
				"nationality": "Brasileira",
				"person_type": "natural",
				"phone": {
					"area_code": "88",
					"country_code": "55",
					"number": "995924634"
				}
			},
			{
				"person_type": "natural",
				"name": "Juliana Tereza Bernardes",
				"mother_name": "Maria Mariane",
				"birth_date": "1990-05-06",
				"profession": "Deputada",
				"nationality": "Brasileira",
				"marital_status": "single",
				"is_pep": false,
				"individual_document_number": "97564480084",
				"document_identification_number": "232479719",
                "document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
				"email": "juliana.tereza@yopmail.com",
				"phone": {
					"country_code": "55",
					"area_code": "11",
					"number": "912821359"
				},
				"address": {
					"street": "Passagem Mariana",
					"state": "PA",
					"city": "Ananindeua",
					"neighborhood": "Águas Lindas",
					"number": "660",
					"postal_code": "67118003",
					"complement": "complemento"
				}
			}
		]
	},
	"allowed_user": {
		"email": "juliana.tereza@yopmail.com",
		"individual_document_number": "97564480084",
		"name": "Juliana Tereza Bernardes",
		"person_type": "natural",
		"phone": {
			"country_code": "55",
			"area_code": "11",
			"number": "912828135"
		}
	},
	"signed_contract": {
        "document_key": "4d7f4e29-4b58-4905-9a69-b1f9215263f5",
        "signatures": [
            {
                "authenticity": {
                    "timestamp": "1970-01-01T00:00:01.080100Z",
                    "facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb",
                    "lang": "-35.8916627",
                    "lat": "-7.2226067",
                    "ip_address": "177.51.1.000",
                    "session_id": "jdifj329842"
                },
                "signer": {
                    "name": "IVANILDO DE SENA LIMA",
                    "email": "teste@gmail.com",
                    "phone": {
                        "country_code": "055",
                        "area_code": "11",
                        "number": "999999999"
                    },
                    "document_number": "99999999999"
                },
                "authentication_type": "opt-in"
            }
        ]
    }
}

"account_owner"： 公司数据应在此对象中发送。

"account_owner.company_statute"：上传公司章程文件（".zip" 格式）时，文件上传端点返回的 "document_key" 应在此字段中发送。

"account_owner.company_representatives"：公司法定代表人的数据列表应在此对象中发送。至少应发送足以根据公司章程/合同合法代表公司的法定代表人。每位法定代表人的权限验证由合作伙伴负责。

"account_owner.company_representatives.document_identification"：上传代表人带照片证件（".zip" 格式）时，文件上传端点返回的 "document_key" 应在此字段中发送。

"allowed_user"：此字段应发送 "account_owner.company_representatives" 对象中某位法定代表人的数据。该用户将成为账户管理员，拥有账户操作权限以及添加新管理员用户的权限。无论是账户操作还是添加新用户的 SMS/邮件确认，均将发送给此人。

信息

具有管理员权限的用户对账户拥有完全控制权（通过短信或邮件的双因素认证）。因此，该用户须根据公司合同/章程在法律上具有操作账户的权限。管理员用户的权限验证由合作伙伴负责。

1.2.1 开户条款签署

在开户 payload 中，须发送 signature_contract 字段，该字段应包含用户（账户持有人或主用户）接受开户条款时的设备扫描信息。

signed_contract 对象

字段	类型	描述	字符数
document_key *	uuidv4	开户条款或托管账户合同文件的唯一标识键。（DOCUMENT_KEY 在文件上传端点的响应中返回）	36
signatures *	list	所发送文件的签名数据。列表中的每一项对应一位签署人。	signatures 对象

signatures 对象

字段	类型	描述	字符数
authenticity *	object	证明签署人完成电子签名的数据集合。	authenticity 对象
signer *	object	包含某位文件签署人数据的对象。	signer 对象
authentication_type *	enumerator	签名类型。始终为 "opt-in"	"opt-in"

authenticity 对象

字段	类型	描述	字符数
timestamp *	string	文件签署时的日期和时间。	27
facial_recognition_key	uuidv4	账户持有人自拍照片的唯一标识键。（DOCUMENT_KEY 在文件上传端点的响应中返回）	36
lang	string	签署时捕获的签署人地理位置经度坐标。	-
lat	string	签署时捕获的签署人地理位置纬度坐标。	-
ip_address	string	签署人设备的 IP 地址。	-
session_id	string	签署时签署人的会话 ID。	-

signer 对象

字段	类型	描述	字符数
name *	string	签署人姓名。	-
email *	string	签署人邮箱。	-
phone *	object	包含签署人电话数据的对象	phone 对象
document_number *	string	签署人 CPF。	11

phone 对象

字段	描述	示例	最大字符数
`country_code` *	string	电话 DDI 代码 (https://ddi.guiamais.com.br/)	3
`area_code` *	string	电话 DDD 代码 (https://ddd.guiamais.com.br/)	2
`number` *	string	电话号码（仅数字）	10

Response

MÉTODO
POST
ENDPOINT
/account

Response Body

{
	"data": {
		"account_info": {
			"account_branch": "0001",
			"account_digit": "2",
			"account_number": "2359934",
			"financial_institution_code": "329"
		},
		"account_owner": {
			"document_number": "09080702000105",
			"name": "VOVO LUCIA CONVENIENCIA LTDA"
		},
		"allowed_user": {
			"document_number": "97564480084",
			"name": "Juliana Tereza Bernardes"
		}
	},
	"event_datetime": "2022-09-02 22:39:10",
	"key": "\<UUID PROPOSAL-KEY\>",
	"status": "pending_kyc_analysis",
	"webhook_type": "account"
}

重要

重要：此响应中返回的 "key" 是开户申请的 PROPOSAL-KEY。应将其保存，以便读取开户 Webhook。

开户申请的响应始终返回状态 "pending_kyc_analysis"。

系统将为该客户保留一个账号，但账户仍待 QI Tech 进行 KYC 分析。此时，账户尚未开通，无法接收或发送资金。

1.3. 创建个人账户（PF）

Request

ENDPOINT
/account
MÉTODO
POST

Request Body

{
	"account_owner": {
		"address": {
			"street": "Avenida Sargento Geraldo Sant'Ana",
			"number": "1100",
			"neighborhood": "Jardim Taquaral",
			"city": "São Paulo",
			"state": "SP",
			"postal_code": "04674225"
		},
		"phone": {
			"country_code": "55",
			"number": "912828135",
			"area_code": "11"
		},
		"email": "juliana.tereza@yopmail.com",
		"name": "Juliana Tereza Bernardes",
		"person_type": "natural",
		"nationality": "Brasil",
		"birth_date": "1993-08-02",
		"mother_name": "Patricia Monica Diaz Bascur Tieppo",
		"is_pep": false,
		"individual_document_number": "97564480084",
		"document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
		"document_identification_type": "cnh",
        "revenue_amount": 1000,
        "profession": "autonomo"
	},
	"signed_contract": {
        "document_key": "4d7f4e29-4b58-4905-9a69-b1f9215263f5",
        "signatures": [
            {
                "authenticity": {
                    "timestamp": "1970-01-01T00:00:01.080100Z",
                    "facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb",
                    "lang": "-35.8916627",
                    "lat": "-7.2226067",
                    "ip_address": "177.51.1.000",
                    "session_id": "jdifj329842"
                },
                "signer": {
                    "name": "IVANILDO DE SENA LIMA",
                    "email": "teste@gmail.com",
                    "phone": {
                        "country_code": "055",
                        "area_code": "11",
                        "number": "999999999"
                    },
                    "document_number": "99999999999"
                },
                "authentication_type": "opt-in"
            }
        ]
    }
}

"account_owner"： 个人账户持有人的数据应在此对象中发送。

"account_owner.document_identification"： 文件上传端点返回的 "document_key"。

1.3.1. 身份证件的提交方式

开立个人账户时，可提交两种类型的证件（document_identification_type）：cnh 或 rg。

身份证件可以 ".pdf"、".png" 和 ".jpeg" 格式提交。

1.3.1.1. 提交 CNH 类型身份证件

如果文件以 2 个文件提交，证件正面在一个文件中，背面在另一个文件中，则应在 /account 端点（1.2.2.）的 account_owner 对象中填写以下字段：

Request Body

		"document_identification": "\<DOCUMENT-KEY DA FRENTE DO DOCUMENTO\>",
		"document_identification_back": "\<DOCUMENT-KEY DA VERSO DO DOCUMENTO\>",
		"document_identification_type": "cnh",

如果文件以 1 个文件提交，同一文件中包含证件正面和背面（证件照片或电子驾照），则应在 /account 端点（1.2.2.）的 account_owner 对象中填写以下字段：

Request Body

		"document_identification": "\<DOCUMENT-KEY DA FRENTE DO DOCUMENTO\>",
		"document_identification_type": "cnh",

1.3.1.2. 提交 RG 类型身份证件

对于 RG 类型证件，必须始终提交 2 个文件，一个包含证件正面，另一个包含证件背面。在此情况下，应在 /account 端点（1.2.2.）的 account_owner 对象中填写以下字段：

Request Body

		"document_identification": "\<DOCUMENT-KEY DA FRENTE DO DOCUMENTO\>",
		"document_identification_back": "\<DOCUMENT-KEY DA VERSO DO DOCUMENTO\>",
		"document_identification_type": "rg",

Response

MÉTODO
POST
ENDPOINT
/account

Response Body

{
	"data": {
		"account_info": {
			"account_branch": "0001",
			"account_digit": "2",
			"account_number": "2359934",
			"financial_institution_code": "329"
		},
		"account_owner": {
            "document_number": "97564480084",
			"name": "Juliana Tereza Bernardes"
		}
	},
	"event_datetime": "2022-09-02 22:39:10",
	"key": "\<UUID PROPOSAL-KEY\>",
	"status": "pending_kyc_analysis",
	"webhook_type": "account"
}

重要

重要： 此响应中返回的 "key" 是开户申请的 PROPOSAL-KEY。应将其保存，以便读取开户 Webhook。

开户申请的响应始终返回状态 "pending_kyc_analysis"。系统将为该客户保留一个账号，但账户仍待 QI Tech 进行 KYC 分析。此时，账户尚未开通，无法接收或发送资金。

信息

在沙盒环境中，可使用账户 owner 的 CPF/CNPJ 第一位数字来模拟审批、拒绝和人工审核情况：

0 到 7 -> 人工审核
8 -> 自动拒绝
9 -> 自动审批

QI Tech 完成 KYC/PLD 分析后，将发送开户 Webhook，如下所示：

Webhook

WEBHOOK_TYPE
account
STATUS
Account Opened

Response Body

{
	"data": {
		"account_info": {
			"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
			"account_digit": "2",
			"account_branch": "0001",
			"account_number": "2359934",
			"financial_institution_code": "329"
		},
		"allowed_user": {
			"name": "Juliana Tereza Bernardes",
			"document_number": "97564480084"
		},
		"account_owner": {
			"name": "VOVO LUCIA CONVENIENCIA LTDA",
			"document_number": "09080702000105"
		}
	},
	"event_datetime": "2022-09-02 22:39:39",
	"key": "\<UUID PROPOSAL-KEY\>",
	"status": "account_opened",
	"webhook_type": "account"
}

此时将返回账户的 "account_key"，账户即可投入使用。

如果账户未通过 KYC/PLD 流程，将发送账户被拒绝的 Webhook：

Webhook

WEBHOOK_TYPE
account
STATUS
Account Rejected

Response Body

{
	"data": {
		"account_info": {
			"account_digit": "2",
			"account_branch": "0001",
			"account_number": "2359934",
			"financial_institution_code": "329"
		},
		"allowed_user": {
			"name": "Juliana Tereza Bernardes",
			"document_number": "97564480084"
		},
		"account_owner": {
			"name": "VOVO LUCIA CONVENIENCIA LTDA",
			"document_number": "09080702000105"
		}
	},
	"event_datetime": "2022-09-02 22:39:39",
	"key": "\<UUID PROPOSAL-KEY\>",
	"status": "account_rejected",
	"webhook_type": "account"
}

注意

allowed_user 属性仅在法人（PJ）开户 Webhook 中返回；对于个人（PF）账户，data 对象中仅返回 account_info 和 account_owner 属性。

1.3.2 开户条款签署

在开户 payload 中，须发送 signature_contract 字段，该字段应包含用户（账户持有人或主用户）接受开户条款时的设备扫描信息。

signed_contract 对象

字段	类型	描述	字符数
document_key *	uuidv4	开户条款或托管账户合同文件的唯一标识键。（DOCUMENT_KEY 在文件上传端点的响应中返回）	36
signatures *	list	所发送文件的签名数据。列表中的每一项对应一位签署人。	signatures 对象

signatures 对象

字段	类型	描述	字符数
authenticity *	object	证明签署人完成电子签名的数据集合。	authenticity 对象
signer *	object	包含某位文件签署人数据的对象。	signer 对象
authentication_type *	enumerator	签名类型。始终为 "opt-in"	"opt-in"

authenticity 对象

字段	类型	描述	字符数
timestamp *	string	文件签署时的日期和时间。	27
facial_recognition_key	uuidv4	账户持有人自拍照片的唯一标识键。（DOCUMENT_KEY 在文件上传端点的响应中返回）	36
lang	string	签署时捕获的签署人地理位置经度坐标。	-
lat	string	签署时捕获的签署人地理位置纬度坐标。	-
ip_address	string	签署人设备的 IP 地址。	-
session_id	string	签署时签署人的会话 ID。	-

signer 对象

字段	类型	描述	字符数
name *	string	签署人姓名。	-
email *	string	签署人邮箱。	-
phone *	object	包含签署人电话数据的对象	phone 对象
document_number *	string	签署人 CPF。	11

phone 对象

字段	描述	示例	最大字符数
`country_code` *	string	电话 DDI 代码 (https://ddi.guiamais.com.br/)	3
`area_code` *	string	电话 DDD 代码 (https://ddd.guiamais.com.br/)	2
`number` *	string	电话号码（仅数字）	10

1.4. 获取账户数据

Request

ENDPOINT
/account
MÉTODO
GET
PARAMETERS
account_type[checking], owner_name, account_number, owner_document_number, account_status[opened, closed, blocked], page, page_size

Response:

Response Body

{
	"data": [
		{
			"account_block_reason": null,
			"account_branch": "0001",
			"account_credentials": [{
					"account_id": 3395,
					"created_at": "2022-09-02T22:39:39",
					"credential_type": {
						"created_at": "2019-06-18T13:19:30",
						"enumerator": "observer",
						"id": 3,
						"translation_path": "account.CredentialType.observer"
					},
					"credential_type_id": 3,
					"id": 3244,
					"is_active": true,
					"person_key": "bffded45-5fcf-4d13-9d2a-566a0af338cc",
					"updated_at": null
				},
				{
					"account_id": 3395,
					"created_at": "2022-09-02T22:39:39",
					"credential_type": {
						"created_at": "2019-06-18T13:19:30",
						"enumerator": "requester",
						"id": 2,
						"translation_path": "account.CredentialType.requester"
					},
					"credential_type_id": 2,
					"id": 3245,
					"is_active": true,
					"person_key": "ef48fbe4-267b-45c1-9049-75345c075486",
					"updated_at": null
				}
			],
			"account_digit": "2",
			"account_documents": [],
			"account_events": [{
				"account_id": 3395,
				"created_at": "2022-09-02T22:39:39",
				"id": 5132,
				"new_account_status": {
					"created_at": "2019-10-11T18:58:31",
					"enumerator": "opened",
					"id": 1,
					"translation_path": "account.AccountStatus.opened"
				},
				"new_account_status_id": 1,
				"old_account_status": null,
				"old_account_status_id": null
			}],
			"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
			"account_name": "Default",
			"account_number": "2359934",
			"account_status": {
				"created_at": "2019-10-11T18:58:31",
				"enumerator": "opened",
				"translation_path": "account.AccountStatus.opened"
			},
			"account_type": {
				"created_at": "2019-03-15T13:09:15",
				"enumerator": "checking",
				"translation_path": "account.AccountType.checking"
			},
			"automatic_transfer_management_status": {
				"created_at": "2022-10-27T13:48:18",
				"enumerator": "master"
			},
			"automatic_transfers": [],
			"balance": 0,
			"blocked_balance": 0,
			"blocked_balance_events": [],
			"created_at": "2022-09-02T22:39:39",
			"destinations": [],
			"fee": 0,
			"internal_webhooks": [],
			"investment_available_amount": 0,
			"investment_configuration": null,
			"is_system_account": false,
			"owner_document_number": "09080702000105",
			"owner_name": "VOVO LUCIA CONVENIENCIA LTDA",
			"owner_person_key": "bffded45-5fcf-4d13-9d2a-566a0af338cc",
			"permitted_person_keys": [
				"bffded45-5fcf-4d13-9d2a-566a0af338cc",
				"bffded45-5fcf-4d13-9d2a-566a0af338cc",
				"ef48fbe4-267b-45c1-9049-75345c075486"
			],
			"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
			"requester_name": "Requester Name Sandbox",
			"setup_fee": null,
			"transactional_limit": null,
			"webhook_enabled": true
		}, ...
	],
	"pagination": {
		"current_page": 1,
		"next_page": null,
		"rows_per_page": 100,
		"total_pages": 1,
		"total_rows": 8
	}
}

信息

账户数据查询响应中最相关的字段为：account_branch、account_digit、account_key、account_number、balance、owner_document_number、owner_name、owner_person_key。

2 - PIX 转账

2.1. 执行 PIX 转账

执行 PIX 转账需进行三次调用：

创建转账请求：/baas/pix_transfer
申请转账验证令牌：/baas/token_request
批准转账：/baas/movement_validation

信息

PIX 转账可使用两种不同的 payload 完成：PIX 密钥或银行账户数据。

2.1.1. 创建转账请求

使用 PIX 密钥进行转账（CPF、CNPJ、电子邮件、手机号或随机密钥）

ENDPOINT
/baas/pix_transfer
MÉTODO
POST

Request Body

{
    "pix_transfer_type": "key",
    "source_account": {
        "account_branch": "0001",
        "account_digit": "2",
        "account_number": "2359934",
        "owner_document_number": "09080702000105"
    },
    "pix_key": "65322181032",
    "transaction_amount": 45,
    "requester_document_identification": "09080702000105"
}

信息

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

CPF： 11 位整数。

CNPJ： 14 位整数。

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

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

随机密钥： UUID。

使用银行账户数据进行转账（手动 PIX）

ENDPOINT
/baas/pix_transfer
MÉTODO
POST

Request Body

{
    "pix_transfer_type": "manual",
    "source_account": {
        "account_branch": "0001",
        "account_digit": "2",
        "account_number": "2359934",
        "owner_document_number": "09080702000105"
    },
    "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": 45
}

使用手动 PIX 时，需要提供目标机构的 ISPB。此数据之所以必要，是因为有些支付机构可以接收 PIX，但没有银行代码。ISPB 是机构 CNPJ 的前缀。要获取参与 PIX 的各机构完整 ISPB 列表，可使用我们文档中的查询端点：https://docs.qitech.com.br/reference/161-consulta-de-institui%C3%A7%C3%B5es-financeiras

Response Body

{
	"data": {
		"end_to_end_id": "E3240250220221120012039U3OKZZMW8",
		"fee_amount": 1,
		"pix_message": null,
		"pix_transfer_key": "cea836b5-b02e-4f94-b1e2-4d575671c33d",
		"source_account": {
			"account_brach": "0001",
			"account_digit": "2",
			"account_number": "2359934",
			"account_type": "checking",
			"owner_document_number": "09080702000105",
			"owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
		},
		"target_account": {
			"document_number": "***.221.81*-**",
			"financial_institution": "BANCO ORIGINAL S.A."
		},
		"transaction_amount": 45,
		"transfer_purpose": "transfer"
	},
	"event_datetime": "2022-09-02 22:20:47",
	"operation_key": "86d80cf4-430b-4e16-910a-41798810ddcf",
	"status": "pending_approval"
}

PIX 转账/付款申请的可能状态：

pending_approval： 转账待账户管理员用户（"allowed_user"）批准

sent： 转账已发送

注意

返回的 end_to_end_id 字段须保存，并在批准交易时提交。正是它来保障交易的唯一性。

完成第一次 "/baas/pix_transfer" 调用后，需要申请令牌以批准交易。要批准 PIX 转账，须使用转账申请中返回的 "pix_transfer_key"，并申请生成一个令牌，该令牌将发送给账户管理员用户（"allowed_user"）以供批准。

2.1.2. 申请转账验证令牌：

ENDPOINT
/baas/token_request
MÉTODO
POST

Request Body

{
    "contact_type": "sms",
    "agent_document_number": "97564480084",
    "movement_payload": {
        "pix_transfer_key": "cea836b5-b02e-4f94-b1e2-4d575671c33d",
        "approver_document_number": "97564480084"
    }
}

信息

contact_type： 是批准转账时将使用的双因素认证方式，可通过电子邮件（"email"）或短信（"sms"）进行。

信息

approver_document_number： 应填写将批准 PIX 转账的管理员用户的 CPF。

信息

agent_document_number： 此字段可填写将接收用于交易双因素批准令牌的主用户 CPF。

完成转账的最后一次调用是 "/baas/movement_validation"，收到的令牌须在批准 PIX 转账时提供。令牌的有效期为 2 分钟。

管理员用户须在合作伙伴应用中输入通过电子邮件或短信收到的令牌。

2.1.3. 批准转账：

ENDPOINT
/baas/movement_validation
MÉTODO
POST

Request Body

{
    "token": "248358",
    "movement_payload": {
        "pix_transfer_key": "cea836b5-b02e-4f94-b1e2-4d575671c33d",
        "approver_document_number": "97564480084"
    }
}

Reponse Body

{
	"authentication_code": "287c4478a1adcd6e820e654ac1b1edf2",
	"event_datetime": "2022-09-02 23:00:07",
	"operation_key": "05283f8e-b9c0-47ff-a06f-9626be710f69",
	"pix_transaction": {
		"end_to_end_id": "E3240250220221120012039U3OKZZMW8",
		"fee_amount": 1,
		"pix_message": null,
		"pix_transfer_key": "cea836b5-b02e-4f94-b1e2-4d575671c33d",
		"pix_transfer_status": "sent",
		"pix_transfer_type": "key",
		"source_account": {
			"account_branch": "0001",
			"account_digit": "2",
			"account_number": "2359934"
		},
		"target_account": {
			"document_number": "***.221.81*-**",
			"financial_institution": "BANCO ORIGINAL S.A."
		},
		"transaction_key": "d2ba3817-26d7-4957-ab82-24f78d910a8a",
		"transfer_amount": 45
	},
	"status": "sent"
}

STATUS

422

Response Body

{
  "data": "{\"title\": \"Pending Transfer\", \"description\": \"The transaction (<END TO END ID DO PIX>) could not be completed and is pending confirmation.\", \"translation\": \"Não foi possível concluir a transação (<END TO END ID DO PIX>) e ela está pendente de confirmação\", \"code\": \"PXT000072\"}"
}

HTTP Error 422

如果返回 http error 422，不得重新尝试 PIX 请求。需要通过 GET 请求 /baas/pix/pix_transfer 路由来检查 PIX 转账申请的状态。

2.2. PIX 到账 Webhook

Webhook

WEBHOOK_TYPE
account_transaction
SOURCE_SUB_TYPE
pix_withdrawal

Response Body

{
  "key": "508ebbba-0b1d-41f6-b9a2-975a4c2e925e",
  "data": {
    "amount": -45,
    "origin": {
      "name": "PIX",
      "branch": "0001",
      "document": "32402502000135",
      "account_key": "3d0e7d50-e898-49f3-b23b-05353c8a3c72",
      "account_digit": "3",
      "account_number": "00003"
    },
    "timestamp": "2023-01-05T18:16:03.395863",
    "description": "237 0001 1017372-2 ***.221.81*-** BANCO BRADESCO S.A.",
    "destination": {
      "name": "Default",
      "branch": "0001",
      "document": "23426525852",
      "account_key": "508ebbba-0b1d-41f6-b9a2-975a4c2e925e",
      "account_digit": "0",
      "account_number": "7058818"
    },
    "reference_key": "aafbf4bc-58eb-45fd-899c-af44f68dfd60",
    "reference_type": "pix_outgoing",
    "account_balance": 99359.15,
    "source_sub_type": "pix_withdrawal",
    "transaction_key": "3e37a0a9-d6d2-4474-8bff-5448e446c225",
    "source_sub_type_str": "Transferência de PIX"
  },
  "datetime": "2023-01-05T18:16:03.395863",
  "webhook_type": "account_transaction"
}

2.3. PIX 手续费扣收 Webhook

Webhook

WEBHOOK_TYPE
account_transaction
SOURCE_SUB_TYPE
pix_fee

Response Body

{
  "key": "508ebbba-0b1d-41f6-b9a2-975a4c2e925e",
  "data": {
    "amount": -0.85,
    "origin": {
      "name": "Fee Account",
      "branch": "0001",
      "document": "32402502000135",
      "account_key": "3679ffd0-d52e-4492-b11c-b11c655047d3",
      "account_digit": "8",
      "account_number": "00005"
    },
    "timestamp": "2023-01-05T18:16:03.554624",
    "description": "237 0001 1017372-2 ***.221.81*-** BANCO BRADESCO S.A.",
    "destination": {
      "name": "Default",
      "branch": "0001",
      "document": "23426525852",
      "account_key": "508ebbba-0b1d-41f6-b9a2-975a4c2e925e",
      "account_digit": "0",
      "account_number": "7058818"
    },
    "reference_key": "aafbf4bc-58eb-45fd-899c-af44f68dfd60",
    "reference_type": "pix_outgoing",
    "account_balance": 99358.3,
    "source_sub_type": "pix_fee",
    "transaction_key": "53c7421b-1340-4625-b383-b94d350ff9b2",
    "source_sub_type_str": "Tarifa de PIX"
  },
  "datetime": "2023-01-05T18:16:03.554624",
  "webhook_type": "account_transaction"
}

2.4. PIX 退款（Chargeback）

PIX 退款（Chargeback）分三个步骤完成：

1 - 发起 PIX Chargeback：/baas/pix_transfer
2 - 申请 PIX Chargeback 授权令牌：/baas/token_request
3 - 批准 PIX Chargeback：/baas/movement_validation

2.4.1. 发起 PIX Chargeback

Request

ENDPOINT

/baas/pix_transfer

MÉTODO

POST

Request Body

{
    "is_chargeback": true,
    "pix_transfer_key": "a180f2fb-0c7e-4708-b6a0-8d231770132e",
    "chargeback_amount": 100.46,
    "chargeback_message": "Mensagem de devolução"
}

信息

pix_transfer_key 是向 QI 账户入账的 PIX 的密钥，通过 account_transaction 的 Webhook 返回。

chargeback_amount 须小于或等于向 QI 账户入账的 PIX 金额。

Response

ENDPOINT

/baas/pix_transfer

MÉTODO

POST

Response Body

{
    "data": {
        "pix_transfer_key": "7a71e1f7-d8d1-4cf0-9243-c0b3837a3d26",
        "pix_transfer_status": "pending_approval",
        "pix_transfer_type": "chargeback",
        "target_account": {
            "document_number": "***45762***",
            "financial_institution": "ITAÚ UNIBANCO S.A."
        },
        "transfer_amount": 100.46
    },
    "event_datetime": "2023-04-28 18:19:30",
    "operation_key": "ab895342-988d-4d20-ba71-f82a7b9aad1b",
    "status": "pending_approval"
}

信息

调用中返回的 pix_transfer_key 是待批准的 PIX Chargeback 的参考密钥。

2.4.2. 申请 PIX Chargeback 授权令牌

ENDPOINT

/bass/token_request

MÉTODO

POST

Request Body

{
    "contact_type": "email",
    "movement_payload": {
        "pix_transfer_key": "7a71e1f7-d8d1-4cf0-9243-c0b3837a3d26",
        "approver_document_number": "97564480084"
    }
}

2.4.3. 批准 PIX Chargeback

ENDPOINT

/bass/movement_validation

MÉTODO

POST

Request Body

{
    "contact_type": "email",
    "movement_payload": {
        "pix_transfer_key": "7a71e1f7-d8d1-4cf0-9243-c0b3837a3d26",
        "approver_document_number": "97564480084"
    }
}

3 - TED 转账

信息

TED 转账只能在工作日 7:00 至 17:00 之间进行。

3.1. 执行 TED 转账

通过 TED 进行转账需进行以下调用：

申请转账验证令牌：/baas/token_request
批准转账：/baas/movement_validation

Request

ENDPOINT
/baas/token_request
MÉTODO
POST

Request Body

{
	"contact_type": "sms",
	"agent_document_number": "97564480084",
	"movement_payload": {
		"source_account": {
			"account_branch": "0001",
			"account_number": "9477323",
			"account_digit": "0",
			"owner_document_number": "38299588000107"
		},
		"target_account": {
			"financial_institution_code": "341",
			"account_branch": "0001",
			"account_number": "4311337",
			"account_digit": "1",
			"owner_document_number": "21669721019",
			"owner_name": "Nome do Titular da Conta Destino"
		},
		"transaction_amount": 8.86
	}
}

收到的令牌须在批准 TED 转账时提供，且 "movement_payload" 须与申请令牌时提供的内容相同。

Request

ENDPOINT
/baas/movement_validation
MÉTODO
POST

Request Body

{
	"token": "329329",
	"agent_document_number": "99999999999",
	"movement_payload": {
		"source_account": {
			"account_branch": "0001",
			"account_number": "0000000",
			"account_digit": "0",
			"owner_document_number": "99999999000107"
		},
		"target_account": {
			"financial_institution_code": "341",
			"account_branch": "0001",
			"account_number": "0000000",
			"account_digit": "1",
			"owner_document_number": "999999999",
			"owner_name": "Nome do Titular da Conta Destino"
		},
		"transaction_amount": 8.86,
        "approver_document_number": "999999999"
	}
}

Response

MÉTODO
POST
ENDPOINT
/baas/movement_validation

Response Body

{
	"authentication_code": "e8f0fffaeb4ebad2df0417194fe6a9e5",
	"origin_key": "d07f77f9-f157-4c35-a26b-567cba59e385",
	"pdf_encoded_string": "\<BASE 64 DO COMPROVANTE\>",
	"source_account": {
		"account_branch": "0001",
		"account_digit": "2",
		"account_number": "2359934",
		"financial_institution_compe_number": 329,
		"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
		"owner_document_number": "09080702000105",
		"owner_document_number_formatted": "09.080.702/0001-05",
		"owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
	},
	"source_subtype": "withdrawal",
	"source_subtype_translation_ptbr": "Transferência",
	"target_account": {
		"account_branch": "0001",
		"account_digit": "1",
		"account_number": "81156",
		"account_type": "checking_account",
		"account_type_str": "Conta Corrente",
		"financial_institution_compe_number": "001",
		"financial_institution_name": "Banco do Brasil S.A.",
		"owner_document_number": "10932327656",
		"owner_document_number_formatted": "109.323.276-56",
		"owner_name": "Lucas de Jesus Clarim"
	},
	"transacted_at": "2022-09-02 14:39:56",
	"transacted_at_br": "2022-09-02 11:39:56",
	"transacted_at_br_formatted": "21/11/2022, 11:39:56",
	"transacted_at_formatted": "21/11/2022, 14:39:56",
	"transaction_amount": 550,
	"transaction_amount_formatted": "R$ 550,00",
	"transaction_key": "32ac0781-f292-4172-b58f-3310102e6fb9"
}

信息

"transacted_at" 字段采用 UTC 格式。

信息

"transaction_key" 将在后续申请转账凭证时使用。

3.2. TED 到账确认

Webhook

WEBHOOK_TYPE
account_transaction
SOURCE_SUB_TYPE
withdrawal

Response Body

{
  "key": "508ebbba-0b1d-41f6-b9a2-975a4c2e925e",
  "data": {
    "amount": -550,
    "origin": {
      "name": "TED",
      "branch": "0001",
      "document": "32402502000135",
      "account_key": "23a4a2c8-9d82-4ebe-a90d-44fe8d839ec0",
      "account_digit": "7",
      "account_number": "00001"
    },
    "timestamp": "2023-01-05T07:35:37.127502",
    "description": "001 0001 81156-1 32.402.502/0001-35 - QI Tech",
    "destination": {
      "name": "Default",
      "branch": "0001",
      "document": "23426525852",
      "account_key": "508ebbba-0b1d-41f6-b9a2-975a4c2e925e",
      "account_digit": "0",
      "account_number": "7058818"
    },
    "reference_key": "58729e67-f490-4607-aafd-2fc7945d3d77",
    "reference_type": "ted_outgoing",
    "account_balance": 99404.15,
    "source_sub_type": "withdrawal",
    "transaction_key": "4ac9e80b-22d9-4097-8676-e19f84c89543",
    "source_sub_type_str": "Transferência"
  },
  "datetime": "2023-01-05T07:35:37.127502",
  "webhook_type": "account_transaction"
}

3.3. TED 退款

Webhook

WEBHOOK_TYPE
account_transaction
SOURCE_SUB_TYPE
withdrawal_reversal

Response Body

{
  "key": "508ebbba-0b1d-41f6-b9a2-975a4c2e925e",
  "data": {
    "amount": 550,
    "origin": {
      "name": "TED",
      "branch": "0001",
      "document": "32402502000135",
      "account_key": "23a4a2c8-9d82-4ebe-a90d-44fe8d839ec0",
      "account_digit": "7",
      "account_number": "00001"
    },
    "timestamp": "2023-01-05T07:42:26.631137",
    "description": "001 0001 81156-1 32.402.502/0001-35 - QI Tech",
    "destination": {
      "name": "Default",
      "branch": "0001",
      "document": "23426525852",
      "account_key": "508ebbba-0b1d-41f6-b9a2-975a4c2e925e",
      "account_digit": "0",
      "account_number": "7058818"
    },
    "reference_key": "58729e67-f490-4607-aafd-2fc7945d3d77",
    "reference_type": "ted_outgoing",
    "account_balance": 99954.15,
    "source_sub_type": "withdrawal_reversal",
    "transaction_key": "53268774-6891-42a4-a658-42e21cef867c",
    "source_sub_type_str": "Estorno de Transferência"
  },
  "datetime": "2023-01-05T07:42:26.631137",
  "webhook_type": "account_transaction"
}

4 - PIX QR Code 付款

4.1. 支付静态 PIX QR Code

支付静态 PIX QR Code 需进行四次调用：

解码 PIX QR Code：/baas/pix/qrcode
创建转账请求：/baas/pix_transfer
申请转账验证令牌：/baas/token_request
批准转账：/baas/movement_validation

解码静态 PIX QR Code 所需的信息是与 QR Code 关联的 PIX 复制粘贴 URI。

信息

PIX 复制粘贴 URI 示例： 00020126580014br.gov.bcb.pix01360598e5d1-2cfc-4857-abf8-12d495aa0a6d52040000530398654040.225802BR5925VOVO LUCIA CONVENIENCIA L6009sao paulo610912345-78062070503***63043A5A

Request

ENDPOINT
/baas/pix/qrcode
MÉTODO
POST

Reponse Body

{
    "qr_code_payload": "\<URI DO PIX COPIA E COLA\>"
}

Response

MÉTODO
POST
ENDPOINT
/baas/pix/qrcode

Response Body

{
	"end_to_end_id": "E3240250220221120030008388062101",
	"qr_code_data": {
		"additional_data": null,
		"amount": 30,
		"ispb_number": "32402502",
		"receiver_conciliation_id": "***",
		"target_account_branch": "0001",
		"target_account_digit": "5",
		"target_account_number": "2",
		"target_account_type": "checking",
		"target_bank_code": 329,
		"target_bank_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
		"target_document_number": "32402502000135",
		"target_name": "QI SOCIEDADE DE CREDITO DIRETO S.A.",
		"target_person_type": "legal",
		"target_pix_key": "316bd44f-2202-4c33-9dc0-096192acd427"
	},
	"qr_code_key": "1608e022-e42d-49d8-bacf-da5844570635",
	"qr_code_payload": "00020126580014br.gov.bcb.pix0136316bd44f-2202-4c33-9dc0-096192acd427520400005303986540530.005802BR5925QI SOCIEDADE DE CREDITO D6009sao paulo610912345-78062070503***63048698",
	"qr_code_type": "static"
}

注意

支付静态 PIX QR Code 的请求与 PIX 转账请求相同，但有以下变化： 1 - 新增 "end_to_end_id" 字段。须填写静态 QR Code 解码返回的相同值；

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

3 - 将 "pix_transfer_type" 字段改为 "static"，以通过 "/baas/pix_transfer" 发起付款请求。

Request

MÉTODO
POST
ENDPOINT
/baas/pix_transfer

Request Body

{
    "pix_transfer_type": "static",
    "source_account": {
        "account_branch": "0001",
        "account_digit": "2",
        "account_number": "2359934",
        "owner_document_number": "09080702000105"
    },
    "end_to_end_id": "E3240250220221118200949955075000",
    "transaction_amount": 30,
	"pix_key": "316bd44f-2202-4c33-9dc0-096192acd427",
    "requester_document_identification": "09080702000105"
}

Response

MÉTODO
POST
ENDPOINT
/baas/pix_transfer

Response Body

{
	"data": {
		"end_to_end_id": "E3240250220221118200949955075000",
		"fee_amount": 1,
		"pix_message": null,
		"pix_transfer_key": "59a0da26-3223-4679-aa2c-020d46e923c1",
		"source_account": {
			"account_brach": "0001",
			"account_digit": "2",
			"account_number": "2359934",
			"account_type": "checking",
			"owner_document_number": "09080702000105",
			"owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
		},
		"target_account": {
			"document_number": "32402502000135",
			"financial_institution": "QI SOCIEDADE DE CRÉDITO DIRETO S.A."
		},
		"transaction_amount": 30,
		"transfer_purpose": "transfer"
	},
	"event_datetime": "2022-09-02 23:00:07",
	"operation_key": "527f60a4-0118-4b90-adf8-d33f895c9f8f",
	"status": "pending_approval"
}

完成第二次 "/baas/pix_transfer" 端点调用后，需要申请令牌以批准交易。要批准 PIX 转账，须使用转账申请中返回的 "pix_transfer_key"，并申请生成一个令牌，该令牌将发送给账户管理员用户（"allowed_user"）以供批准。

Request

MÉTODO
POST
ENDPOINT
/baas/token_request

Request Body

{
    "contact_type": "sms",
    "agent_document_number": "97564480084",
    "movement_payload": {
        "pix_transfer_key": "59a0da26-3223-4679-aa2c-020d46e923c1",
        "approver_document_number": "97564480084"
    }
}

完成付款的最后一次调用是 "/baas/movement_validation"，收到的令牌须在批准 PIX 转账时提供。令牌的有效期为 2 分钟。管理员用户须在合作伙伴应用中输入通过电子邮件或短信收到的令牌。

Request

MÉTODO
POST
ENDPOINT
/baas/movement_validation

Request Body

{
    "token": "957219",
    "movement_payload": {
        "pix_transfer_key": "59a0da26-3223-4679-aa2c-020d46e923c1",
        "approver_document_number": "97564480084"
    }
}

Response

MÉTODO
POST
ENDPOINT
/baas/movement_validation

Response Body

{
	"authentication_code": "4c579663bd3f369c4f5f5cd89d8e1a24",
	"event_datetime": "2022-09-02 23:00:07",
	"operation_key": "527f60a4-0118-4b90-adf8-d33f895c9f8f",
	"pix_transaction": {
		"end_to_end_id": "E3240250220221118200949955075000",
		"fee_amount": 1,
		"pix_message": null,
		"pix_transfer_key": "59a0da26-3223-4679-aa2c-020d46e923c1",
		"pix_transfer_status": "sent",
		"pix_transfer_type": "static",
		"source_account": {
			"account_branch": "0001",
			"account_digit": "2",
			"account_number": "2359934"
		},
		"target_account": {
			"document_number": "***.221.81*-**",
			"financial_institution": "BANCO ORIGINAL S.A."
		},
		"transaction_key": "d5134c23-18d2-4279-bc99-459312b64bfc",
		"transfer_amount": 30
	},
	"status": "sent"
}

信息

此响应与 PIX 转账批准响应的唯一区别，是 "pix_transfer_type" 字段的值，此处返回为 "static"。

4.2. 支付动态 PIX QR Code

支付动态 PIX QR Code 需进行四次调用：

解码 PIX QR Code：/baas/pix/qrcode
创建转账请求：/baas/pix_transfer
申请转账验证令牌：/baas/token_request
批准转账：/baas/movement_validation。解码动态 PIX QR Code 所需的信息是与 QR Code 关联的 PIX 复制粘贴 URI。

信息

静态 PIX QR Code 和动态 PIX QR Code 在 "/baas/pix/qrcode" 中的唯一区别是端点的响应。

Response

MÉTODO
POST
ENDPOINT
/baas/pix/qrcode

Response Body

{
	"end_to_end_id": "E3240250220221120162904592385040",
	"qr_code_data": {
		"account_type": "checking",
		"additional_data": [],
		"address": "Avenida Brigadeiro Faria Lima",
		"amount": 35,
		"category_code": "0000",
		"city": "Sao Paulo",
		"created_at": "2022-09-01T20:20:11",
		"days_after_due_accepted": 180,
		"discount_amount": null,
		"due_date": "2022-11-30",
		"fee_amount": null,
		"fine_amount": null,
		"ispb_number": "32402502",
		"original_amount": null,
		"payer_document_number": "10932327656",
		"payer_name": "Payer Name",
		"payer_person_type": "natural",
		"postal_code": "01452000",
		"presented_at": "2022-09-01T16:29:04",
		"question_to_payer": "QR Code Payment",
		"receiver_conciliation_id": "a6c3f35b342047e58ac105a0ae0c0c6f",
		"receiver_url": null,
		"reduction_amount": null,
		"reusable_qrcode": "yes",
		"revision": 1,
		"state": "SP",
		"status": "active",
		"target_account_branch": "0001",
		"target_account_digit": "5",
		"target_account_number": "2",
		"target_bank_code": 329,
		"target_bank_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
		"target_document_number": "32402502000135",
		"target_name": "QI SOCIEDADE DE CREDITO DIRETO S.A.",
		"target_person_type": "legal",
		"target_pix_key": "316bd44f-2202-4c33-9dc0-096192acd427",
		"target_trading_name": null
	},
	"qr_code_key": "a1bcf9be-918d-431e-ae79-a75f78337423",
	"qr_code_payload": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/a6c3f35b-3420-47e5-8ac1-05a0ae0c0c6f5204000053039865802BR5902QI6009Sao Paulo61080145200062070503***6304AFEE",
	"qr_code_type": "dynamic_term"
}

注意

支付动态 PIX QR Code 的请求与 PIX 转账请求相同，但有以下变化：

1 - 新增 "end_to_end_id" 字段。须填写动态 QR Code 解码返回的相同值。 2 - 在 "transaction_amount" 字段中填写动态 QR Code 解码时 "qr_code_data.amount" 字段返回的相同值； 3 - 将 "pix_transfer_type" 字段改为 "dynamic_term"，以通过 "/baas/pix_trasnfer" 发起付款请求。 4 - 新增 "receiver_conciliation_id" 字段。须填写动态 QR Code 解码返回的相同值。

Request

MÉTODO
POST
ENDPOINT
/baas/pix_transfer

Response Body

{
    "pix_transfer_type": "dynamic_term",
    "source_account": {
        "account_branch": "0001",
        "account_digit": "2",
        "account_number": "2359934",
        "owner_document_number": "09080702000105"
    },
    "end_to_end_id": "E3240250220221120162904592385040",
    "receiver_conciliation_id": "a6c3f35b342047e58ac105a0ae0c0c6f",
    "transaction_amount": 35,
    "requester_document_identification": "09080702000105"
}

Response

MÉTODO
POST
ENDPOINT
/baas/pix_transfer

Response Body

{
	"data": {
		"end_to_end_id": "E3240250220221120162904592385040",
		"fee_amount": 0,
		"pix_message": null,
		"pix_transfer_key": "8ddd3bce-5130-4b5b-b7f1-40f17547a413",
		"source_account": {
			"account_brach": "0001",
			"account_digit": "2",
			"account_number": "2359934",
			"account_type": "checking",
			"owner_document_number": "09080702000105",
			"owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
		},
		"target_account": {
			"document_number": "32402502000135",
			"financial_institution": "QI SOCIEDADE DE CRÉDITO DIRETO S.A."
		},
		"transaction_amount": 35,
		"transfer_purpose": "transfer"
	},
	"event_datetime": "2022-09-02 13:45:44",
	"operation_key": "c697d8d8-4520-4285-b5ec-d573fb6c1eb3",
	"status": "pending_approval"
}

Request

MÉTODO
POST
ENDPOINT
/baas/token_request

Response Body

{
    "contact_type": "sms",
    "agent_document_number": "97564480084",
    "movement_payload": {
        "pix_transfer_key": "8ddd3bce-5130-4b5b-b7f1-40f17547a413",
        "approver_document_number": "97564480084"
    }
}

Request

MÉTODO
POST
ENDPOINT
/baas/movement_validation

Response Body

{
    "token": "231564",
    "movement_payload": {
        "pix_transfer_key": "8ddd3bce-5130-4b5b-b7f1-40f17547a413",
        "approver_document_number": "97564480084"
    }
}

Response

MÉTODO
POST
ENDPOINT
/baas/movement_validation

Response Body

{
	"authentication_code": "936c01a20ebf73c6d474a14bc32553b0",
	"event_datetime": "2022-09-02 23:00:07",
	"operation_key": "c697d8d8-4520-4285-b5ec-d573fb6c1eb3",
	"pix_transaction": {
		"end_to_end_id": "E3240250220221120162904592385040",
		"fee_amount": 1,
		"pix_message": null,
		"pix_transfer_key": "8ddd3bce-5130-4b5b-b7f1-40f17547a413",
		"pix_transfer_status": "sent",
		"pix_transfer_type": "dynamic_term",
		"source_account": {
			"account_branch": "0001",
			"account_digit": "2",
			"account_number": "2359934"
		},
		"target_account": {
			"document_number": "***.221.81*-**",
			"financial_institution": "BANCO ORIGINAL S.A."
		},
		"transaction_key": "96e063f4-b1fb-4f93-ae30-906029764a0a",
		"transfer_amount": 35
	},
	"status": "sent"
}

信息

此响应与 PIX 转账批准响应的唯一区别，是 "pix_transfer_type" 字段的值，此处返回为 "dynamic_term"。

5 - 管理 PIX 密钥

信息

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

CPF： 11 位整数。

CNPJ： 14 位整数。

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

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

随机密钥： UUID。

5.1. 创建 CPF、CNPJ 或随机 PIX 密钥

要创建 CNPJ PIX 密钥或随机密钥，只需调用 "/baas/pix/keys" 端点，将 "pix_key_type" 更改为 "cnpj"、"cpf" 或 "random_key"。

Request

MÉTODO
POST
ENDPOINT
/baas/pix/keys

Request Body

{
    "account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
    "pix_key_type": "random_key"
}

或

Request Body

{
    "account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
    "pix_key_type": "cnpj",
    "pix_key": "09080702000105"
}

或

payload.json

{
    "account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
    "pix_key_type": "cpf",
    "pix_key": "03882617038"
}

Response

MÉTODO
POST
ENDPOINT
/baas/pix/keys

Response Body

{
	"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
	"created_at": "2022-09-02T18:20:52",
	"pix_key": {
		"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
		"created_at": "2022-09-02T18:20:51",
		"pix_key": "09080702000105",
		"pix_key_status": "pending_confirmation",
		"pix_key_type": "cnpj",
		"updated_at": "2022-09-02T18:20:51"
	},
	"pix_key_request_key": "d60abf67-ad9c-42ee-9089-d26c8fc855b9",
	"request_data": {
		"account_created_at": "2022-09-02T22:44:36",
		"account_digit": "2",
		"account_number": "2359934",
		"account_type": "checking",
		"branch_number": "0001",
		"key": "09080702000105",
		"owner_document_number": "09080702000105",
		"owner_name": "VOVO LUCIA CONVENIENCIA LTDA",
		"owner_person_type": "legal",
		"trading_name": "VOVO LUCIA"
	},
	"request_failure_reason": null,
	"request_status": "pending",
	"request_type": "inclusion",
	"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
	"updated_at": "2022-09-02T18:20:52"
}

注意

对于创建随机 PIX 密钥的响应，"pix_key" 字段将返回空值，因为这是一个由巴西中央银行生成密钥的异步过程。要获取已生成的随机密钥值，需要查询账户中已注册的密钥列表（如"查询账户中已注册的 PIX 密钥"条目所述），或等待 inclusion Webhook。

信息

由于验证 CNPJ 或 CPF PIX 密钥是否激活是异步过程，需要查询账户中已注册的密钥列表（如"查询账户中已注册的 PIX 密钥"条目所述），或等待 inclusion Webhook。

Webhook

WEBHOOK_TYPE
key_inclusion

Response Body

{
	"pix_key": "c232142c-ddbf-41d6-a54f-3b90c28b97dc",
	"account_key": "94945886-7a6f-43e6-a307-e36c959e4903",
	"webhook_type": "key_inclusion",
	"pix_key_status": "active",
	"pix_key_request_key": "e274eb13-40b3-4902-978e-8e5fa267af53",
	"pix_key_request_type": "inclusion",
	"pix_key_request_status": "approved"
}

5.2. 创建电子邮件和手机号 PIX 密钥

要创建电子邮件或手机号 PIX 密钥，须调用两个端点：

1 - 创建密钥： POST 请求 "/baas/pix/keys" 端点，将 "pix_key_type" 字段改为 "email" 或 "phone_number"。此时，将向 "pix_key" 字段中填写的电子邮件或手机号发送令牌。

2 - 批准密钥： PATCH 请求 "/baas/pix/keys/<pix_key_request_key>" 端点，填写上一步收到的令牌。

Request

MÉTODO
POST
ENDPOINT
/baas/pix/keys

Request Body

{
    "account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
    "pix_key_type": "email",
    "pix_key": "vovo.lucia@gmail.com.br"
}

或

Request Body

{
    "account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
    "pix_key_type": "phone_number",
    "pix_key": "+5511987654321"
}

Response

MÉTODO
POST
ENDPOINT
/baas/pix/keys

Response Body

{
	"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
	"created_at": "2022-09-02T17:41:55",
	"pix_key": {
		"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
		"created_at": "2022-09-02T17:41:54",
		"pix_key": "pedro.pinho@qitech.com.br",
		"pix_key_status": "pending_confirmation",
		"pix_key_type": "email",
		"updated_at": "2022-09-02T17:41:54"
	},
	"pix_key_request_key": "f6209b7e-82da-44a8-9cfa-6ad0a689adb2",
	"request_data": {
		"account_created_at": "2022-09-02T22:44:36",
		"account_digit": "2",
		"account_number": "2359934",
		"account_type": "checking",
		"branch_number": "0001",
		"key": "pedro.pinho@qitech.com.br",
		"owner_document_number": "09080702000105",
		"owner_name": "VOVO LUCIA CONVENIENCIA LTDA",
		"owner_person_type": "legal",
		"trading_name": "VOVO LUCIA"
	},
	"request_failure_reason": null,
	"request_status": "pending",
	"request_type": "inclusion",
	"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
	"updated_at": "2022-09-02T17:41:55"
}

重要： "pix_key_request_key" 字段返回的值须在请求 URL 中用于批准 PIX 密钥创建。

5.3. 批准已申请的电子邮件或手机号 PIX 密钥

Request

MÉTODO
PATCH
ENDPOINT
/baas/pix/keys/PIX_KEY_REQUEST_KEY/twofa_validation

Request Body

{
    "verification_code": "756816"
}

5.4. 重新发送验证码

Request

MÉTODO
PATCH
ENDPOINT
/baas/pix/keys/PIX_KEY_REQUEST_KEY/resend_twofa

payload.json

{}

5.5. 查询账户中已注册的 PIX 密钥

Request

MÉTODO
GET
ENDPOINT
/baas/pix/keys
PARAMETERS
account_key

Response

Response Body

{
  "data": [
    {
      "account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
      "created_at": "2022-09-02T17:17:31",
      "pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
      "pix_key_status": "active",
      "pix_key_type": "random_key",
      "updated_at": "2022-09-02T17:17:31"
    },
    {
      "account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
      "created_at": "2022-09-02T18:20:51",
      "pix_key": "09080702000105",
      "pix_key_status": "active",
      "pix_key_type": "cnpj",
      "updated_at": "2022-09-02T18:20:51"
    }
  ]
}

5.6. 删除 PIX 密钥

Request

MÉTODO
DELETE
ENDPOINT
/baas/pix/keys/PIX-KEY

Payload:

Response

Response Body

{
	"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
	"created_at": "2022-09-02T20:00:36",
	"pix_key": {
		"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
		"created_at": "2022-09-02T18:20:51",
		"pix_key": "09080702000105",
		"pix_key_status": "inactivated",
		"pix_key_type": "cnpj",
		"updated_at": "2022-09-02T20:00:36"
	},
	"pix_key_request_key": "dced4317-c1e7-4da4-a75a-42f855c7598e",
	"request_data": {},
	"request_failure_reason": null,
	"request_status": "approved",
	"request_type": "deletion",
	"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
	"updated_at": "2022-09-02T20:00:36"
}

6 - 生成 PIX QR Code

6.1. 生成静态 PIX QR Code

QR Code 从账户中已注册的有效 PIX 密钥创建。生成 QR Code 后，将返回与 QR Code 关联的 PIX 复制粘贴 URI，以及 QR Code 图片的 base64（如有请求）。

QR Code 图片也可由合作伙伴使用 PIX 复制粘贴 URI 自行生成。

生成静态 PIX QR Code 只需一个请求：

Request

MÉTODO
POST
ENDPOINT
/baas/qrcode/static

Request Body

{
    "pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
    "amount": 35.00,
    "receiver_name": "Tywin Lannister",
    "qr_code_format": "both"
}

信息

qr_code_format 字段可填写 "image"、"payload" 和 "both"。

"image"：返回包含 PIX QR Code 图片 base64 的字段。
"payload"：返回包含 PIX QR Code 复制粘贴 URI base64 的字段。
"both"：返回以上两个字段。

Response

MÉTODO
POST
ENDPOINT
/baas/qrcode/static

Response Body

{
    "external_reference_key": null,
    "image": "\<BASE 64 DO QR CODE PIX\>",
    "payload": "MDAwMjAxMjY0NzAwMTRici5nb3YuYmNiLnBpeDAxMjVwZWRyby5waW5ob0BxaXRlY2guY29tLmJyNTIwNDAwMDA1MzAzOTg2NTQwNTM1LjAwNTgwMkJSNTkxNVR5d2luIExhbm5pc3RlcjYwMDlzYW8gcGF1bG82MTA5MTIzNDUtNzgwNjIwNzA1MDMqKio2MzA0M0QzMA",
    "revision": null
}

6.2. 生成动态 PIX QR Code

动态 QR Code 有两种类型：即时付款动态 QR Code 和到期日动态 QR Code。

6.2.1. 生成带到期日的动态 PIX QR Code

这是一种功能与银行票据（boleto）非常相似的 PIX QR Code 类型，可包含到期日、滞纳金、逾期利息和提前付款折扣等信息。生成此类 PIX QR Code 只需向 "/baas/qrcode/dynamic" 端点发起一个请求。

Request

MÉTODO
POST
ENDPOINT
/baas/qrcode/dynamic

Request Body

{
	"amount": 100,
	"qr_code_type": "dynamic_term",
	"occurrence_type": "registration",
	"max_payment_days": 180,
	"expiration_date": "2025-09-24",
	"pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
	"payer_name": "QI Tech",
	"payer_document_number": "98765432100",
	"payer_person_type": "natural",
	"payer_request": "O que voce achou da experiencia",
	"rebate_amount": 0,
	"interest_amount": 1,
	"fine_amount": 2,
	"discounts": [{
		"limit_date": "2023-02-24",
		"amount": 20,
		"discount_type": "absolute"
	}],
	"additional_data": [{
		"\<tag_name\>": "\<tag_value\>"
	}]
}

信息

occurrence_type： 此字段填写预期操作。可选值：registration、edit、write_off

registration： 创建新 QR Code
edit： 编辑已有 QR Code（如下方条目所述）。
write_off： 注销已激活的 QR Code。

interest_amount： 每日逾期利息金额（巴西雷亚尔 R$）。

fine_amount： 逾期罚款金额（巴西雷亚尔 R$）。

discounts： 提前付款折扣信息。如不适用，请发送空列表（[]）。

additional_data： 可自定义的元标签，可在付款时向付款方展示。格式如下："<tag_name>": "<tag_value>"。

tag_name 最多 100 个字符，tag_value 最多 320 个字符。

Response

MÉTODO
POST
ENDPOINT
/baas/qrcode/dynamic

Response Body

{
	"qr_code_type": "dynamic_term",
	"amount": 100,
	"expiration_seconds": null,
	"max_payment_days": 180,
	"receiver_conciliation_id": "3bd19ada234141bf9f1fc5ce0b216723",
	"payer_name": "QI Tech",
	"payer_document_number": "98765432100",
	"payer_person_type": "natural",
	"payer_request": "O que voce achou da experiencia",
	"pix_message": null,
	"modality_alteration": false,
	"expiration_date": "2025-09-24",
	"rebate_amount": 10,
	"interest_amount": 10,
	"fine_amount": 10,
	"paid_amount": null,
	"discounts": [{
		"discount_type": "absolute",
		"limit_date": "2023-02-24",
		"amount": 20
	}],
	"additional_data": [{
		"\<tag_name\>": "\<tag_value\>"
	}],
	"origin": "system",
	"origin_key": null,
	"pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
	"qr_code_key": "3bd19ada-2341-41bf-9f1f-c5ce0b216723",
	"occurrence_type": "registration",
	"end_to_end_id": null,
	"base_64": "MDAwMjAxMjY5NzAwMTRici5nb3YuYmNiLnBpeDI1NzVxcmNvZGUtaC5zYW5kYm94LnFpdGVjaC5hcHAvYmFjZW4vY29idi8zYmQxOWFkYS0yMzQxLTQxYmYtOWYxZi1jNWNlMGIyMTY3MjM1MjA0MDAwMDUzMDM5ODY1ODAyQlI1OTI1Vk9WTyBMVUNJQSBDT05WRU5JRU5DSUEgTDYwMDdMaW1laXJhNjEwODEzNDgwMjkwNjIwNzA1MDMqKio2MzA0QzNGNg",
	"image": "\<BASE 64 DO QR CODE PIX\>",
	"source_account_branch": null,
	"source_account_financial_institution": null,
	"source_account_ispb": null,
	"source_account_number": null,
	"source_account_digit": null,
	"qr_code_occurrence_key": "b6777e78-e00c-4e9f-9b44-aa7b551c11e4"
}

信息

"base_64"字段是与此动态 PIX QR Code 关联的 PIX 复制粘贴 URI。

6.2.2. 生成即时支付动态 PIX QR Code

这是一种类似于静态 QR Code 的 PIX QR Code 类型，但便于收款方进行对账，并且可以设置当日到期（例如，有效期仅为 5 分钟）。要生成此类 PIX QR Code，只需向端点 "/baas/qrcode/dynamic" 发起一次请求。

请求（Request）

方法
POST
端点
/baas/qrcode/dynamic

Request Body

{
	"amount": 100,
	"occurrence_type": "registration",
	"qr_code_type": "dynamic_instant",
	"pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
	"expiration_seconds": 360,
	"payer_name": "QI Tech",
	"payer_document_number": "98765432100",
	"payer_person_type": "natural",
	"payer_request": "Valor referente a compra 1234",
	"additional_data": [{
		"\<tag_name\>": "\<tag_value\>"
	}]
}

响应（Response）

方法
POST
端点
/baas/qrcode/dynamic

Response Body

{
	"qr_code_type": "dynamic_instant",
	"amount": 100,
	"expiration_seconds": 360,
	"max_payment_days": null,
	"receiver_conciliation_id": "8e5af204fa5844eca9707c4facc5e5f5",
	"payer_name": "QI Tech",
	"payer_document_number": "98765432100",
	"payer_person_type": "natural",
	"payer_request": "Valor referente a compra 1234",
	"pix_message": null,
	"modality_alteration": false,
	"expiration_date": null,
	"rebate_amount": null,
	"interest_amount": null,
	"fine_amount": null,
	"paid_amount": null,
	"discounts": [],
	"additional_data": [{
		"\<tag_name\>": "\<tag_value\>"
	}],
	"origin": "system",
	"origin_key": null,
	"pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
	"qr_code_key": "8e5af204-fa58-44ec-a970-7c4facc5e5f5",
	"occurrence_type": "registration",
	"end_to_end_id": null,
	"base_64": "MDAwMjAxMjY4ODAwMTRici5nb3YuYmNiLnBpeDI1NjZxcmNvZGUtaC5zYW5kYm94LnFpdGVjaC5hcHAvYmFjZW4vOGU1YWYyMDRmYTU4NDRlY2E5NzA3YzRmYWNjNWU1ZjU1MjA0MDAwMDUzMDM5ODY1ODAyQlI1OTI1Vk9WTyBMVUNJQSBDT05WRU5JRU5DSUEgTDYwMDdMaW1laXJhNjEwODEzNDgwMjkwNjIwNzA1MDMqKio2MzA0M0RBRA",
	"image": "\<BASE 64 DO QR CODE PIX\>",
	"source_account_branch": null,
	"source_account_financial_institution": null,
	"source_account_ispb": null,
	"source_account_number": null,
	"source_account_digit": null,
	"qr_code_occurrence_key": "838e4bd3-36c9-4aa8-9be8-04079bbe8d1a"
}

6.2.3. 编辑动态 PIX QR Code 数据

要编辑动态 PIX QR Code 的数据，需要提供 QR Code 的 "qr_code_key" 并将 "occurrence_type" 设置为 "edit"。在此情况下，需要重新发送所有数据。

请求（Request）

方法
POST
端点
/baas/qrcode/dynamic

Request Body

{
    "qr_code_key": "3bd19ada-2341-41bf-9f1f-c5ce0b216723",
	"amount": 200,
	"qr_code_type": "dynamic_term",
	"occurrence_type": "edit",
	"max_payment_days": 180,
	"expiration_date": "2025-09-24",
	"pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
	"payer_name": "QI Tech",
	"payer_document_number": "98765432100",
	"payer_person_type": "natural",
	"payer_request": "O que voce achou da experiencia",
	"rebate_amount": 0,
	"interest_amount": 1,
	"fine_amount": 2,
	"discounts": [{
		"limit_date": "2023-02-24",
		"amount": 20,
		"discount_type": "absolute"
	}],
	"additional_data": [{
		"\<tag_name\>": "\<tag_value\>"
	}]
}

请求（Request）

方法
POST
端点
/baas/qrcode/dynamic

Response Body

{
	"qr_code_type": "dynamic_term",
	"amount": 200,
	"expiration_seconds": null,
	"max_payment_days": 180,
	"receiver_conciliation_id": "3bd19ada234141bf9f1fc5ce0b216723",
	"payer_name": "QI Tech",
	"payer_document_number": "98765432100",
	"payer_person_type": "natural",
	"payer_request": "O que voce achou da experiencia",
	"pix_message": null,
	"modality_alteration": false,
	"expiration_date": "2025-09-24",
	"rebate_amount": 10,
	"interest_amount": 10,
	"fine_amount": 10,
	"paid_amount": null,
	"discounts": [{
		"discount_type": "absolute",
		"limit_date": "2023-02-24",
		"amount": 20
	}],
	"additional_data": [{
		"\<tag_name\>": "\<tag_value\>"
	}],
	"origin": "system",
	"origin_key": null,
	"pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
	"qr_code_key": "3bd19ada-2341-41bf-9f1f-c5ce0b216723",
	"occurrence_type": "edit",
	"end_to_end_id": null,
	"base_64": "MDAwMjAxMjY5NzAwMTRici5nb3YuYmNiLnBpeDI1NzVxcmNvZGUtaC5zYW5kYm94LnFpdGVjaC5hcHAvYmFjZW4vY29idi8zYmQxOWFkYS0yMzQxLTQxYmYtOWYxZi1jNWNlMGIyMTY3MjM1MjA0MDAwMDUzMDM5ODY1ODAyQlI1OTI1Vk9WTyBMVUNJQSBDT05WRU5JRU5DSUEgTDYwMDdMaW1laXJhNjEwODEzNDgwMjkwNjIwNzA1MDMqKio2MzA0QzNGNg",
	"image": "\<BASE 64 DO QR CODE PIX\>",
	"source_account_branch": null,
	"source_account_financial_institution": null,
	"source_account_ispb": null,
	"source_account_number": null,
	"source_account_digit": null,
	"qr_code_occurrence_key": "d9c01f70-26bc-429d-afd1-038bd3c235b2"
}

6.3. 注销动态 PIX QR Code

要注销动态 PIX QR Code，需要提供 QR Code 的 "qr_code_key" 并将 "occurrence_type" 设置为 "write_off"。

请求（Request）

方法
POST
端点
/baas/qrcode/dynamic

Request Body

{
    "qr_code_key": "3bd19ada-2341-41bf-9f1f-c5ce0b216723",
    "occurrence_type": "write_off"
}

响应（Response）

方法
POST
端点
/baas/qrcode/dynamic

Response Body

{
	"qr_code_type": "dynamic_term",
	"amount": null,
	"expiration_seconds": 86400,
	"max_payment_days": null,
	"receiver_conciliation_id": "3bd19ada234141bf9f1fc5ce0b216723",
	"payer_name": null,
	"payer_document_number": null,
	"payer_person_type": "natural",
	"payer_request": null,
	"pix_message": null,
	"modality_alteration": false,
	"expiration_date": null,
	"rebate_amount": null,
	"interest_amount": null,
	"fine_amount": null,
	"paid_amount": null,
	"discounts": [],
	"additional_data": [],
	"origin": "system",
	"origin_key": null,
	"pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
	"qr_code_key": "3bd19ada-2341-41bf-9f1f-c5ce0b216723",
	"occurrence_type": "write_off",
	"end_to_end_id": null,
	"base_64": null,
	"image": null,
	"source_account_branch": null,
	"source_account_financial_institution": null,
	"source_account_ispb": null,
	"source_account_number": null,
	"source_account_digit": null,
	"qr_code_occurrence_key": "46001adf-ffe2-4534-b60e-f6c16b9af56e"
}

7 - 登记、修改和支付银行票据（Boleto）

7.1. 查询收款钱包

要登记、修改和支付银行票据，首先需要获取与账户绑定的收款钱包代码（Requester Profile Code）。每个账户在创建时都会自动绑定一个收款钱包。

收款钱包代码遵循以下格式：

"银行编号" + "钱包代码" + "账户行号" + "不含校验位的7位账户号码"。在 QI Tech，银行编号、钱包代码和行号默认分别为 "329"、"09" 和 "0001"。例如："329-09-0001-2359934"。

如需获取各账户的收款钱包代码列表，请使用以下端点：

请求（Request）

方法
GET
端点
/bank_slip/requester_profiles

响应（Response）

Response Body

{
    "requester_profile_codes": [
        "329-09-0001-1467576",
        "329-09-0001-5747500",
        "329-09-0001-2730579",
        "329-09-0001-2359934"
    ]
}

注意

银行票据的登记、修改和注销通过事件（occurrence）机制进行。每个事件发送至 QI Tech 后，再转发至票据集中处理中心。事件可能被票据集中处理中心接受或拒绝。关于事件接受或拒绝的结果将通过 webhook 发送给合作方。

7.2. 登记票据

要登记一张票据，需要发送一个登记事件，具体方式如下端点所述：

请求（Request）

方法
POST
端点
/multibank_instruction?use_multi_process=true

Request Body

{
    "occurrences": [
        {
            "amount": 800,
            "our_number": 1,
            "automatic_bankruptcy_protest": false,
            "bank_teller_instructions": "Não aceitar após vencimento",
            "days_to_bankruptcy_protest": 0,
            "document_number": "123456/01",
            "expiration": "2022-12-01",
            "fine_percentage": "2",
            "interest_daily_value": "0.34",
            "occurrence_type": "registration",
            "payer_address": "Rua Carlos Sampaio, 123",
            "payer_document": "41184562067",
            "payer_name": "João Ninguem",
            "payer_person_type": "natural",
            "payer_postal_code_root": "15800",
            "payer_postal_code_suffix": "020",
            "registration_institution_enumerator": "qi_scd",
            "requester_profile": 9,
            "requester_profile_code": "329-09-0001-2359934"
        }
    ]
}

信息

我方银行编号（"our_number"）是票据在收款钱包中的 ID，应为递增 ID。我方银行编号（"our_number"）由合作方生成，并在登记票据时提供。

重要提示： 票据应通过以下组合键定位：我方银行编号（"our_number"）+ 收款钱包代码（"requester_profile_code"）。

响应（Response）

方法
POST
端点
/multibank_instruction?use_multi_process=true

Response Body

{
	"file_info": {
		"beneficiary_code": null,
		"beneficiary_name": null,
		"file_sequence_id": null,
		"file_type_identifier": null,
		"file_type_literal": null,
		"service_code": null,
		"service_literal": null,
		"wrote_at": null
	},
	"occurrence_stats": {
		"bank_slip_edit": 0,
		"bankruptcy_protest_request": 0,
		"cancel_rebate": 0,
		"extension": 0,
		"notary_office_entry": 0,
		"notary_office_exit": 0,
		"notary_office_payment": 0,
		"notification": 0,
		"payment": 0,
		"payment_notice": 0,
		"payment_write_off": 0,
		"protest_cancel_and_write_off_request": 0,
		"protest_cancel_request": 0,
		"protest_remove_request": 0,
		"protest_request": 0,
		"rebate": 0,
		"registration": 1,
		"write_off": 0
	},
	"semantic_errors": []
}

关于票据登记的接受或拒绝结果将通过以下 webhook 通知。

Webhook

WEBHOOK_TYPE
bank_slip.status_change
STATUS
registered

Response Body

{
	"key": "41927fa9-f9ed-4797-b48a-6ac68e58dc17",
	"data": {
		"expiration": "2022-12-01",
		"our_number": 1,
		"bank_slip_key": "41927fa9-f9ed-4797-b48a-6ac68e58dc17",
		"rebate_amount": 0,
		"occurrence_type": "registration",
		"occurrence_feedback": "confirmed",
		"occurrence_sequence": 0,
		"requester_profile_code": "329-09-0001-2359934",
		"glados_occurrence_reasons": null,
		"cnab_file_occurrence_order": 1,
		"registration_institution_occurrence_date": "2022-11-21"
	},
	"status": "registered",
	"webhook_type": "bank_slip.status_change",
	"event_datetime": "2022-11-22 00:41:32"
}

要将收到的 webhook 与某张票据关联，应使用我方银行编号（"our_number"）和收款钱包代码（"requester_profile_code"）。

一旦票据登记被集中处理中心接受，webhook 中将返回票据的 UUID 密钥（"bank_slip_key"）。请保存此密钥，通过它可以查询票据信息。

7.2. 修改票据数据

要修改票据数据，需要发送一个事件。每种可能的修改对应相应的事件类型。票据数据修改的事件列表可在我们的文档《发送票据指令》[链接]中查阅。

7.3. 申请票据补发

票据登记后，可申请生成票据的 ".pdf" 文件，其中包含付款所需的信息。

请求（Request）

方法
POST
端点
/bank_slip/2-way/BANKSLIP-KEY

Payload:

响应（Response）

Response Body

{
	...
	"bank_slip_file": [{
		"barcode": "32991918600000800000001090000000000123599340",
		"created_at": "2022-11-21T23:29:45",
		"digitable_line": "32990001039000000000101235993407191860000080000",
		"url": "https://storage.googleapis.com/sandbox-bank-slip-api/bank-slip-pdf/41927fa9-f9ed-4797-b48a-6ac68e58dc17_1.pdf"
	}],
	...
}

信息

将返回票据的所有数据，".pdf" 下载链接将在 "bank_slip_file.url" 对象中提供。

7.4. 查询票据数据

票据数据可通过两种不同方式查询。

7.4.1. 通过可输入行查询

票据的可输入行（linha digitável）是一串包含票据信息的数字序列。付款用户在付款银行的网银中输入此数字序列。

信息

可输入行示例：32990001031000000000902000000204685640000100000

通过可输入行可查询票据数据：

请求（Request）

方法
GET
端点
/bank_slip/payment
参数
digitable_line

响应（Response）

Response Body

{
	"barcode": "32991918600000800000001090000000000123599340",
	"beneficiary_bank_code": "329",
	"beneficiary_document_number": "09080702000105",
	"beneficiary_legal_name": "VOVO LUCIA CONVENIENCIA LTDA",
	"beneficiary_person_type": "legal",
	"calculated_internally": true,
	"calculation_date": "2022-11-21",
	"calculation_model": 1,
	"digitable_line": "32990001039000000000101235993407191860000080000",
	"discount_amount": "0",
	"expiration_date": "2022-12-01",
	"expired_as_of_payment_date": false,
	"expired_as_of_today": false,
	"factual_expiration_date": "2022-12-01",
	"fine_amount": "0",
	"guarantor_document": null,
	"guarantor_name": null,
	"interest_amount": "0",
	"max_payment_date": "2023-05-30",
	"nominal_amount": "800.00",
	"payer_document_number": "41184562067",
	"payer_legal_name": "Jo_o Ninguem",
	"payer_person_type": "natural",
	"payment_date": "2022-11-21",
	"rebate_amount": "0.0",
	"total_amount": "800.0",
	"valid_payment_amount": true,
	"valid_payment_calculation": true,
	"valid_payment_time_frame": true
}

7.4.2. 通过票据密钥查询

一旦票据登记被集中处理中心接受，webhook 中将返回票据的 UUID 密钥（"bank_slip_key"）。通过此密钥可查询票据信息：

请求（Request）

方法
GET
端点
/bank_slip/BANKSLIP-KEY

Request Body

{
	"barcode": "32991918600000800000001090000000000123599340",
	"beneficiary_bank_code": "329",
	"beneficiary_document_number": "09080702000105",
	"beneficiary_legal_name": "VOVO LUCIA CONVENIENCIA LTDA",
	"beneficiary_person_type": "legal",
	"calculated_internally": true,
	"calculation_date": "2022-11-21",
	"calculation_model": 1,
	"digitable_line": "32990001039000000000101235993407191860000080000",
	"discount_amount": "0",
	"expiration_date": "2022-12-01",
	"expired_as_of_payment_date": false,
	"expired_as_of_today": false,
	"factual_expiration_date": "2022-12-01",
	"fine_amount": "0",
	"guarantor_document": null,
	"guarantor_name": null,
	"interest_amount": "0",
	"max_payment_date": "2023-05-30",
	"nominal_amount": "800.00",
	"payer_document_number": "41184562067",
	"payer_legal_name": "Jo_o Ninguem",
	"payer_person_type": "natural",
	"payment_date": "2022-11-21",
	"rebate_amount": "0.0",
	"total_amount": "800.0",
	"valid_payment_amount": true,
	"valid_payment_calculation": true,
	"valid_payment_time_frame": true
}

7.5. 支付票据

要支付一张票据，需要进行两次调用：

申请转账验证 token：/baas/token_request
批准转账：/baas/movement_validation

请求（Request）

方法
POST
端点
/baas/token_request

Request Body

{
    "contact_type": "email",
    "agent_document_number": "97564480084",
    "movement_payload": {
        "resource_account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
        "digitable_line": "32990001031000699926165000000201993810000003500"
    }
}

信息

发送的 Token 需在批准票据付款时提供，且 "movement_payload" 必须与申请 Token 时所提供的内容一致。

请求（Request）

方法
POST
端点
/baas/movement_validation

Request Body

{
    "token": "358192",
    "movement_payload": {
        "resource_account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
        "digitable_line": "32990001031000699926165000000201993810000003500"
    }
}

响应（Response）

方法
POST
端点
/baas/movement_validation

Response Body

{
	"authentication_code": "7bf20f1721ecc043d2a16a20ae668b01",
	"bank_slip": {
		"beneficiary": {
			"document_number": "32402502000135",
			"document_number_formatted": "32.402.502/0001-35",
			"name": "QI SCD"
		},
		"digitable_line": "32990001031000699926165000000201993810000003500",
		"expiration_date": "2023-06-14",
		"expiration_date_formatted": "14/06/2023",
		"financial_institution_compe_number": "329",
		"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
		"payer": {
			"document_number": "10932327656",
			"document_number_formatted": "109.323.276-56",
			"name": "Lucas Clarim"
		},
		"payment_date": "2022-11-22",
		"payment_date_formatted": "22/11/2022",
		"payment_key": "13b35108-0fdc-44ab-b86d-5dda12dc8dce"
	},
	"origin_key": "13b35108-0fdc-44ab-b86d-5dda12dc8dce",
	"pdf_encoded_string": "\<BASE 64 DO COMPROVANTE\>",
	"source_account": {
		"account_branch": "0001",
		"account_digit": "2",
		"account_number": "2359934",
		"financial_institution_compe_number": 329,
		"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
		"owner_document_number": "09080702000105",
		"owner_document_number_formatted": "09.080.702/0001-05",
		"owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
	},
	"source_subtype": "bank_slip_payment",
	"source_subtype_translation_ptbr": "Pagamento de Boleto",
	"transacted_at": "2022-11-22 12:26:21",
	"transacted_at_br": "2022-11-22 09:26:21",
	"transacted_at_br_formatted": "22/11/2022, 09:26:21",
	"transacted_at_formatted": "22/11/2022, 12:26:21",
	"transaction_amount": 35,
	"transaction_amount_formatted": "R$ 35,00",
	"transaction_key": "eee862b9-7f2e-4eea-b04a-fa0e89442618"
}

7.6. 票据收款通知

当票据在其他银行被支付时，系统会实时发送该票据已被支付的通知。财务清算将于下一个工作日进行。

Webhook

WEBHOOK_TYPE
bank_slip.status_change
STATUS
payment_notice

Response Body

{
	"key": "945e191d-1a78-4a28-8669-000b7e4a3522",
	"data": {
		"our_number": 1,
		"paid_amount": 800,
		"payment_bank": 341,
		"bank_slip_key": "41927fa9-f9ed-4797-b48a-6ac68e58dc17",
		"payment_method": 2,
		"payment_origin": 3,
		"occurrence_type": "payment_notice",
		"occurrence_feedback": "confirmed",
		"occurrence_sequence": 0,
		"requester_profile_code": "329-09-0001-2359934",
		"registration_institution": "qi_scd",
		"cnab_file_occurrence_order": 1,
		"registration_institution_occurrence_date": "2022-11-02"
	},
	"status": "payment_notice",
	"webhook_type": "bank_slip.status_change",
	"event_datetime": "2022-11-21 23:02:02"
}

信息

payment_method： 票据的支付方式，可为：

"credit_card"： 信用卡

"cash"： 现金

"account_debit"： 账户扣款

"check"： 支票

信息

payment_origin： 票据支付地点的来源，可为：

"internet"： 网上银行

"phisical_cashier"： 银行柜台（窗口）

"taa"： 自动柜员机

"eletronic_file"： CNAB 清算文件

"call_center"： 客服中心

"dda"： DDA（授权直接扣款）

"corban"： 彩票点 - 银行代理

注意

支付方式（"payment_method"）和支付来源（"payment_origin"）信息由付款方在支付票据时提供，其一致性和真实性由处理该支付的机构负责。

8 - 资金流动、凭证与账单

信息

本手册包含我们 Banking as a Service 产品的结构/信息，同时也可作为我们端点的文档参考。

8.1. 资金流动

每一笔资金流动都将发送一个 "account_transaction" webhook。

每笔交易都有一种分类类型（Source Sub Type）。该分类用于对账户中的每笔流动进行归类。Source Sub Types 列表可在本手册的附录 I 中查阅。

账户入账将产生一个 "data.amount" 为正值的 webhook，"data.origin" 为资金来源账户，"data.destination" 为资金目标账户：

Webhook

WEBHOOK_TYPE
account_transaction

Response Body: Pix

{
    "key": "\<ACCOUNT-KEY\>",
	"data": {
		"amount": 1000000,
		"origin": {
			"name": "Treasury Account",
			"branch": "0001",
			"document": "32402502000135",
			"account_key": "5d068423-6094-49e4-b15b-7740038295a8",
			"account_digit": "5",
			"account_number": "00002"
		},
		"timestamp": "2022-09-02T21:36:33.446120",
		"description": "329 0001 00002-5 32.402.502/0001-35 - QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
		"destination": {
			"name": "Default",
			"branch": "0001",
			"document": "09080702000105",
			"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
			"account_digit": "2",
			"account_number": "2359934"
		},
		"reference_key": "983b4a28-7de6-4e71-97ef-60fb50c7b013",
		"reference_type": "movement_request",
		"account_balance": 1000000,
		"source_sub_type": "internal_funds_transfer",
		"transaction_key": "67a62397-2c32-4768-8485-ec9129a46654",
		"source_sub_type_str": "Transferência Interna",
		"transaction_details": {
			"payer_name": "0001",
			"receiver_name": "Default",
			"payer_account_digit": "5",
			"payer_account_branch": "",
			"payer_account_number": "1111111",
			"payer_document_number": "66681638999999",
			"receiver_account_digit": "6",
			"receiver_account_branch": "0000",
			"receiver_account_number": "34256449809",
			"receiver_conciliation_id": null,
			"receiver_document_number": "00809641658"
		}
	},
	"datetime": "2022-09-02T21:36:33.446120",
	"webhook_type": "account_transaction"
}

Response Body: 其他交易

{
    "key": "\<ACCOUNT-KEY\>",
	"data": {
		"amount": 1000000,
		"origin": {
			"name": "Treasury Account",
			"branch": "0001",
			"document": "32402502000135",
			"account_key": "5d068423-6094-49e4-b15b-7740038295a8",
			"account_digit": "5",
			"account_number": "00002"
		},
		"timestamp": "2022-09-02T21:36:33.446120",
		"description": "329 0001 00002-5 32.402.502/0001-35 - QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
		"destination": {
			"name": "Default",
			"branch": "0001",
			"document": "09080702000105",
			"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
			"account_digit": "2",
			"account_number": "2359934"
		},
		"reference_key": "983b4a28-7de6-4e71-97ef-60fb50c7b013",
		"reference_type": "movement_request",
		"account_balance": 1000000,
		"source_sub_type": "internal_funds_transfer",
		"transaction_key": "67a62397-2c32-4768-8485-ec9129a46654",
		"source_sub_type_str": "Transferência Interna",
	},
	"datetime": "2022-09-02T21:36:33.446120",
	"webhook_type": "account_transaction"
}

账户出账将产生一个 "data.amount" 为负值的 webhook，"data.origin" 为资金目标账户，"data.destination" 为资金来源账户：

Webhook

WEBHOOK_TYPE
account_transaction

Response Body

{
	"key": "\<ACCOUNT-KEY\>",
	"data": {
		"amount": -45,
		"origin": {
			"name": "PIX",
			"branch": "0001",
			"document": "32402502000135",
			"account_key": "3d0e7d50-e898-49f3-b23b-05353c8a3c72",
			"account_digit": "3",
			"account_number": "00003"
		},
		"timestamp": "2022-09-02T23:00:05.326738",
		"description": "212 0001 1017372-2 ***.221.81*-** BANCO ORIGINAL S.A.",
		"destination": {
			"name": "Default",
			"branch": "0001",
			"document": "09080702000105",
			"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
			"account_digit": "2",
			"account_number": "2359934"
		},
		"reference_key": "cea836b5-b02e-4f94-b1e2-4d575671c33d",
		"reference_type": "pix_outgoing",
		"account_balance": 999955,
		"source_sub_type": "pix_withdrawal",
		"transaction_key": "d2ba3817-26d7-4957-ab82-24f78d910a8a",
		"source_sub_type_str": "Transferência de PIX"
	},
	"datetime": "2022-09-02T23:00:05.326738",
	"webhook_type": "account_transaction"
}

source_sub_type 列表：

Enum	描述
operation_disbursement	操作放款
protest_expense	抗议费用
automatic_integrated_payment	集成自动支付
tax	税费
electronic_funds_fee	TED手续费
credit_operation_fee	信贷开立手续费
internal_funds_transfer	内部转账
incoming_funds_transfer	入账转账
outgoing_funds_transfer	TED
deposit	存款
withdrawal	转账
withdrawal_reversal	转账退款
trade_funds_transfer	转让付款转账
settlement_funds_transfer	清算转账
bank_slip_fee	银行单据手续费
bank_slip_settlement	银行单据清算
outgoing_funds_transfer_reversal	TED退款
incoming_funds_transfer_refusal	拒绝转账
electronic_funds_fee_reversal	TED手续费退款
monthly_account_fee_reversal	账户维护手续费退款
bank_slip_fee_reversal	银行单据手续费退款
correspondent_bank_transfer	银行代理转付
credit_analysis_fee	信贷分析手续费
credit_operation_fee_reversal	信贷开立手续费退款
financial_investments_income	金融投资收益
bank_slip_settlement_reversal	银行单据清算退款
bank_slip_settlement_expense_reversal	银行单据清算手续费退款
bank_slip_settlement_incoming_reversal	银行单据清算收款退款
correspondent_bank_transfer_reversal	银行代理转付退款
credit_analysis_fee_reversal	信贷分析手续费退款
doc_expense_reversal	DOC手续费退款
incoming_doc_reversal	DOC入账退款
operation_disbursement_reversal	操作放款退款
operation_settling_reversal	操作付款退款
outgoing_doc_reversal	DOC出账退款
rebate_reversal	回扣退款
settlement_funds_transfer_reversal	清算转账退款
tax_reversal	税费退款
trade_funds_transfer_reversal	转让付款转账退款
bank_slip_permanency_fee	票据保管手续费
bank_slip_cancel_protest_fee	票据保管手续费
bank_slip_protest_fee	抗议申请手续费
bank_slip_notary_office_fee	抗议公证费用
bank_slip_registration_fee	登记手续费
bank_slip_extension_fee	延期手续费
bank_slip_rebate_fee	折扣手续费
bank_slip_discount_fee	贴现手续费
bank_slip_settlement_fee	清算手续费
bank_slip_write_off_term_fee	到期注销手续费
bank_slip_write_off_fee	注销手续费
bank_slip_cancel_protest_write_off_fee	带注销的抗议中止手续费
bank_slip_notary_office_settlement_fee	公证处清算手续费
rebate_tax_free	受托转付
rebate_tax_free_reversal	受托转付退款
incoming_funds_transfer_reversal	内部转账退款
bank_slip_payment	银行单据付款
bank_slip_payment_reversal	银行单据付款退款
warranty_analysis_fee	担保分析手续费
bank_slip_settlement_deposit	银行单据清算
bank_slip_payment_withdrawal	银行单据付款
account_setup_fee	开户手续费
account_setup_fee_reversal	开户手续费退款
bank_slip_payment_withdrawal_reversal	银行单据付款退款
incoming_anticipation_of_receivable	-
incoming_credit_card_settlement	信用卡清算
incoming_debit_card_settlement	借记卡清算
assignment_automatic_transfer	自动转让扣款
assignment_automatic_transfer_reversal	自动转让扣款退款
pix_fee	PIX手续费
incoming_pix_transfer	PIX入账
outgoing_pix_transfer	PIX出账
pix_fee_reversal	PIX手续费退款
incoming_pix_transfer_reversal	PIX入账退款
outgoing_pix_transfer_reversal	PIX出账退款
pix_deposit	PIX存款
pix_withdrawal	PIX转账
pix_withdrawal_reversal	PIX转账退款
pix_chargeback_withdrawal	PIX退款发送
outgoing_pix_chargeback	PIX退款出账
incoming_pix_chargeback	PIX退款收款
pix_chargeback_deposit	PIX退款入账
pix_chargeback_withdrawal_reversal	PIX退款发送退款
outgoing_pix_chargeback_reversal	PIX退款出账退款
incoming_pix_chargeback_reversal	PIX退款收款退款
operation_pix_disbursement	操作PIX放款
operation_pix_disbursement_reversal	操作PIX放款退款
receivables_inquiry_fee	应收款日程查询手续费
pix_deposit_reversal	PIX存款退款
internal_pix_transfer	PIX转账
automatic_integrated_payment_reversal	集成自动支付退款
operation_dibursement_reversal	操作放款退款
available_yield	流动投资存款

8.2. 凭证

转账/付款的凭证数据可通过 "transaction_key" 查询。

请求（Request）

方法
GET
端点
/transaction_receipt/TRANSACTION-KEY

响应（Response） - PIX 转账/付款

Response Body

{
	"chargeback_reason": null,
	"chargeback_returned_amount": null,
	"chargeback_unexpected_reason": null,
	"end_to_end_id": "E3240250220221120012039U3OKZZMW8",
	"origin_key": "cea836b5-b02e-4f94-b1e2-4d575671c33d",
	"original_transfer_data": null,
	"pix_message": null,
	"pix_transfer_type": "key",
	"receiver_conciliation_id": null,
	"source_account": {
		"account_branch": "0001",
		"account_digit": "2",
		"account_number": "2359934",
		"financial_institution_compe_number": 329,
		"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
		"owner_document_number": "09080702000105",
		"owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
	},
	"source_subtype": "pix_withdrawal",
	"source_subtype_translation_ptbr": "Transferência de PIX",
	"target_account": {
		"account_branch": "0001",
		"account_digit": "2",
		"account_number": "1017372",
		"financial_institution_compe_number": 212,
		"financial_institution_name": "BANCO ORIGINAL S.A.",
		"is_internal": false,
		"ispb_number": "92894922",
		"owner_document_number": "***22181***",
		"owner_name": "Vivo Test",
		"target_pix_key": "65322181032"
	},
	"transacted_at": "2022-11-20 02:00:05",
	"transacted_at_br": "2022-11-19 23:00:05",
	"transaction_amount": 45,
	"transaction_key": "d2ba3817-26d7-4957-ab82-24f78d910a8a",
	"translated_chargeback_reason": null
}

响应（Response） - 内部转账或 TED 付款

Response Body

{
	"origin_key": "983b4a28-7de6-4e71-97ef-60fb50c7b013",
	"source_account": {
		"account_branch": "0001",
		"account_digit": "5",
		"account_number": "00002",
		"financial_institution_compe_number": 329,
		"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
		"owner_document_number": "32402502000135",
		"owner_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A."
	},
	"source_subtype": "internal_funds_transfer",
	"source_subtype_translation_ptbr": "Transferência Interna",
	"target_account": {
		"account_branch": "0001",
		"account_digit": "2",
		"account_number": "2359934",
		"financial_institution_compe_number": 329,
		"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
		"owner_document_number": "09080702000105",
		"owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
	},
	"transacted_at": "2022-11-20 00:36:33",
	"transacted_at_br": "2022-11-19 21:36:33",
	"transaction_amount": 1000000,
	"transaction_key": "67a62397-2c32-4768-8485-ec9129a46654"
}

响应（Response） - 票据付款

Response Body

{
	"bank_slip": {
		"beneficiary": {
			"document_number": "32402502000135",
			"name": "QI SCD"
		},
		"digitable_line": "32990001031000699926165000000201993810000003500",
		"expiration_date": "2023-06-14",
		"financial_institution_compe_number": "329",
		"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
		"payer": {
			"document_number": "10932327656",
			"name": "Lucas Clarim"
		},
		"payment_date": "2022-11-22",
		"payment_key": "13b35108-0fdc-44ab-b86d-5dda12dc8dce"
	},
	"origin_key": "13b35108-0fdc-44ab-b86d-5dda12dc8dce",
	"source_account": {
		"account_branch": "0001",
		"account_digit": "2",
		"account_number": "2359934",
		"financial_institution_compe_number": 329,
		"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
		"owner_document_number": "09080702000105",
		"owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
	},
	"source_subtype": "bank_slip_payment",
	"source_subtype_translation_ptbr": "Pagamento de Boleto",
	"transacted_at": "2022-11-22 12:26:21",
	"transacted_at_br": "2022-11-22 09:26:21",
	"transaction_amount": 35,
	"transaction_key": "eee862b9-7f2e-4eea-b04a-fa0e89442618"
}

8.3. 账单

账户账单可通过以下端点查询：

请求（Request）

方法
GET
端点
/account_statement
参数
account_key, document_number, date_from, date_to, page, page_size

响应（Response）

Response Body

{
	"data": {
		"account_info": {
			"account_block_reason": null,
			"account_branch": "0001",
			"account_credentials": [{
					"account_id": 3395,
					"credential_type": "observer",
					"credential_type_id": 3,
					"document_number": "09080702000105",
					"id": 3244,
					"is_active": true,
					"name": "VOVO LUCIA CONVENIENCIA LTDA",
					"updated_at": null
				},
				{
					"account_id": 3395,
					"credential_type": "requester",
					"credential_type_id": 2,
					"document_number": "94310345000195",
					"id": 3245,
					"is_active": true,
					"name": "Parceiro Sandbox",
					"updated_at": null
				}
			],
			"account_digit": "2",
			"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
			"account_name": "Default",
			"account_number": "2359934",
			"account_status": "opened",
			"account_type": "checking",
			"automatic_transfer_management_status": {
				"created_at": "2022-10-27T13:48:18",
				"enumerator": "master"
			},
			"automatic_transfers": [],
			"balance": 999359,
			"blocked_balance": 0,
			"destinations": [],
			"fee": 0,
			"internal_webhooks": [],
			"investment_available_amount": 0,
			"investment_configuration": null,
			"owner_document_number": "09080702000105",
			"owner_name": "VOVO LUCIA CONVENIENCIA LTDA",
			"owner_person_key": "d2fddd2c-3436-41d5-97e0-5721ee871a3a",
			"permitted_person_keys": [
				"bffded45-5fcf-4d13-9d2a-566a0af338cc",
				"ef48fbe4-267b-45c1-9049-75345c075486"
			],
			"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
			"requester_name": "Parceiro Sandbox",
			"setup_fee": null,
			"transactional_limit": null,
			"webhook_enabled": true
		},
		"transaction_list": [
			{
				"account_balance": 999359,
				"description": "001 0001 81156-1 109.323.276-56 - Lucas de Jesus Clarim",
				"source_subtype": "withdrawal",
				"transacted_at": "2022-11-21 14:39:56",
				"transaction_amount": -551,
				"transaction_key": "32ac0781-f292-4172-b58f-3310102e6fb9"
			},
			{
				"account_balance": 999910,
				"description": "329 0001 00002-5 32.402.502/0001-35 - QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
				"source_subtype": "internal_funds_transfer",
				"transacted_at": "2022-11-20 02:27:38",
				"transaction_amount": -45,
				"transaction_key": "9cee2272-b280-47ed-b9ec-00674f25db1b"
			},
			{
				"account_balance": 999955,
				"description": "212 0001 1017372-2 ***.221.81*-** BANCO ORIGINAL S.A.",
				"source_subtype": "pix_withdrawal",
				"transacted_at": "2022-11-20 02:00:05",
				"transaction_amount": -45,
				"transaction_key": "d2ba3817-26d7-4957-ab82-24f78d910a8a"
			},
			{
				"account_balance": 1000000,
				"description": "329 0001 00002-5 32.402.502/0001-35 - QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
				"source_subtype": "internal_funds_transfer",
				"transacted_at": "2022-11-20 00:36:33",
				"transaction_amount": 1000000,
				"transaction_key": "67a62397-2c32-4768-8485-ec9129a46654"
			}
		]
	},
	"event_datetime": "2022-11-22 12:57:44",
	"key": "d96fb39c-e80b-447b-aad8-191c9bd2eb17",
	"status": "success",
	"webhook_type": "account_statement"
}

9 - 用户管理

可以对已开立账户的管理员用户进行添加和编辑。添加操作始终需要对被添加用户进行双因素身份验证。

9.1. 向已开立账户添加新用户

9.1.1. 创建

首先需要创建用户。在创建时，QI Tech 将通过短信或邮件向被创建用户发送一个 token。

请求（Request）

方法
POST
端点
/baas/token_request

Request Body

{
	"contact_type": "sms",
	"agent_document_number": "97564480084",
	"person_creation": {
		"person": {
			"date_of_birth": "1987-01-11",
			"spouse_name": "sample spouse name",
			"birth_place": "sample birth place",
			"phone_number": {
				"country_code": "55",
				"area_code": "88",
				"number": "988887777"
			},
			"representative": null,
			"father_name": "sample father name",
			"address": {
				"street": "Rua Sample Avenue",
				"complement": "Apto 123",
				"state": "MG",
				"number": "1234",
				"neighborhood": "Cabral",
				"postal_code": "38300000",
				"city": "Ituiutaba"
			},
			"nationality": "Brasil",
			"document_identification_number": "890537823",
			"mother_name": "Sample Mama",
			"person_type": "natural",
			"name": "Sample Name Natural",
			"profession": "sample profession",
			"gender": null,
			"email": "sample@gmail.com",
			"document_number": "68346734500",
			"marital_status": null
		}
	}
}

创建/更新新用户的双因素身份验证只能通过 "sms" 方式进行。

9.1.2. 确认创建

需要提供发送的 token 以完成新用户的创建：

请求（Request）

方法
POST
端点
/baas/movement_validation

Request Body

{
	"token": "456785",
	"person_creation": {
		"person": {
			"date_of_birth": "1987-01-11",
			"spouse_name": "sample spouse name",
			"birth_place": "sample birth place",
			"phone_number": {
				"country_code": "55",
				"area_code": "88",
				"number": "988887777"
			},
			"representative": null,
			"father_name": "sample father name",
			"address": {
				"street": "Rua Sample Avenue",
				"complement": "Apto 123",
				"state": "MG",
				"number": "1234",
				"neighborhood": "Cabral",
				"postal_code": "38300000",
				"city": "Ituiutaba"
			},
			"nationality": "Brasil",
			"document_identification_number": "890537823",
			"mother_name": "Sample Mama",
			"person_type": "natural",
			"name": "Sample Name Natural",
			"profession": "sample profession",
			"gender": null,
			"email": "sample@gmail.com",
			"document_number": "68346734500",
			"marital_status": null
		}
	}
}

响应（Response）

方法
POST
端点
/baas/movement_validation

Response Body

{
	"hash": "1ab3754bbe74e16c1bebfadd9b8fb9e3",
	"return_response": {
		"birth_place": null,
		"created_at": null,
		"date_of_birth": "1987-01-11T00:00:00",
		"document_identification_number": null,
		"email": "sample@gmail.com",
		"father_name": null,
		"gender": null,
		"is_pep": false,
		"kc_key": null,
		"marital_status": null,
		"mother_name": "Sample Mama",
		"nationality": "Brasil",
		"natural_revenue_range": {
			"average_amount": null,
			"created_at": "2021-03-12T13:26:08",
			"description": "Unavailable",
			"description_ptbr": "Indisponível",
			"enumerator": "0",
			"more_than_amount": null,
			"up_to_amount": null
		},
		"person": {
			"address": {
				"city": "Ituiutaba",
				"complement": "Apto 123",
				"created_at": null,
				"neighborhood": "Cabral",
				"number": "1234",
				"postal_code": "38300000",
				"state": "MG",
				"street": "Rua Sample Avenue"
			},
			"category": null,
			"category_nick": null,
			"created_at": null,
			"document_number": "44236096307",
			"domain": {
				"created_at": "2022-07-14T15:42:45",
				"domain_key": "7aa7e064-f06b-4e09-ae19-7c27694f545b",
				"domain_name": "Koin Soluções Domain Updated",
				"owner_person_key": "997d1b30-e40a-42a0-b87a-4191a5165494"
			},
			"internal_contact": null,
			"internal_contact_person_key": null,
			"name": "Sample Name Natural",
			"person_category": null,
			"person_code": 1564,
			"person_key": "9021859f-9860-41e6-af19-559a2599859c",
			"person_status": {
				"created_at": "2019-02-15T18:28:09",
				"enumerator": "pending",
				"translation_path": "onboarding.PersonStatus.pending"
			},
			"person_type": {
				"created_at": "2019-02-15T18:28:08",
				"enumerator": "natural",
				"translation_path": "onboarding.PersonType.natural"
			},
			"phone": [{
				"area_code": "16",
				"country_code": "55",
				"created_at": null,
				"number": "997239044",
				"phone_key": "b1c3f2d1-2433-4305-9d58-4dd83c30b7aa",
				"phone_type": null
			}],
			"professional_data": [],
			"qualifications": [],
			"registration_date": "2022-08-22",
			"risk": null,
			"special_attention": false,
			"terms_acknowledgement": false,
			"valid_cip_beneficiary": false
		},
		"profession": null,
		"revenue_amount": null,
		"spouse_name": null
	},
	"validation": true
}

9.1.3. 创建职业关联

用户创建后，需要将其关联到持有已开立账户的企业：

请求（Request）

方法
POST
端点
/baas/token_request

Request Body

{
	"contact_type": "sms",
	"agent_document_number": "97564480084",
	"professional_data_creation": {
		"natural_person": "3ea7f034-f06b-4e28-ae19-7c23694f546b",
		"legal_person": "8bc83ae4-68e4-7bc9-8c84-077131ba2c93",
		"natural_person_roles": [{
				"product_type": "account",
				"role_type": "requester"
			},
			{
				"product_type": "escrow",
				"role_type": "requester"
			}
		],
		"post_type": "ceo"
	}
}

9.1.4. 批准职业关联

要批准关联的添加，需要发送管理员用户收到的 token。

请求（Request）

方法
POST
端点
/baas/movement_validation

载荷（Payload）

Response Body

{
	"token": "076244",
	"professional_data_creation": {
		"natural_person": "3ea7f034-f06b-4e28-ae19-7c23694f546b",
		"legal_person": "8bc83ae4-68e4-7bc9-8c84-077131ba2c93",
		"natural_person_roles": [{
				"product_type": "account",
				"role_type": "requester"
			},
			{
				"product_type": "escrow",
				"role_type": "requester"
			}
		],
		"post_type": "ceo"
	}
}

响应（Response）

方法
POST
端点
/baas/movement_validation

响应体（Body）

Response Body

{
	"hash": "53d62e42d5299fca0d261ff1eae4bffc",
	"return_response": {
		"admission_date": "2022-08-22",
		"created_at": "2022-08-22T21:51:29",
		"email": null,
		"final_beneficiary": null,
		"is_active": true,
		"legal_person_key": "9bc89ea4-64e4-4bd9-8d84-077135ba2c93",
		"natural_person_key": "9021859f-9860-41e6-af19-559a2599859c",
		"natural_person_roles": [{
				"created_at": "2022-08-22T21:51:29",
				"natural_person_roles_events": [],
				"product_type": {
					"created_at": "2021-02-26T14:16:35",
					"enumerator": "account"
				},
				"role_type": {
					"created_at": "2021-02-26T14:14:52",
					"enumerator": "requester"
				},
				"updated_at": "2022-08-22T21:51:29"
		},
		{
			"created_at": "2022-08-22T21:51:29",
			"natural_person_roles_events": [],
			"product_type": {
				"created_at": "2022-04-08T14:51:34",
				"enumerator": "escrow"
			},
			"role_type": {
				"created_at": "2021-02-26T14:14:52",
				"enumerator": "requester"
			},
			"updated_at": "2022-08-22T21:51:29"
		}
	],
	"phone": null,
	"post_type": {
		"created_at": "2019-02-15T18:28:12",
		"enumerator": "ceo",
		"translation_path": "onboarding.PostType.ceo"
	},
	"profession_data_key": "bfe8bc59-533a-4c6a-be3a-af5137794c70",
	"updated_at": "2022-08-22T21:51:29"
},
"validation": true
}

9.2. 更新现有用户数据

用户数据的更新始终在该用户与特定企业的关联层级上进行。因此，执行任何更新时，始终需要用户的识别密钥（"natural_person"）以及该用户与企业关联的密钥（"professional_data_key"）。

9.2.1. 申请变更

首先需要申请更新用户与特定企业的关联数据。

请求（Request）

方法
POST
端点
/baas/token_request

Response Body

{
	"contact_type": "sms",
	"agent_document_number": "97564480084",
	"professional_data_contact_update": {
		"professional_data_key": "4ba8ff34-e07b-4ea8-ae59-8c23994f546b",
		"natural_person": "3ea7f034-f06b-4e28-ae19-7c23694f546b",
		"email": "sample@gmail.com",
		"phone_number": {
			"country_code": "55",
			"area_code": "888",
			"number": "988887777"
		}
	}
}

9.2.2. 批准变更申请

要批准用户数据的变更，需要发送发送给变更目标用户的 token：

请求（Request）

方法
POST
端点
/baas/movement_validation

Response Body

{
	"token": "076244",
	"professional_data_contact_update": {
		"professional_data_key": "4ba8ff34-e07b-4ea8-ae59-8c23994f546b",
		"natural_person": "3ea7f034-f06b-4e28-ae19-7c23694f546b",
		"email": "sample@gmail.com",
		"phone_number": {
			"country_code": "55",
			"area_code": "888",
			"number": "988887777"
		}
	}
}

响应（Response）

方法
POST
端点
/baas/movement_validation

Response Body

{
	"hash": "a355aade311f93ec87637e321f11386d",
	"return_response": {
		"admission_date": "2022-08-22",
		"created_at": "2022-08-22T21:51:29",
		"email": "contacto_info@fakemail.com",
		"final_beneficiary": null,
		"is_active": true,
		"legal_person_key": "9bc89ea4-64e4-4bd9-8d84-077135ba2c93",
		"natural_person_key": "9021859f-9860-41e6-af19-559a2599859c",
		"natural_person_roles": [{
				"created_at": "2022-08-22T21:51:29",
				"natural_person_roles_events": [],
				"product_type": {
					"created_at": "2021-02-26T14:16:35",
					"enumerator": "account"
				},
				"role_type": {
					"created_at": "2021-02-26T14:14:52",
					"enumerator": "requester"
				},
				"updated_at": "2022-08-22T21:51:29"
			},
			{
				"created_at": "2022-08-22T21:51:29",
				"natural_person_roles_events": [],
				"product_type": {
					"created_at": "2022-04-08T14:51:34",
					"enumerator": "escrow"
				},
				"role_type": {
					"created_at": "2021-02-26T14:14:52",
					"enumerator": "requester"
				},
				"updated_at": "2022-08-22T21:51:29"
			}
		],
		"phone": {
			"area_code": "16",
			"country_code": "55",
			"number": "997239044",
			"phone_type": "commercial"
		},
		"post_type": {
			"created_at": "2019-02-15T18:28:12",
			"enumerator": "ceo",
			"translation_path": "onboarding.PostType.ceo"
		},
		"profession_data_key": "bfe8bc59-533a-4c6a-be3a-af5137794c70",
		"updated_at": "2022-08-22T21:51:29"
	},
	"validation": true
}

1 - 创建账户​

1.1. 上传文件​

Response​

1.2. 创建法人账户（PJ）​

Request​

1.2.1 开户条款签署​

signed_contract 对象​

signatures 对象​

authenticity 对象​

signer 对象​

phone 对象​

1.3. 创建个人账户（PF）​

1.3.1. 身份证件的提交方式​

1.3.1.1. 提交 CNH 类型身份证件​

1.3.1.2. 提交 RG 类型身份证件​

1.3.2 开户条款签署​

signed_contract 对象​

signatures 对象​

authenticity 对象​

signer 对象​

phone 对象​

1.4. 获取账户数据​

2 - PIX 转账​

2.1. 执行 PIX 转账​

2.1.1. 创建转账请求​

使用 PIX 密钥进行转账（CPF、CNPJ、电子邮件、手机号或随机密钥）​

使用银行账户数据进行转账（手动 PIX）​

2.1.2. 申请转账验证令牌：​

2.1.3. 批准转账：​

2.2. PIX 到账 Webhook​

Webhook​

2.3. PIX 手续费扣收 Webhook​

2.4. PIX 退款（Chargeback）​

2.4.1. 发起 PIX Chargeback​

Request​

Response​

2.4.2. 申请 PIX Chargeback 授权令牌​

2.4.3. 批准 PIX Chargeback​

3 - TED 转账​

3.1. 执行 TED 转账​

3.2. TED 到账确认​

3.3. TED 退款​

4 - PIX QR Code 付款​

4.1. 支付静态 PIX QR Code​

4.2. 支付动态 PIX QR Code​

5 - 管理 PIX 密钥​

5.1. 创建 CPF、CNPJ 或随机 PIX 密钥​

5.2. 创建电子邮件和手机号 PIX 密钥​

5.3. 批准已申请的电子邮件或手机号 PIX 密钥​

5.4. 重新发送验证码​

5.5. 查询账户中已注册的 PIX 密钥​

5.6. 删除 PIX 密钥​

6 - 生成 PIX QR Code​

6.1. 生成静态 PIX QR Code​

6.2. 生成动态 PIX QR Code​

6.2.1. 生成带到期日的动态 PIX QR Code​

6.2.2. 生成即时支付动态 PIX QR Code​

6.2.3. 编辑动态 PIX QR Code 数据​

6.3. 注销动态 PIX QR Code​

7 - 登记、修改和支付银行票据（Boleto）​

7.1. 查询收款钱包​

7.2. 登记票据​

7.2. 修改票据数据​

7.3. 申请票据补发​

7.4. 查询票据数据​

7.4.1. 通过可输入行查询​

7.4.2. 通过票据密钥查询​

7.5. 支付票据​

7.6. 票据收款通知​

8 - 资金流动、凭证与账单​

8.1. 资金流动​

8.2. 凭证​

8.3. 账单​

9 - 用户管理​

9.1. 向已开立账户添加新用户​

9.1.1. 创建​

9.1.2. 确认创建​

9.1.3. 创建职业关联​

9.1.4. 批准职业关联​

9.2. 更新现有用户数据​

1 - 创建账户

1.1. 上传文件

Response

1.2. 创建法人账户（PJ）

Request

1.2.1 开户条款签署

signed_contract 对象

signatures 对象

authenticity 对象

signer 对象

phone 对象

1.3. 创建个人账户（PF）

1.3.1. 身份证件的提交方式

1.3.1.1. 提交 CNH 类型身份证件

1.3.1.2. 提交 RG 类型身份证件

1.3.2 开户条款签署

signed_contract 对象

signatures 对象

authenticity 对象

signer 对象

phone 对象

1.4. 获取账户数据

2 - PIX 转账

2.1. 执行 PIX 转账

2.1.1. 创建转账请求

使用 PIX 密钥进行转账（CPF、CNPJ、电子邮件、手机号或随机密钥）

使用银行账户数据进行转账（手动 PIX）

2.1.2. 申请转账验证令牌：

2.1.3. 批准转账：

2.2. PIX 到账 Webhook

Webhook

2.3. PIX 手续费扣收 Webhook

2.4. PIX 退款（Chargeback）

2.4.1. 发起 PIX Chargeback

Request

Response

2.4.2. 申请 PIX Chargeback 授权令牌

2.4.3. 批准 PIX Chargeback

3 - TED 转账

3.1. 执行 TED 转账

3.2. TED 到账确认

3.3. TED 退款

4 - PIX QR Code 付款

4.1. 支付静态 PIX QR Code

4.2. 支付动态 PIX QR Code

5 - 管理 PIX 密钥

5.1. 创建 CPF、CNPJ 或随机 PIX 密钥

5.2. 创建电子邮件和手机号 PIX 密钥

5.3. 批准已申请的电子邮件或手机号 PIX 密钥

5.4. 重新发送验证码

5.5. 查询账户中已注册的 PIX 密钥

5.6. 删除 PIX 密钥

6 - 生成 PIX QR Code

6.1. 生成静态 PIX QR Code

6.2. 生成动态 PIX QR Code

6.2.1. 生成带到期日的动态 PIX QR Code

6.2.2. 生成即时支付动态 PIX QR Code

6.2.3. 编辑动态 PIX QR Code 数据

6.3. 注销动态 PIX QR Code

7 - 登记、修改和支付银行票据（Boleto）

7.1. 查询收款钱包

7.2. 登记票据

7.2. 修改票据数据

7.3. 申请票据补发

7.4. 查询票据数据

7.4.1. 通过可输入行查询

7.4.2. 通过票据密钥查询

7.5. 支付票据

7.6. 票据收款通知

8 - 资金流动、凭证与账单

8.1. 资金流动

8.2. 凭证

8.3. 账单

9 - 用户管理

9.1. 向已开立账户添加新用户

9.1.1. 创建

9.1.2. 确认创建

9.1.3. 创建职业关联

9.1.4. 批准职业关联

9.2. 更新现有用户数据