跳到主要内容

创建 Pix 密钥

创建 CPF、CNPJ 或随机 Pix 密钥​

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"
}
Request Body
{
    "account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
    "pix_key_type": "cpf",
    "pix_key": "03882617038"
}
Pix 密钥类型

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

CPF：11 位整数。

CNPJ：14 位整数。

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

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

随机密钥：UUID。

沙盒环境中的 CPF/CNPJ 规则

为模拟批准和拒绝场景，可使用待创建 Pix 密钥持有人 CPF/CNPJ 的第一位数字：

1, 2, 3, 4, 5 -> 自动拒绝 0, 6, 7, 8, 9 -> 自动批准

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

STATUS
400

Response Body: Pix 密钥已存在。
{
  "title": "Bad Request",
  "description": "Pix key: \{pix_key\} already exists.",
  "translation": "A chave pix: \{pix_key\} já existe.",
  "code": "PIX000065"
}

STATUS
404

Response Body: 账户未找到
{
    "title": "Account not found",
    "description": "Conta não encontrada para account_key: \{account_key\}",
    "translation": "Conta não encontrada para account_key: \{account_key\}",
    "code": "PIX000026"
}

STATUS
400

Response Body: 人员未找到
{
    "title": "Person not found",
    "description": "Pessoa não encontrada para person_key: \{person_key\}",
    "translation": "Pessoa não encontrada para person_key: \{person_key\}",
    "code": "PIX000027"
}

STATUS
400

Response Body: Pix 密钥创建未完成
{
    "title": "Pix Key Creation Non Finished",
    "description": "A chave pix \{pix_key\} já possui um pedido de criação não finalizado.",
    "translation": "A chave pix \{pix_key\} já possui um pedido de criação não finalizado.",
    "code": "PIX000074"
}

STATUS
400

Response Body: Pix 密钥数量已达上限
{
    "title": "Maximum Number of Pix Keys in Use",
    "description": "A conta \{account_key\} já atingiu o número máximo de chaves pix.",
    "translation": "A conta \{account_key\} já atingiu o número máximo de chaves pix.",
    "code": "PIX000014"
}

STATUS
400

Response Body: 账户未开立
{
    "title": "Account is not Opened",
    "description": "A conta \{account_key\} não está aberta.",
    "translation": "A conta \{account_key\} não está aberta.",
    "code": "PIX000002"
}

STATUS
403

Response Body: 权限无效
{
    "title": "Invalid Permission",
    "description": "A pessoa \{person_key\} não possui credenciais de administrador para a conta \{account_key\}.",
    "translation": "A pessoa \{person_key\} não possui credenciais de administrador para a conta \{account_key\}.",
    "code": "PIX000054"
}

STATUS
422

Response Body: 尝试创建的 CPF Pix 密钥无效
{
    "title": "Attempted CPF Pix Key is Not that of Account Owner",
    "description": "A chave pix fornecida \{pix_key\} não corresponde ao CPF {document_number} do titular da conta.",
    "translation": "A chave pix fornecida \{pix_key\} não corresponde ao CPF {document_number} do titular da conta.",
    "code": "PIX000020"
}
注意

对于创建随机密钥的响应，"pix_key"字段将返回空值。要获取生成的随机密钥值，需要查询账户已注册密钥列表，或通过激活 Webhook 获取。

注意

密钥创建是异步的，因此密钥只有在收到 Pix 密钥包含 Webhook 后才可使用。

创建电子邮件和手机号 Pix 密钥​

创建密钥： 向端点 "/baas/pix/keys" 发送 POST 请求。此时，将向"pix_key"字段中填写的电子邮件或手机号发送一个 Token。

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_validation",
	"request_type": "inclusion",
	"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
	"updated_at": "2022-09-02T17:41:55"
}

STATUS
400

Response Body: Pix 密钥已存在。
{
  "title": "Bad Request",
  "description": "Pix key: \{pix_key\} already exists.",
  "translation": "A chave pix: \{pix_key\} já existe.",
  "code": "PIX000065"
}

STATUS
404

Response Body: 账户未找到
{
    "title": "Account not found",
    "description": "Conta não encontrada para account_key: \{account_key\}",
    "translation": "Conta não encontrada para account_key: \{account_key\}",
    "code": "PIX000026"
}

STATUS
400

Response Body: 人员未找到
{
    "title": "Person not found",
    "description": "Pessoa não encontrada para person_key: \{person_key\}",
    "translation": "Pessoa não encontrada para person_key: \{person_key\}",
    "code": "PIX000027"
}

STATUS
400

Response Body: Pix 密钥创建未完成
{
    "title": "Pix Key Creation Non Finished",
    "description": "A chave pix \{pix_key\} já possui um pedido de criação não finalizado.",
    "translation": "A chave pix \{pix_key\} já possui um pedido de criação não finalizado.",
    "code": "PIX000074"
}

STATUS
400

Response Body: Pix 密钥数量已达上限
{
    "title": "Maximum Number of Pix Keys in Use",
    "description": "A conta \{account_key\} já atingiu o número máximo de chaves pix.",
    "translation": "A conta \{account_key\} já atingiu o número máximo de chaves pix.",
    "code": "PIX000014"
}

STATUS
400

Response Body: 账户未开立
{
    "title": "Account is not Opened",
    "description": "A conta \{account_key\} não está aberta.",
    "translation": "A conta \{account_key\} não está aberta.",
    "code": "PIX000002"
}

