# Internal transfer (/en/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;Payer debit&#x22;]
  B --> C[&#x22;Receiver credit&#x22;]
  C --> D[&#x22;COMPLETED callback&#x22;]
  D --> E[&#x22;GET /internal-transfer&#x22;]

  click A &#x22;/en/docs/pix-processamento/endpoints/internal-transfer/post_internal_transfer&#x22; &#x22;POST /internal-transfer&#x22;
  click D &#x22;/en/docs/pix-processamento/webhooks&#x22; &#x22;Webhooks&#x22;
  click E &#x22;/en/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
`"
/>

## When to use [#when-to-use]

* Transfer between accounts of the same operation (headquarters/branch)
* Payment to a partner that is also a PayZu customer
* Internal balance movement (wallets, operational sub-accounts)

## Create transfer [#create-transfer]

You need the `accountNumber` (6 digits) of both payer and receiver. The payer must match the account authenticated by the 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": "000000",
        "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: '000000',
        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': '000000',
            'receiverAccountNumber': '987654',
            'amount': 100.50,
            'description': 'Pagamento referente a fatura #1234',
            'callbackUrl': 'https://seusite.com.br/webhooks/payzu',
            'clientReference': 'transfer-abc-123',
        },
    )
    ```
  </Tab>
</Tabs>

### Fields [#fields]

| Field                   | Type   | Required | Description                                       |
| ----------------------- | ------ | -------- | ------------------------------------------------- |
| `payerAccountNumber`    | string | Yes      | Payer account (6 digits). Must match the token.   |
| `receiverAccountNumber` | string | Yes      | Destination account (6 digits).                   |
| `amount`                | number | Yes      | Amount in BRL. Minimum R$ 0.01.                   |
| `description`           | string | No       | Free text up to 500 characters.                   |
| `callbackUrl`           | string | No       | URL to receive updates.                           |
| `clientReference`       | string | No       | External identifier (idempotência). Max 64 chars. |
| `virtualAccount`        | string | No       | Virtual sub-account (multi-tenant). Max 50 chars. |

Full schema at [`POST /internal-transfer`](/docs/pix-processamento/endpoints/internal-transfer/post_internal_transfer).

## Query [#query]

Accepts `id`, `clientReference` or `virtualAccount` (**use only one**).

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

## Differences vs Pix Payment [#differences-vs-pix-payment]

| Aspect      | Internal transfer          | Pix withdrawal (`/withdraw`) |
| ----------- | -------------------------- | ---------------------------- |
| Destination | PayZu account              | Any bank/account             |
| Fee         | Per account fee schedule   | Per fee schedule             |
| Settlement  | Instant                    | Pix in seconds               |
| Identifier  | `accountNumber` (6 digits) | Pix key or QR Code           |

<Callout type="info">
  The destination account's `accountNumber` comes from the PayZu partner. The platform does not expose a public account directory.
</Callout>