POST /transfers. O que muda é a etapa de inicialização anterior (quando necessária) e o valor do campo initiationType enviado no corpo da transferência.
Formas de iniciação disponíveis
Por chave Pix
Você tem a chave Pix do recebedor (CPF, CNPJ, e-mail, telefone ou EVP). A API consulta o DICT e retorna os dados da conta antes de executar o pagamento.
Por dados bancários
Você tem os dados completos da conta destino (banco, agência, conta, CPF/CNPJ). Não há etapa de inicialização — o pagamento é executado diretamente.
Por QR Code
Você tem o payload de um QR Code (estático ou dinâmico). A API decodifica o payload, retorna os dados da cobrança e você executa o pagamento.
Qual forma usar?
| Por chave Pix | Por dados bancários | Por QR Code | |
|---|---|---|---|
| Informação necessária | Chave Pix | Banco, agência, conta, CPF/CNPJ | Payload do QR Code |
| Etapa de inicialização | Sim (/pix/dict/payment-initialization) | Não | Sim (/pix/qrcode/payment-initialization) |
| Número de chamadas à API | 2 | 1 | 2 |
initiationType no transfer | KEY | (não enviado) | QR_CODE_STATIC ou QR_CODE_DYNAMIC |
| Caso de uso típico | Transferências P2P, pagamentos com chave conhecida | Pagamentos para contas sem chave cadastrada | Pagamento de cobranças emitidas por terceiros |
Como funciona o fluxo
Status do pagamento
| Status | Significado |
|---|---|
PIX_PROCESSING | Pagamento recebido e sendo processado |
PIX_WAITING_SPI_RESPONSE | Aguardando confirmação do Sistema de Pagamentos Instantâneos (BACEN) |
PIX_EFFECTIVE | Pagamento liquidado com sucesso |
PIX_ERROR | Pagamento falhou — verifique os detalhes para investigar |
PIX_REFUND_PAYMENT_UPDATED | Evento de devolução enviada |
Consultar um pagamento
Você pode consultar o status de qualquer pagamento a qualquer momento usando oendToEndId ou a IdempotencyKey da requisição original. Veja Consultar Pagamento.
Próximos passos
Pagar via chave Pix
Consulte a chave no DICT e execute a transferência.
Pagar via dados bancários
Envie diretamente para uma conta sem precisar de chave.
Pagar via QR Code
Decodifique um payload e execute o pagamento da cobrança.
Consultar pagamento
Consulte o status de transferências Pix, TED e devoluções.