Pular para o conteúdo principal

Criar Chave Pix

Criar Chave Pix CPF, CNPJ ou Aleatória​

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"
}
Tipos de Chave Pix

A “pix_key” pode ser um CPF, CNPJ, E-mail, Celular ou uma Chave Aleatória (UUID), seguindo as seguintes formatações:

CPF: Número inteiro com 11 dígitos.

CNPJ: Número inteiro com 14 dígitos.

E-mail: Texto contendo ao menos um “@”.

Celular: Texto contendo os seguintes valores: “+55” + “DDD do celular“ + “Número Inteiro do Celular com no mínimo 8 e no máximo 9 dígitos”. Ex: “+5511987654321“.

Chave Aleatória: UUID.

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: Chave pix já existe.
{
  "title": "Bad Request",
  "description": "Pix key: \{pix_key\} already exists.",
  "translation": "A chave pix: \{pix_key\} já existe.",
  "code": "PIX000065"
}

STATUS
404

Response Body: Conta não encontrada
{
    "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: Pessoa não encontrada
{
    "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: Chave Pix não Finalizada
{
    "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: Número Máximo de Chaves Pix em Uso
{
    "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: Conta não Aberta
{
    "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: Permissão Inválida
{
    "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: Tentativa de Chave Pix CPF Inválida
{
    "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"
}
Atenção

No caso da Response de criação de uma Chave Pix Aleatória, o campo “pix_key“ retornará um valor nulo. Para recuperar o valor da chave aleatória gerada, é necessária realizar uma consulta à lista de chaves cadastradas em uma conta, ou através do webhook de ativação.

Atenção

A criação de chaves é assíncrona, sendo assim, a chave apenas estará disponível para uso após o recebimento do webhook de inclusão de chave pix.

Criar Chave Pix E-mail e Celular​

Para criação da chave: POST no endpoint “/baas/pix/keys“. Neste momento, será enviado um Token para o E-mail ou Celular informado no campo “pix_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_validation",
	"request_type": "inclusion",
	"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
	"updated_at": "2022-09-02T17:41:55"
}

STATUS
400

Response Body: Chave pix já existe.
{
  "title": "Bad Request",
  "description": "Pix key: \{pix_key\} already exists.",
  "translation": "A chave pix: \{pix_key\} já existe.",
  "code": "PIX000065"
}

STATUS
404

Response Body: Conta não encontrada
{
    "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: Pessoa não encontrada
{
    "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: Chave Pix não Finalizada
{
    "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: Número Máximo de Chaves Pix em Uso
{
    "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: Conta não Aberta
{
    "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: Permissão Inválida
{
    "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: Tentativa de Chave Pix CPF Inválida
{
    "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"
}

IMPORTANTE: O valor retornado no campo “pix_key_request_key“ deve ser utilizado na URL da requisição para aprovação da criação da Chave Pix.

Aprovação de Chave Pix E-mail ou Celular​

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: Solicitação de chave Pix não encontrada
{
  "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: Erro do Validador de Permissão
{
    "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: Pedido de criação não possui validação
{
    "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: Pedido de criação não está pendente de validação
{
    "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 Expirado
{
    "title": "Gone",
    "description": {
        "description": "Expired Code.",
        "translation": "Código de verificação expirado."
    },
    "translation": {},
    "extra_fields": {},
    "code": "2FA000410"
}

STATUS
403

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

Reenviar o token de aprovação​

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: Solicitação de chave Pix não encontrada
{
  "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: Erro do Validador de Permissão
{
    "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: Pedido de criação não possui validação
{
    "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: Pedido de criação não está pendente de validação
{
    "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"
}

Webhook de Inclusão de Chave Pix​

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