Skip to main content
Para a descrição completa de todos os campos, consulte a referência do endpoint.

​
Visão Geral

Existem dois fluxos dependendo do tipo de chave:
  • DOCUMENT e RANDOM — uma única chamada à API cria a chave imediatamente.
  • EMAIL e PHONE — é necessário solicitar um código de verificação primeiro e informá-lo na criação.

​
Fluxo 1 — Chaves simples (DOCUMENT e RANDOM)

​
1. Criar a chave

Envie apenas o type. A chave é criada a partir dos dados já vinculados à conta:
DOCUMENT
curl -X POST 'https://app.plowf.com/api/v1/pix-keys' \
  -H 'Authorization: Bearer seu_token_aqui' \
  -H 'Content-Type: application/json' \
  -d '{ "type": "DOCUMENT" }'
RANDOM
curl -X POST 'https://app.plowf.com/api/v1/pix-keys' \
  -H 'Authorization: Bearer seu_token_aqui' \
  -H 'Content-Type: application/json' \
  -d '{ "type": "RANDOM" }'
A resposta retorna a chave criada: 
{
  "message": "Chave PIX criada com sucesso.",
  "data": {
    "key": "52998224725",
    "type": "DOCUMENT",
    "is_active": true,
    "created_at": "2026-01-19T19:32:14.000000Z"
  }
}
Para chaves RANDOM, o campo key conterá um UUID gerado automaticamente.

​
Fluxo 2 — Chaves com verificação (EMAIL e PHONE)

​
1. Solicitar o código de autenticação

Antes de criar a chave, solicite o envio de um código de verificação para o valor da chave desejada:
EMAIL
curl -X POST 'https://app.plowf.com/api/v1/pix-keys/auth-code' \
  -H 'Authorization: Bearer seu_token_aqui' \
  -H 'Content-Type: application/json' \
  -d '{ "key": "[email protected]" }'
PHONE
curl -X POST 'https://app.plowf.com/api/v1/pix-keys/auth-code' \
  -H 'Authorization: Bearer seu_token_aqui' \
  -H 'Content-Type: application/json' \
  -d '{ "key": "+5511999999999" }'
A resposta retorna o identificador do código enviado: 
{
  "message": "Código de autenticação enviado com sucesso.",
  "data": {
    "auth_code_id": "abc123xyz"
  }
}
Armazene o auth_code_id — ele será necessário na próxima etapa.
O código tem rate limit de 3 tentativas por 60 segundos por conta. Se o usuário não receber, aguarde antes de reenviar.

​
2. Criar a chave com o código recebido

Informe o auth_code_id retornado e o código que o usuário recebeu por SMS ou e-mail:
EMAIL
curl -X POST 'https://app.plowf.com/api/v1/pix-keys' \
  -H 'Authorization: Bearer seu_token_aqui' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "EMAIL",
    "auth_code_id": "abc123xyz",
    "auth_code": "123456"
  }'
PHONE
curl -X POST 'https://app.plowf.com/api/v1/pix-keys' \
  -H 'Authorization: Bearer seu_token_aqui' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "PHONE",
    "auth_code_id": "abc123xyz",
    "auth_code": "123456"
  }'
Resposta de sucesso: 
{
  "message": "Chave PIX criada com sucesso.",
  "data": {
    "key": "[email protected]",
    "type": "EMAIL",
    "is_active": true,
    "created_at": "2026-01-19T19:32:14.000000Z"
  }
}

​
Tratamento de erros

CódigoCausaAção recomendada
403Conta virtual inativaVerifique o status da conta antes de tentar criar chaves
422Chave já cadastrada em outra contaInforme o usuário que a chave não está disponível
422Código de autenticação inválido ou expiradoSolicite um novo código e repita o fluxo
422Provider não suporta este tipo de chaveUse um tipo alternativo (DOCUMENT ou RANDOM)
429Rate limit excedidoAguarde 60 segundos antes de tentar novamente

​
Referências