Skip to main content
POST /transfers envia saldo da sua conta por Pix. O destino pode ser uma chave Pix, um Copia e Cola ou um QR Code. Exige a permissão transfers:write.
Transferência Pix não tem volta. Sempre envie uma chave de idempotência, confira o destino antes e use uma chave de API só para saques, com IP restrito.

Regras que valem para toda transferência

O limite de um saque pendente por vez vale para a conta toda, não para a chave. Se você paga vários beneficiários, enfileire do seu lado e envie um por vez, esperando transaction.approved ou failed de cada.

Dois formatos de destino

Moderno: destination (recomendado)

Legado: pixKey e pixKeyType

Continua funcionando para chave Pix: amount, pixKey e pixKeyType (cpf, cnpj, email, phone, random). Para código novo, prefira destination.

Quando enviar amount

Para pix_copy_paste e qr_code, o value é o texto do BR Code (o Copia e Cola), não uma imagem. A NyxPag valida o código com a processadora antes de enviar. Se o código já define um valor, ele prevalece sobre o amount que você mandar.

Transferir para uma chave Pix

Transferir por Copia e Cola ou QR Code

O corpo é o mesmo, mudando o type. Para o QR Code, leia a imagem no seu lado e envie o texto do código em value.
Lembre de enviar Idempotency-Key (ou externalId) em todos.

A resposta

201 Created
Os valores são ilustrativos: a tarifa real depende da sua conta. Nas transferências:

Códigos de resposta

Só considere o dinheiro enviado quando o status for approved. 201 e 202 dizem apenas que o pedido foi aceito. Acompanhe pelo webhook transaction.approved ou por GET /transactions/{id}.

coverFee: quem paga a tarifa

Exemplo com tarifa ilustrativa de R$ 1,00 e amount: 150: com true, saem R$ 151,00 e o destinatário recebe R$ 150,00. Com false, saem R$ 150,00 e o destinatário recebe R$ 149,00.
Em Copia e Cola e QR Code, a NyxPag sempre aplica coverFee: true, para que o valor pago bata exatamente com o do código.

Erros comuns

Prevenção de duplicidade

Toda transferência precisa de chave de idempotência, pelo cabeçalho Idempotency-Key ou pelo campo externalId. Repetir a mesma chave com o mesmo corpo devolve a operação original, sem enviar o dinheiro duas vezes. Para transferências, o cabeçalho é o caminho mais direto.

Idempotência

Como gerar, guardar e reutilizar a chave com segurança.

Acompanhar transações

Consulte o estado da transferência pelo ID ou pelo externalId.

Solicitar transferência Pix

Referência completa do endpoint.