Cadastrar chave Pix
POST /accounts/:accountId/pix/keys — EVP/CPF/CNPJ direto ou EMAIL/PHONE com OTP.
Cadastrar chave Pix
Cadastra uma chave Pix na conta. EVP/CPF/CNPJ são cadastradas direto (sem verificação) enviando só o keyType — o valor é decidido pelo servidor (EVP gera UUID; CPF/CNPJ usa o documento da entidade). EMAIL/PHONE exigem verificação OTP em 2 etapas: primeiro POST /pix/keys/verifications, depois POST /pix/keys com o verificationId + otpCode recebido.
Dois fluxos no mesmo endpoint: (1) Direto pra EVP/CPF/CNPJ — só keyType no body, sem value (servidor preenche); CPF/CNPJ exigem que o documento bata com o da entidade autenticada. (2) Com OTP pra EMAIL/PHONE — chame antes POST /pix/keys/verifications, espere o código chegar e mande verificationId + otpCode. Erro PIX_KEY_PORTABILITY_REQUIRED indica que a chave já está vinculada a outra instituição financeira — peça portabilidade pelo banco atual antes de tentar cadastrar aqui (a API não força o vínculo).
Path params
- accountIdObrigatóriostring (UUID)ID da conta que vai receber a chave.
Headers
- AcceptObrigatóriostringapplication/json
- Content-TypeObrigatóriostringapplication/json
- AuthorizationObrigatóriostringBearer <token> — JWT de /authenticate.
- X-Tenant-IdObrigatóriostring (UUID)Identificador do tenant.
Body
- keyType"EVP" | "CPF" | "CNPJ"Obrigatório na variante direta (EVP/CPF/CNPJ). Para EVP, o servidor gera o UUID; para CPF/CNPJ, usa o documento da entidade autenticada. Não envie em variante com OTP.
- verificationIdstring (UUID)Obrigatório na variante com OTP (EMAIL/PHONE). Use o valor retornado por POST /pix/keys/verifications.
- otpCodestringObrigatório na variante com OTP. Código numérico recebido por e-mail/SMS (geralmente 6 dígitos).
Exemplo de requisição
curl -X POST https://baas.staterpay.io/accounts/00000000-0000-0000-0000-000000000010/pix/keys \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.<payload>.<signature>" \ -H "X-Tenant-Id: 00000000-0000-0000-0000-000000000000" \ -d '{ "keyType": "EVP" }'Resposta
- keyobjectChave Pix cadastrada.
- key.idstring (UUID)ID interno da chave.
- key.keystringValor final da chave: UUID em EVP, CPF/CNPJ da entidade, ou o e-mail/telefone confirmado em EMAIL/PHONE.
- key.type"EVP" | "CPF" | "CNPJ" | "EMAIL" | "PHONE"Tipo da chave.
- key.status"ACTIVE" | "INACTIVE"Estado inicial — sempre ACTIVE em cadastro bem-sucedido.
{ "key": { "id": "00000000-0000-0000-0000-0000000000b1", "key": "00000000-0000-0000-0000-0000000000c0", "type": "EVP", "status": "ACTIVE" }}https://baas.staterpay.io