> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pagmaster.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Transferências Pix

> Envios automáticos com API key, reserva de saldo e consulta de status.

## 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.

```bash theme={null}
curl -X POST https://api.pagmaster.site/api/v1/public/pix/transfers \
  -H "Authorization: Bearer $MASTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amountCents": 1000,
    "pixKey": "recebedor@exemplo.com",
    "pixKeyType": "EMAIL",
    "description": "Repasse do pedido 123",
    "requestKey": "4b2acc8a-b838-4640-956b-131da49588a4"
  }'
```

`amountCents` é o **total descontado do saldo, incluindo a taxa**: mínimo `1000` (R$ 10,00) e má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 R$ 10,00 e o destinatário recebe R$ 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](/webhooks). `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.

<Warning>
  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.
</Warning>

## Compatibilidade com rascunhos antigos

`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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.