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

# Create Transfer

> Create a new payout transfer to an external beneficiary via PIX

## Request Body

<ParamField body="merchant_id" type="integer">
  Merchant ID of the account creating the payout. Required when there is more than one account under your umbrella (sellers).

  Example: `123`
</ParamField>

<ParamField body="amount" type="number" required>
  The payout amount in decimal format.

  Example: `150.75`
</ParamField>

<ParamField body="invoice" type="string" required>
  Unique invoice identifier for this transfer.

  Example: `PEDIDO-12345`
</ParamField>

<ParamField body="beneficiary" type="object" required>
  Beneficiary information.

  <Expandable title="Beneficiary Object">
    <ParamField body="name" type="string" required>
      Beneficiary's full name.

      Max length: `100` characters
    </ParamField>

    <ParamField body="document" type="object" required>
      Beneficiary's document.

      <Expandable title="Document Object">
        <ParamField body="type" type="string" required>
          Document type.

          Allowed values: `CPF`, `CNPJ`
        </ParamField>

        <ParamField body="number" type="string" required>
          Document number (digits only).
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="notification_url" type="string">
  URL where webhook notifications will be sent.

  Max length: `255` characters

  Example: `https://meusite.com/webhook`
</ParamField>

<ParamField body="pix" type="object" required>
  PIX payment information. Use either `pix_key` OR bank account details.

  <Expandable title="PIX Object">
    <ParamField body="pix_key" type="string">
      PIX key (CPF, CNPJ, email, phone, or random key). Use this for payments via PIX key.

      **Note**: When using `pix_key`, bank account fields are not required.
    </ParamField>

    <ParamField body="ispb" type="string">
      Bank ISPB code. Required when using bank account details.
    </ParamField>

    <ParamField body="bank_branch" type="string">
      Bank branch number. Required when using bank account details.
    </ParamField>

    <ParamField body="bank_branch_digit" type="string">
      Bank branch digit. Required when using bank account details.
    </ParamField>

    <ParamField body="account" type="string">
      Bank account number. Required when using bank account details.
    </ParamField>

    <ParamField body="account_digit" type="string">
      Bank account digit. Required when using bank account details.
    </ParamField>

    <ParamField body="account_type" type="string">
      Account type. Required when using bank account details.

      Allowed values: `CHECKING`, `SAVINGS`
    </ParamField>
  </Expandable>
</ParamField>

## Request Examples

### PIX Key

```bash cURL - PIX Key theme={null}
curl --request POST \
  --url https://api.sandbox.wepayout.com.br/v2/payout/transfers \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "merchant_id": 123,
    "amount": 150.75,
    "invoice": "PEDIDO-12345",
    "beneficiary": {
      "name": "João da Silva",
      "document": {
        "type": "CPF",
        "number": "12345678901"
      }
    },
    "notification_url": "https://meusite.com/webhook",
    "pix": {
      "pix_key": "joao@email.com"
    }
  }'
```

### Bank Account Details

```bash cURL - Bank Account theme={null}
curl --request POST \
  --url https://api.sandbox.wepayout.com.br/v2/payout/transfers \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "merchant_id": 123,
    "amount": 2500.00,
    "invoice": "FATURA-98765",
    "beneficiary": {
      "name": "Maria Oliveira",
      "document": {
        "type": "CPF",
        "number": "98765432100"
      }
    },
    "notification_url": "https://meusite.com/webhook",
    "pix": {
      "ispb": "00000000",
      "bank_branch": "1234",
      "bank_branch_digit": "1",
      "account": "987654",
      "account_digit": "0",
      "account_type": "CHECKING"
    }
  }'
```

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "id": 98765,
    "source_wallet_id": "wallet-uuid-source",
    "destination_wallet_id": "wallet-uuid-destination",
    "amount": 10000,
    "currency": "BRL",
    "description": "Transfer between accounts",
    "status": {
      "id": 1,
      "name": "Completed"
    },
    "external_id": "TRANSFER-001",
    "created_at": "2024-06-13T11:00:00.000000Z",
    "updated_at": "2024-06-13T11:00:00.000000Z"
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "message": "Insufficient balance"
  }
  ```
</ResponseExample>

## Related Resources

<CardGroup cols={2}>
  <Card title="Create Payment" icon="money-bill-transfer" href="/api-reference/cash-out/payout/create-payment">
    Create an external payout payment
  </Card>

  <Card title="Get Balance" icon="wallet" href="/api-reference/account/get-balance">
    Check your wallet balance before creating transfers
  </Card>
</CardGroup>