Contexto
Neste artigo, vamos apresentar o processo de criação de uma nova chave Pix por meio da nossa API, incluindo os pré-requisitos, o endpoint utilizado, parâmetros esperados e exemplos de resposta.
Pré-requisitos
Antes de começar, certifique-se de que você:
- Está autenticado com um token válido da nossa API;
- Possui um client_id e client_secret ativos;
- Já possui uma conta Pix cadastrada.
1. Criação de Nova Chave Pix (EVP)
▶️ Endpoint
POST {{url}}/v1/accounts/{{accountId}}/aliases
Body
{
"externalIdentifier": "{{UUID}}", // Identificador único da transação
"alias": {
"type": "EVP" // Tipo da chave
}
}
Hash de Autenticação
A requisição exige um hash no header Transaction-Hash calculado assim:
var valoresHash = "post:/v1/accounts/" + accountId + "/aliases:";
CryptoJS.HmacSHA256(valoresHash, SecretKey);
✅ Resposta
{
"data": {
"alias": {
"type": "EVP", // Tipo da chave
"status": "CLEARING_REGISTRATION_PENDING" // Status temporário
}
}
}
⚠️ Durante o processo de registro da chave, caso consulte na API e ainda esteja com o status CLEARING_REGISTRATION_PENDING é temporário e por isso recomendamos que salve no banco como chave PIX, somente quando a mesma está com o status de ACTIVE.
1.1 Criação de Nova Chave Pix (CPF/CNPJ)
▶️ Endpoint
POST {{url}}/v1/accounts/{{accountId}}/aliases
Body
{
"externalIdentifier": "{{UUID}}", // Identificador único da transação
"alias": {
"name": "61229818000175", // informar o CPF ou CNPJ*
"type": "TAX_ID" // Tipo da chave
}
}
* O alias recebido como taxId deve ser o mesmo taxId do titular da conta.
Hash de Autenticação
A requisição exige um hash no header Transaction-Hash calculado assim:
var valoresHash = "post:/v1/accounts/" + environment["accountId"].toString() + "/aliases:" + environment["CNPJ"].toString();
CryptoJS.HmacSHA256(valoresHash, SecretKey);
✅ Resposta
{
"data": {
"needsIdentifyConfirmation": false,
"alias": {
"name": "61229818000175",
"type": "TAX_ID",
"status": "CLEARING_REGISTRATION_PENDING" // Status temporário
}
}
}
1.2 Criação de Nova Chave Pix (EMAIL)
▶️ Endpoint
POST {{url}}/v1/accounts/{{accountId}}/aliases
Body
{
"externalIdentifier": "{{UUID}}", // Identificador único da transação
"alias": {
"name": "cuimei3424@uorak.com", // informar o endereço de e-mail*
"type": "EMAIL" // Tipo da chave
}
}
* Deverá ser realizado a confirmação do token, por isso revise o e-mail informado garantindo que esteja correto.
Hash de Autenticação
A requisição exige um hash no header Transaction-Hash calculado assim:
var valoresHash = "post:/v1/accounts/" + accountId + "/aliases:" + alias;
CryptoJS.HmacSHA256(valoresHash, SecretKey);
✅ Resposta
{
"data": {
"protocolId": "d87391ea-c4f3-442d-b7dd-24a5c3fa1643", // será usado na etapa de confirmação
"needsIdentifyConfirmation": true,
"alias": {
"name": "cuimei3424@uorak.com",
"type": "EMAIL",
"status": "IDENTITY_VALIDATION_PENDING*"
}
}
}
⚠️ Atenção!
Para as chaves que exigem confirmação via token, é fundamental verificar se os e-mails com o código de verificação não estão sendo bloqueados pelo provedor de e-mail, ou se foram redirecionados para a caixa de spam.
Os remetentes utilizados para o envio dos códigos são:
naoresponda@ipflagship.com.br - Ambiente de Produção
naoresponda@maas.ipflagship.com.br - Ambiente de Homologação
▶️ Endpoint de validação do token
POST {{url}}/v1/accounts/{{accountId}}/aliases/{{alias}}/otp-validation
Body
{
"externalIdentifier": "{{UUID}}", // Identificador único da transação
"verificationCode": "{{verificationCode}}", // código recebido no e-mail
"protocolId": "{{protocolId}}" // código retornado na response da criação da chave
}
✅ Resposta
Será retornado apenas o status code 202 Accepted, não é retornado nada no response body.
1.3 Criação de Nova Chave Pix (PHONE)
▶️ Endpoint
POST {{url}}/v1/accounts/{{accountId}}/aliases
Body
{
"externalIdentifier": "{{UUID}}", // Identificador único da transação
"alias": {
"name": "+551912345678", // informar o celular adicionar o +55 com o DDD e o número*
"type": "PHONE" // Tipo da chave
}
}
* Deverá ser realizado a confirmação do token, por isso revise o celular informado garantindo que esteja correto para o recebimento do SMS.
Hash de Autenticação
A requisição exige um hash no header Transaction-Hash calculado assim:
var valoresHash = "post:/v1/accounts/" + accountId + "/aliases:" + alias;
CryptoJS.HmacSHA256(valoresHash, SecretKey);
✅ Resposta
{
"data": {
"protocolId": "567ea7fb-a2a0-4c76-a3a0-6aae6cc1ce85",
"needsIdentifyConfirmation": true,
"alias": {
"name": "+551912345678",
"type": "PHONE",
"status": "IDENTITY_VALIDATION_PENDING*"
}
}
}
* Após isso, será enviado um sms para o celular com o token de validação que deverá ser utilizado no endpoint:
POST {{url}}/v1/accounts/{{accountId}}/aliases/{{alias}}/otp-validation
Body
{
"externalIdentifier": "{{UUID}}", // Identificador único da transação
"verificationCode": "{{verificationCode}}", // código recebido por sms
"protocolId": "{{protocolId}}" // código retornado na response da criação da chave
}
✅ Resposta
Será retornado apenas o status code 202 Accepted, não é retornado nada no response body.
2. Consulta da Nova Chave
A chave pode levar alguns segundos para ser ativada. Consulte o status com:
▶️ Endpoint
GET {{url}}/v1/accounts/{{accountId}}/aliases
✅ Resposta
Exemplos para os casos listados nesse artigo:
{
"data": {
"aliases": [
{
"name": "0428f19c-6be6-4e90-a0c3-fa1b650a1ce4",
"type": "EVP",
"status": "ACTIVE"
},
{
"name": "61229818000175",
"type": "TAX_ID",
"status": "ACTIVE"
},
{
"name": "+551912345678",
"type": "PHONE",
"status": "ACTIVE"
},
{
"name": "cuimei3424@uorak.com",
"type": "EMAIL",
"status": "ACTIVE"
}
]
}
}
⚠️ Somente utilize a chave quando ela estiver com status ACTIVE.
3. Geração de QR Code com Nova Chave
▶️ Endpoint
POST {{url}}/v1/payments
Body - Parâmetro Principal a Ser Alterado
"paymentInfo": {
"instantPayment": {
"alias": "{{alias}}" // Nova chave ativa gerada
}
}
⚠️ QR Codes antigos não podem ser atualizados. A nova chave deve ser usada em novas cobranças.
4. Exclusão de chave
É possível solicitar a exclusão da chave via API, para isso deve seguir as seguintes etapas:
▶️ Endpoint
DELETE {{url}}/v1/accounts/{{accountId}}/aliases/{{alias}}
Para esse caso não possui body.
Hash de Autenticação
A requisição exige um hash no header Transaction-Hash calculado assim:
var valoresHash = "delete:/v1/accounts/" + accountId + "/aliases:" + alias;
CryptoJS.HmacSHA256(valoresHash, SecretKey);
✅ Resposta
Será retornado apenas o status code 202 Accepted, não é retornado nada no response body, basta realizar uma nova consulta para verificar que a chave não será mais retornada.
Para a exclusão das chaves não é necessário confirmação de token, ao retornar sucesso na API em alguns segundos a mesma será excluída, é possível que ao consultar seja retornado um status temporário de PENDING_DELETION, basta consultar novamente que a mesma será deletada e nada será retornado pela API.
Callback - Exemplo de Exclusão de Chave
{
"callbackType": "INSTANT_PAYMENT_ALIAS",
"aliasInfo": {
"key": "bob@email.com", // Chave excluída
"keyType": "EMAIL", // O tipo irá depender da chave excluída
"status": "EXCLUDED"
}
}
Exemplo de Erro Comum
Caso uma chave excluída ainda esteja sendo utilizada na geração do QR Code, o sistema pode retornar o seguinte erro:
{
"error": {
"code": "34",
"description": "Alias must be the same as the account holder."
}
}
Causa Provável
Esse erro pode ocorrer quando a chave Pix utilizada foi excluída ou não está mais vinculada corretamente ao titular da conta.
✅ Solução
Certifique-se de que:
- A chave utilizada no campo instantPayment.alias está com status ACTIVE;
- A chave foi recém-criada e consultada com sucesso no endpoint de aliases;
- O alias pertence ao mesmo titular da conta que está recebendo a cobrança.
Suporte
Para dúvidas ou acompanhamento de chamados, acesse: Portal de Suporte