STATUS
403

Response Body: 权限无效
{
    "title": "Invalid Permission",
    "description": "A pessoa \{person_key\} não possui credenciais de administrador para a conta \{account_key\}.",
    "translation": "A pessoa \{person_key\} não possui credenciais de administrador para a conta \{account_key\}.",
    "code": "PIX000054"
}

STATUS
422

Response Body: 尝试创建的 CPF Pix 密钥无效
{
    "title": "Attempted CPF Pix Key is Not that of Account Owner",
    "description": "A chave pix fornecida \{pix_key\} não corresponde ao CPF {document_number} do titular da conta.",
    "translation": "A chave pix fornecida \{pix_key\} não corresponde ao CPF {document_number} do titular da conta.",
    "code": "PIX000020"
}

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

批准电子邮件或手机号 Pix 密钥​

Request​

  • MÉTODO
    PATCH
  • ENDPOINT
    /baas/pix/keys/PIX_KEY_REQUEST_KEY/twofa_validation
Request Body
{
    "verification_code": "756816"
}

Response​

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

STATUS
404

Response Body: Pix 密钥请求未找到
{
  "title": "Pix Key Request not found",
  "description": "Pix Key Request not found for key: {pix_key_request_key}.",
  "translation": "Pix Key Request não encontrada para a chave: {pix_key_request_key}.",
  "code": "PIX000008"
}

STATUS
403

Response Body: 权限验证器错误
{
    "title": "Permission Validator Error",
    "description": "Selected agent do not own this item.",
    "translation": "O agente selecionado não é dono do item.",
    "code": "QIT000005"
}

STATUS
400

Response Body: 创建请求没有验证
{
    "title": "Key request does not have validation",
    "description": "Key request does not have two steps validation",
    "translation": "Pedido de criação não possui validação de duas etapas",
    "code": "PIX000075"
}

STATUS
400

Response Body: 创建请求不处于待验证状态
{
    "title": "Key Request Is Not Pending Validation",
    "description": "Key request {pix_key_request_key}, is not pending validation.",
    "translation": "Pedido de criação {pix_key_request_key}, não está pendente de validação.",
    "code": "PIX000076"
}

STATUS
404

Response Body: Token 已过期
{
    "title": "Gone",
    "description": {
        "description": "Expired Code.",
        "translation": "Código de verificação expirado."
    },
    "translation": {},
    "extra_fields": {},
    "code": "2FA000410"
}

STATUS
403

Response Body: Token 已过期
{
    "title": "Forbidden",
    "description": {
        "description": "Code already verified.",
        "translation": "Este código já foi utilizado."
    },
    "translation": {},
    "extra_fields": {},
    "code": "2FA000403"
}

重新发送批准 Token​

Request​

  • MÉTODO
    PATCH
  • ENDPOINT
    /baas/pix/keys/PIX_KEY_REQUEST_KEY/resend_twofa
Request Body
{}

Response​

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_validation",
	"request_type": "inclusion",
	"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
	"updated_at": "2022-09-02T17:41:55"
}

STATUS
404

Response Body: Pix 密钥请求未找到
{
  "title": "Pix Key Request not found",
  "description": "Pix Key Request not found for key: {pix_key_request_key}.",
  "translation": "Pix Key Request não encontrada para a chave: {pix_key_request_key}.",
  "code": "PIX000008"
}

STATUS
403

Response Body: 权限验证器错误
{
    "title": "Permission Validator Error",
    "description": "Selected agent do not own this item.",
    "translation": "O agente selecionado não é dono do item.",
    "code": "QIT000005"
}

STATUS
400

Response Body: 创建请求没有验证
{
    "title": "Key request does not have validation",
    "description": "Key request does not have two steps validation",
    "translation": "Pedido de criação não possui validação de duas etapas",
    "code": "PIX000075"
}

STATUS
400

Response Body: 创建请求不处于待验证状态
{
    "title": "Key Request Is Not Pending Validation",
    "description": "Key request {pix_key_request_key}, is not pending validation.",
    "translation": "Pedido de criação {pix_key_request_key}, não está pendente de validação.",
    "code": "PIX000076"
}

Pix 密钥包含 Webhook​

WEBHOOK_TYPE
key_inclusion
STATUS
approved
Webhook 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"
}
WEBHOOK_TYPE
key_inclusion
STATUS
failed
Webhook Body
{
	"pix_key": "03882617038",
	"account_key": "94945886-7a6f-43e6-a307-e36c959e4903",
	"webhook_type": "key_inclusion",
	"pix_key_status": "inactivated",
	"pix_key_request_key": "e274eb13-40b3-4902-978e-8e5fa267af53",
	"pix_key_request_type": "inclusion",
	"pix_key_request_status": "failed",
	"request_failure_reason": "DCT200016"
}
请求失败原因代码
  • DCT200012：该密钥已存在绑定关系，但归另一个人所有。建议发起所有权认领。
  • DCT200013：该密钥已由同一所有者绑定，但关联至另一个参与者。建议发起可携性认领。
  • DCT200014：该绑定密钥存在状态不为已完成或已取消的认领。在此情况下，绑定关系不可删除。
  • DCT200015：请求中提供的参数验证失败。
  • DCT200016：密钥持有人（CPF/CNPJ）的登记状态异常。在正常化之前，不允许添加 PIX 密钥。