Chave PIX
Saque só vai para uma chave PIX sua, cadastrada e verificada. E "sua" aqui é literal.
A chave é o seu documento
A chave de saque é o CPF ou o CNPJ aprovado no seu KYC. Você não escolhe o número: ele é o documento da conta.
O cadastro acontece no painel e o corpo do pedido tem só o tipo, cpf ou cnpj, que precisa bater
com o tipo do documento da conta. Não existe campo para digitar a chave.
Isso resolve a titularidade por construção. Não há como cadastrar a chave de outra pessoa, e não há como uma chave apontar para uma conta que não é a sua.
Consequência direta: chave de e-mail, de telefone e aleatória não são mais criadas. Contas que já tinham uma dessas continuam podendo usá-la; contas novas, não.
Sem KYC não há chave, e sem chave não há saque
Cadastrar a chave exige documento aprovado. Sem isso, a resposta é 403 kyc_required.
Isso vale nos dois ambientes. O saque em produção já exige KYC por si só; no ambiente de teste o saque não exige KYC, mas exige chave verificada, e a chave exige KYC. Na prática, o fluxo de saque só é testável depois que a sua análise sair.
Outras regras do cadastro: no máximo 5 chaves ativas, e a mesma chave não entra duas vezes
(409 invalid_state). Desativar uma chave não a apaga, porque saques antigos apontam para ela.
Aprovação do parceiro
Dependendo do processador que atende a sua conta, a chave ainda precisa ser registrada e aprovada por ele antes de poder sacar. Isso leva alguns instantes e não exige nada de você.
Enquanto essa aprovação não sai, o saque é recusado com 409 pix_key_not_verified, e details.reason
traz o motivo. Não é erro: é espera. Tente de novo em seguida.
O que a API mostra
A chave é cadastrada e removida pelo painel. Pela chave de API você lista as chaves que podem sacar:
GET /v1/pix-keys
A listagem por API traz apenas as chaves verificadas e ativas, que são exatamente as que servem para
pix_key_id no pedido de saque. Se ela vier vazia, não adianta tentar sacar.
O key volta mascarado nas respostas. Isso é proposital e não tem como desligar.
Próximo passo
Referência: Lista as chaves PIX verificadas e ativas do seller.