Skip to main content
Quando você tem a chave Pix do recebedor (CPF, CNPJ, e-mail, telefone ou chave aleatória EVP), o fluxo acontece em dois passos: primeiro você consulta a chave para obter o endToEndId e os dados da conta destino, depois executa o pagamento com esse identificador.

Passo a passo

1

Inicialize o pagamento consultando a chave

Chame o endpoint de inicialização informando a chave Pix do recebedor. A API consulta o DICT (Diretório de Identificadores de Contas Transacionais) do Banco Central e retorna os dados da conta vinculada.
O endToEndId retornado é de uso único e tem validade curta — use-o imediatamente na etapa seguinte.
Passe holderDocument no corpo da requisição se quiser verificar se a chave pertence a um CPF ou CNPJ específico. O campo keyBelongsHolder na resposta indica o resultado da verificação — útil para confirmar que o pagador está enviando para a pessoa certa.
2

Confirme os dados do recebedor

Antes de executar o pagamento, exiba os dados do beneficiary retornado para que o usuário confirme que está enviando para a pessoa certa. Isso evita erros e é uma boa prática de UX para qualquer produto financeiro.Os dados do titular aparecem com o documento parcialmente mascarado — isso é comportamento padrão do DICT por privacidade.
3

Execute a transferência

Com o endToEndId em mãos, execute o pagamento. Use initiationType: "KEY" para indicar que a iniciação foi feita via chave Pix.
O status inicial é PIX_PROCESSING. O status final (PIX_EFFECTIVE ou PIX_ERROR) é entregue via webhook — não use polling.
O IdempotencyKey no header é obrigatório. Envie um GUID único por requisição. Se a mesma chamada for reenviada com o mesmo IdempotencyKey, a API retornará o resultado original sem criar um pagamento duplicado. Veja Idempotência.

Chaves disponíveis no sandbox

No ambiente sandbox, você só pode transferir para chaves que existam nesse ambiente. Use as chaves abaixo para testar. Um pagamento não pode ser feito de uma conta para ela mesma.

Referência da API

Inicializar pagamento por chave

POST /pix/dict/payment-initialization

Executar transferência

POST /transfers