# Transferência interna (/docs/pix-processamento/tutoriais/internal-transfer)



<QuickLinks>
  <QuickLink href="/docs/pix-processamento/endpoints/internal-transfer/post_internal_transfer" title="POST /internal-transfer" method="POST" path="/internal-transfer" />

  <QuickLink href="/docs/pix-processamento/endpoints/internal-transfer/get_internal_transfer" title="GET /internal-transfer" method="GET" path="/internal-transfer" />

  <QuickLink href="/docs/pix-processamento/best-practices/idempotency" title="Idempotência" />

  <QuickLink href="/docs/pix-processamento/webhooks" title="Webhooks" />
</QuickLinks>

<Mermaid
  chart="`
flowchart LR
  A[&#x22;POST /internal-transfer&#x22;] --> B[&#x22;Débito do pagador&#x22;]
  B --> C[&#x22;Crédito do recebedor&#x22;]
  C --> D[&#x22;Callback COMPLETED&#x22;]
  D --> E[&#x22;GET /internal-transfer&#x22;]

  click A &#x22;/docs/pix-processamento/endpoints/internal-transfer/post_internal_transfer&#x22; &#x22;POST /internal-transfer&#x22;
  click D &#x22;/docs/pix-processamento/webhooks&#x22; &#x22;Webhooks&#x22;
  click E &#x22;/docs/pix-processamento/endpoints/internal-transfer/get_internal_transfer&#x22; &#x22;GET /internal-transfer&#x22;

  style A fill:#f59e0b,stroke:#d97706,color:#ffffff
  style D fill:#14ce71,stroke:#0eb464,color:#ffffff
`"
/>

## Quando usar [#quando-usar]

* Repasse entre contas da mesma operação (matriz/filial)
* Pagamento a parceiro que também é cliente PayZu
* Movimentação interna de saldo (carteiras, sub-contas operacionais)

## Criar transferência [#criar-transferência]

Você precisa do `accountNumber` (6 dígitos) tanto do pagador quanto do recebedor. O pagador deve casar com a conta autenticada pelo token.

<Tabs items="['curl', 'Node.js', 'Python']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.payzu.processamento.com/v1/internal-transfer \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "payerAccountNumber": "513579",
        "receiverAccountNumber": "987654",
        "amount": 100.50,
        "description": "Pagamento referente a fatura #1234",
        "callbackUrl": "https://seusite.com.br/webhooks/payzu",
        "clientReference": "transfer-abc-123"
      }'
    ```
  </Tab>

  <Tab value="Node.js">
    ```ts
    const res = await fetch('https://api.payzu.processamento.com/v1/internal-transfer', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        payerAccountNumber: '513579',
        receiverAccountNumber: '987654',
        amount: 100.50,
        description: 'Pagamento referente a fatura #1234',
        callbackUrl: 'https://seusite.com.br/webhooks/payzu',
        clientReference: 'transfer-abc-123',
      }),
    });
    ```
  </Tab>

  <Tab value="Python">
    ```python
    res = requests.post(
        'https://api.payzu.processamento.com/v1/internal-transfer',
        headers={
            'Authorization': f'Bearer {os.environ["PAYZU_TOKEN"]}',
            'Content-Type': 'application/json',
        },
        json={
            'payerAccountNumber': '513579',
            'receiverAccountNumber': '987654',
            'amount': 100.50,
            'description': 'Pagamento referente a fatura #1234',
            'callbackUrl': 'https://seusite.com.br/webhooks/payzu',
            'clientReference': 'transfer-abc-123',
        },
    )
    ```
  </Tab>
</Tabs>

### Campos [#campos]

| Campo                   | Tipo   | Obrigatório | Descrição                                           |
| ----------------------- | ------ | ----------- | --------------------------------------------------- |
| `payerAccountNumber`    | string | Sim         | Conta pagadora (6 dígitos). Deve casar com o token. |
| `receiverAccountNumber` | string | Sim         | Conta destino (6 dígitos).                          |
| `amount`                | number | Sim         | Valor em BRL. Mínimo R$ 0,01.                       |
| `description`           | string | Não         | Texto livre de até 140 caracteres.                  |
| `callbackUrl`           | string | Não         | URL para receber atualizações.                      |
| `clientReference`       | string | Não         | Identificador externo (idempotência). Máx 64 chars. |
| `virtualAccount`        | string | Não         | Subconta virtual (multi-tenant). Máx 50 chars.      |

Schema completo em [`POST /internal-transfer`](/docs/pix-processamento/endpoints/internal-transfer/post_internal_transfer).

## Consultar [#consultar]

Aceita `id`, `clientReference` ou `virtualAccount` (**use apenas um**).

```bash
curl "https://api.payzu.processamento.com/v1/internal-transfer?clientReference=transfer-abc-123" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"
```

## Diferenças vs Saque Pix [#diferenças-vs-saque-pix]

| Aspecto       | Transferência interna       | Saque Pix (`/withdraw`) |
| ------------- | --------------------------- | ----------------------- |
| Destino       | Conta PayZu                 | Qualquer banco/conta    |
| Tarifa        | Conforme tabela da conta    | Conforme tabela         |
| Liquidação    | Instantânea                 | Pix em segundos         |
| Identificador | `accountNumber` (6 dígitos) | Chave Pix ou QR Code    |

<Callout type="info">
  O `accountNumber` da conta destino vem do parceiro PayZu. A plataforma não expõe diretório público de contas.
</Callout>