Envio automático pela API
POST /pix/transfers envia um Pix usando uma API key com permissão transfers. Não envia código de e-mail e não exige uma chamada de confirmação. A key autoriza a movimentação. Guarde-a no servidor e conceda essa permissão somente às integrações que precisam sacar.
Envie X-Master-Operation para selecionar o negócio. O saldo de outro negócio não cobre o saque. Bloqueios administrativos da conta e da plataforma também se aplicam aos envios por API.
amountCents é o total descontado do saldo, incluindo a taxa: mínimo 1000 (R10,00)emaˊximo‘1000000‘(R 10.000,00). Tipos de chave: EMAIL, CPF, CNPJ, PHONE e RANDOM. CPF/CNPJ usam só dígitos; telefone começa com +; chave aleatória usa UUID.
Taxa e reserva
A taxa padrão de saque é 0% + R$ 0,25, podendo variar conforme a conta. O registro guarda feeCents na criação. Alterações posteriores não mudam um saque já criado.
Uma solicitação de 1000 centavos com taxa 25 retorna debitAmountCents: 1000 e expectedNetAmountCents: 975: desconta R10,00eodestinataˊriorecebeR 9,75. netAmountCents, quando informado pela liquidante, é o líquido confirmado. Não desconte a taxa outra vez.
O saldo bruto é reservado atomicamente antes do envio. Repetir os mesmos dados com o mesmo requestKey não reserva nem envia novamente. Saques recusados ou cancelados pelo provedor liberam a reserva sem taxa. Saques pendentes ou incertos continuam reservados até a conciliação.
Consulta de status
Consulte GET /payments/{id} ou receba transfer.completed pelo webhook. pending indica processamento; completed confirma o envio. A consulta não autoriza nem confirma manualmente um pagamento.
O webhook é a primeira fonte de atualização. Após 5 segundos sem atualização, a Master agenda consultas autenticadas à liquidante; falhas usam espera crescente e limite compartilhado de consultas. Esse acompanhamento também funciona sem um navegador aberto.
Um timeout ou unknown pode indicar que o Pix já foi enviado. Preserve o mesmo requestKey e consulte a mesma operação. Nunca gere outro UUID para substituir um envio incerto.
POST /pix/transfers/{id}/confirm e /cancel permanecem somente para rascunhos legados em draft. Não fazem parte do novo fluxo automático. Uma referência usada em um rascunho com código não pode ser reutilizada para um envio automático.
A página Transferir do painel continua com confirmação por e-mail. Essa proteção do acesso pelo site é independente da autorização por API key.