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

# Transferir por Pix

> Envie saldo por Pix usando chave, Copia e Cola ou QR Code com a NyxPag API: formatos de destino, valor mínimo, coverFee, erros e idempotência.

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

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

## Regras que valem para toda transferência

| Regra | Detalhe |
| - | - |
| Valor mínimo | R\$ 3,00 |
| Idempotência | `Idempotency-Key` ou `externalId`, obrigatório |
| Um saque por vez | Só pode haver **uma** transferência `pending` na conta. A segunda recebe `409` (`WITHDRAWAL_IN_PROGRESS`) até a primeira terminar |
| Saldo | Precisa de saldo disponível para o valor mais a tarifa |
| Rota | A NyxPag escolhe por onde a transferência sai. Você não escolhe |

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

## Dois formatos de destino

### Moderno: `destination` (recomendado)

| Campo | Tipo | Obrigatório | Valores |
| - | - | - | - |
| `destination.type` | string | Sim | `pix_key`, `pix_copy_paste` ou `qr_code` |
| `destination.value` | string | Sim | A chave ou o BR Code, até 1024 caracteres |
| `destination.keyType` | string | Só com `pix_key` | `cpf`, `cnpj`, `email`, `phone` ou `random` |
| `amount` | number | Depende | Veja a tabela abaixo |

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

| Destino | `amount` |
| - | - |
| `pix_key` | **Obrigatório** |
| `pix_copy_paste` / `qr_code` com valor definido no código | **Omita.** O valor do código é o que vale |
| `pix_copy_paste` / `qr_code` estático, sem valor | **Obrigatório** |

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

## Transferir para uma chave Pix

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl -X POST https://api.nyxpag.com.br/v1/transfers \
    -H "Authorization: Bearer $NYXPAG_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: saque-0001" \
    -d '{
      "amount": 150.00,
      "description": "Repasse de outubro",
      "destination": {
        "type": "pix_key",
        "value": "52998224725",
        "keyType": "cpf"
      }
    }'
  ```

  ```javascript JavaScript theme={"dark"}
  const res = await fetch("https://api.nyxpag.com.br/v1/transfers", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.NYXPAG_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": "saque-0001",
    },
    body: JSON.stringify({
      amount: 150.0,
      description: "Repasse de outubro",
      destination: { type: "pix_key", value: "52998224725", keyType: "cpf" },
    }),
  });

  const body = await res.json();
  if (!res.ok) throw new Error(`${res.status} ${body.error.code}: ${body.error.message}`);
  console.log(body.data.id, body.data.status);
  ```

  ```python Python theme={"dark"}
  import os
  import requests

  res = requests.post(
      "https://api.nyxpag.com.br/v1/transfers",
      headers={
          "Authorization": f"Bearer {os.environ['NYXPAG_API_KEY']}",
          "Idempotency-Key": "saque-0001",
      },
      json={
          "amount": 150.00,
          "description": "Repasse de outubro",
          "destination": {"type": "pix_key", "value": "52998224725", "keyType": "cpf"},
      },
      timeout=15,
  )
  body = res.json()
  if not res.ok:
      raise RuntimeError(f"{res.status_code} {body['error']['code']}: {body['error']['message']}")
  print(body["data"]["id"], body["data"]["status"])
  ```

  ```php PHP theme={"dark"}
  <?php
  $ch = curl_init('https://api.nyxpag.com.br/v1/transfers');
  curl_setopt_array($ch, [
      CURLOPT_POST => true,
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => [
          'Authorization: Bearer ' . getenv('NYXPAG_API_KEY'),
          'Content-Type: application/json',
          'Idempotency-Key: saque-0001',
      ],
      CURLOPT_POSTFIELDS => json_encode([
          'amount' => 150.00,
          'description' => 'Repasse de outubro',
          'destination' => ['type' => 'pix_key', 'value' => '52998224725', 'keyType' => 'cpf'],
      ]),
  ]);
  $body = json_decode(curl_exec($ch), true);
  echo $body['data']['id'] . ' ' . $body['data']['status'];
  ```
</CodeGroup>

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

<Tabs>
  <Tab title="Copia e Cola">
    ```json theme={"dark"}
    {
      "destination": {
        "type": "pix_copy_paste",
        "value": "00020126580014BR.GOV.BCB.PIX0136...6304E2CA"
      }
    }
    ```
  </Tab>

  <Tab title="QR Code">
    ```json theme={"dark"}
    {
      "destination": {
        "type": "qr_code",
        "value": "00020126580014BR.GOV.BCB.PIX0136...6304E2CA"
      }
    }
    ```
  </Tab>

  <Tab title="Código estático sem valor">
    ```json theme={"dark"}
    {
      "amount": 80.00,
      "destination": {
        "type": "pix_copy_paste",
        "value": "00020126580014BR.GOV.BCB.PIX0136...6304E2CA"
      }
    }
    ```
  </Tab>
</Tabs>

Lembre de enviar `Idempotency-Key` (ou `externalId`) em todos.

## A resposta

```json 201 Created theme={"dark"}
{
  "success": true,
  "idempotent": false,
  "data": {
    "id": "out_mabc123_0123456789abcdef",
    "externalId": "saque-0001",
    "direction": "out",
    "type": "withdrawal",
    "method": "pix",
    "status": "pending",
    "processingState": "monitoring",
    "amount": 150,
    "fee": 1,
    "netAmount": 150,
    "debitedAmount": 151,
    "recipientAmount": 150,
    "description": "Repasse de outubro",
    "approvedAt": null,
    "createdAt": "2026-10-03T15:00:00.000Z",
    "updatedAt": "2026-10-03T15:00:00.000Z"
  },
  "requestId": "req_01H..."
}
```

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

| Campo | O que é |
| - | - |
| `amount` / `recipientAmount` / `netAmount` | O que o **destinatário recebe** |
| `fee` | A tarifa que você paga |
| `debitedAmount` | O que **sai do seu saldo** (o valor mais a tarifa, quando `coverFee` é `true`) |

### Códigos de resposta

| Código | Significado | Ação |
| - | - | - |
| `201` | Transferência solicitada | Aguarde o webhook |
| `200` | Repetição idempotente | Use a resposta |
| `202` | Em reconciliação automática | **Não é envio confirmado.** Aguarde `approved` |

<Warning>
  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`](/webhooks/transacoes) ou por `GET /transactions/{id}`.
</Warning>

## coverFee: quem paga a tarifa

| `coverFee` | Sai do seu saldo | O destinatário recebe |
| - | - | - |
| `true` (padrão) | `amount` mais a tarifa | `amount` inteiro |
| `false` | `amount` | `amount` menos 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.

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

## Erros comuns

| HTTP | `error.code` | Causa | O que fazer |
| - | - | - | - |
| `400` | `invalid_request` | Chave Pix e tipo de chave são obrigatórios | Envie `destination.value` e `destination.keyType` |
| `400` | `invalid_request` | Valor fora dos limites configurados para saque | Respeite o mínimo de R\$ 3,00 |
| `400` | `invalid_request` | Informe o valor para pagar este Pix Copia e Cola | Código estático sem valor: envie `amount` |
| `400` | `idempotency_key_required` | Sem chave de idempotência | Envie `Idempotency-Key` ou `externalId` |
| `409` | `WITHDRAWAL_IN_PROGRESS` | Já existe um saque pendente na conta | Aguarde o anterior terminar |
| `409` | `idempotency_conflict` | Mesma chave, corpo diferente | Veja [Idempotência](/guides/idempotencia) |
| `422` | `operation_refused` | Saldo insuficiente | Confira o [saldo](/guides/pix/saldo) |
| `422` | `operation_refused` | Saques desabilitados para a API, ou rota sem suporte àquele tipo de destino | Fale com o suporte |
| `423` | `invalid_request` | Saques da conta temporariamente bloqueados pela administração | Fale com o suporte |

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

<Card title="Idempotência" icon="repeat" href="/guides/idempotencia">
  Como gerar, guardar e reutilizar a chave com segurança.
</Card>

<CardGroup cols={2}>
  <Card title="Acompanhar transações" icon="search" href="/guides/pix/acompanhar">
    Consulte o estado da transferência pelo ID ou pelo `externalId`.
  </Card>

  <Card title="Solicitar transferência Pix" icon="code" href="/api-reference/transferências/solicitar-transferência-pix">
    Referência completa do endpoint.
  </Card>
</CardGroup>


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