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

> Create a new payout payment to transfer funds

## Request Body

<ParamField body="merchant_id" type="integer">
  Merchant id of the account that is creating the payout. The custom number will be different for sandbox and production environment.

  Is mandatory if there is more than one account under your umbrella (sellers).
</ParamField>

<ParamField body="payment_method" type="string" required>
  Payment method for the payout.

  Allowed values: `PIX`
</ParamField>

<ParamField body="currency" type="string" required>
  Currency code of the amount (ISO 4217).

  Example: `BRL`
</ParamField>

<ParamField body="country" type="string" required>
  Country code (ISO 3166-1 alpha-2).

  Example: `BR`
</ParamField>

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

  Example: `50.34`
</ParamField>

<ParamField body="invoice" type="string" required>
  Unique invoice identifier (UUID format recommended).

  Example: `e3317882-f821-455b-b082-dc3ba36e8a57`
</ParamField>

<ParamField body="description" type="string">
  Description or purpose of the payout.

  Max length: `255` characters
</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>

    <ParamField body="birthdate" type="string">
      Beneficiary's birthdate in format `YYYY-MM-DD`.
    </ParamField>

    <ParamField body="phone" type="string">
      Beneficiary's phone number.
    </ParamField>

    <ParamField body="address" type="object">
      Beneficiary's address information.

      <Expandable title="Address Object">
        <ParamField body="address" type="string">
          Street address.
        </ParamField>

        <ParamField body="city" type="string">
          City name.
        </ParamField>

        <ParamField body="country" type="string">
          Country code.
        </ParamField>

        <ParamField body="state_code" type="string">
          State code.
        </ParamField>

        <ParamField body="zip_code" type="string">
          ZIP/Postal code.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="remitter" type="object">
  Details of remitter. Mandatory for the remittance model. Payments from individuals to individuals.

  <Expandable title="Remitter Object">
    <ParamField body="name" type="string" required>
      Name of who is sending the payment (cash).

      Min: 1 character, Max: 150 characters
    </ParamField>

    <ParamField body="birthdate" type="string" required>
      Date of birth of who is sending the payment (cash).

      Format: `YYYY-MM-DD`

      Example: `1989-03-05`
    </ParamField>

    <ParamField body="country" type="string" required>
      Country of who is sending the payment (cash).

      Format: ISO 3166-1 alpha-2 (2 characters)

      Example: `US`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="originator_legal_entity" type="object">
  Legal entity information of the payment originator. Mandatory for crossborder merchants.

  <Expandable title="Originator Legal Entity Object">
    <ParamField body="name" type="string" required>
      Legal entity name of the originator.

      Max length: `125` characters
    </ParamField>

    <ParamField body="website" type="string" required>
      Legal entity website of the originator.

      Max length: `125` characters
    </ParamField>
  </Expandable>
</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="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>

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

  Max length: `255` characters
</ParamField>

<ParamField body="purpose" type="string">
  Purpose code for the transaction.

  Default: `20`
</ParamField>

<ParamField body="receipt_message" type="string">
  Custom message to appear on the receipt.
</ParamField>

## Response

<ResponseField name="id" type="integer">
  WEpayment's auto generated payout ID.
</ResponseField>

<ResponseField name="merchant" type="object">
  Merchant information.

  <Expandable title="Merchant">
    <ResponseField name="id" type="integer">
      Merchant ID.
    </ResponseField>

    <ResponseField name="name" type="string">
      Merchant name.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="payment_method" type="string">
  Payment method used.
</ResponseField>

<ResponseField name="country" type="string">
  Country code.
</ResponseField>

<ResponseField name="currency" type="string">
  Currency code.
</ResponseField>

<ResponseField name="amount" type="string">
  Payout amount formatted with currency symbol.
</ResponseField>

<ResponseField name="source_currency" type="string">
  Source currency if conversion was applied.
</ResponseField>

<ResponseField name="source_amount" type="string">
  Source amount if conversion was applied.
</ResponseField>

<ResponseField name="invoice" type="string">
  Invoice identifier.
</ResponseField>

<ResponseField name="description" type="string">
  Payout description.
</ResponseField>

<ResponseField name="authentication_code" type="string">
  Authentication code for the transaction.
</ResponseField>

<ResponseField name="rejection_description" type="string">
  Description if the payout was rejected.
</ResponseField>

<ResponseField name="notification_url" type="string">
  Webhook notification URL.
</ResponseField>

<ResponseField name="status" type="object">
  Payout status.

  <Expandable title="Status">
    <ResponseField name="id" type="integer">
      Status ID.
    </ResponseField>

    <ResponseField name="name" type="string">
      Status name (e.g., "Awaiting").
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="beneficiary" type="object">
  Beneficiary information.

  <Expandable title="Beneficiary">
    <ResponseField name="name" type="string">
      Beneficiary name.
    </ResponseField>

    <ResponseField name="document" type="object">
      Document information.
    </ResponseField>

    <ResponseField name="birthdate" type="string">
      Birthdate.
    </ResponseField>

    <ResponseField name="phone" type="string">
      Phone number.
    </ResponseField>

    <ResponseField name="address" type="object">
      Address information.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="receipt_message" type="string">
  Receipt message.
</ResponseField>

<ResponseField name="pix" type="object">
  PIX payment details.

  <Expandable title="PIX">
    <ResponseField name="pix_key" type="string">
      PIX key used (if applicable).
    </ResponseField>

    <ResponseField name="bank_code" type="string">
      Bank code.
    </ResponseField>

    <ResponseField name="bank_branch" type="string">
      Bank branch.
    </ResponseField>

    <ResponseField name="bank_branch_digit" type="string">
      Bank branch digit.
    </ResponseField>

    <ResponseField name="account" type="string">
      Account number.
    </ResponseField>

    <ResponseField name="account_digit" type="string">
      Account digit.
    </ResponseField>

    <ResponseField name="account_type" type="string">
      Account type.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="purpose" type="string">
  Transaction purpose code.
</ResponseField>

<ResponseField name="paid_at" type="string">
  Payment completion timestamp.
</ResponseField>

<ResponseField name="created_at" type="string">
  Creation timestamp.
</ResponseField>

<ResponseField name="updated_at" type="string">
  Last update timestamp.
</ResponseField>

## Request Examples

### PIX Key Payment

Use this method when you have the beneficiary's PIX key.

<CodeGroup>
  ```bash cURL - PIX Key theme={null}
  curl --location 'https://api.sandbox.wepayout.com.br/v2/payout/payments' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer YOUR_TOKEN' \
    --data '{
      "payment_method": "PIX",
      "currency": "BRL",
      "country": "BR",
      "amount": 43.34,
      "invoice": "c071bcc5-0c1c-450b-a47f-15fc5321fbe3",
      "beneficiary": {
        "name": "João Silva",
        "document": {
          "type": "CPF",
          "number": "82608288200"
        }
      },
      "pix": {
        "pix_key": "82608288200"
      }
    }'
  ```

  ```javascript JavaScript - PIX Key theme={null}
  const response = await fetch(
    'https://api.sandbox.wepayout.com.br/v2/payout/payments',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_TOKEN'
      },
      body: JSON.stringify({
        payment_method: 'PIX',
        currency: 'BRL',
        country: 'BR',
        amount: 43.34,
        invoice: 'c071bcc5-0c1c-450b-a47f-15fc5321fbe3',
        beneficiary: {
          name: 'João Silva',
          document: {
            type: 'CPF',
            number: '82608288200'
          }
        },
        pix: {
          pix_key: '82608288200'
        }
      })
    }
  );

  const payout = await response.json();
  console.log('Payout created:', payout);
  ```

  ```python Python - PIX Key theme={null}
  import requests

  url = 'https://api.sandbox.wepayout.com.br/v2/payout/payments'
  headers = {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_TOKEN'
  }

  payload = {
      'payment_method': 'PIX',
      'currency': 'BRL',
      'country': 'BR',
      'amount': 43.34,
      'invoice': 'c071bcc5-0c1c-450b-a47f-15fc5321fbe3',
      'beneficiary': {
          'name': 'João Silva',
          'document': {
              'type': 'CPF',
              'number': '82608288200'
          }
      },
      'pix': {
          'pix_key': '82608288200'
      }
  }

  response = requests.post(url, headers=headers, json=payload)
  payout = response.json()
  print('Payout created:', payout)
  ```
</CodeGroup>

### Bank Account Payment

Use this method when you have the beneficiary's bank account details.

<CodeGroup>
  ```bash cURL - Bank Account theme={null}
  curl --location 'https://api.sandbox.wepayout.com.br/v2/payout/payments' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer YOUR_TOKEN' \
    --data '{
      "payment_method": "PIX",
      "currency": "BRL",
      "country": "BR",
      "amount": 50.34,
      "invoice": "e3317882-f821-455b-b082-dc3ba36e8a57",
      "beneficiary": {
        "name": "Maria Santos",
        "document": {
          "type": "CPF",
          "number": "58713371126"
        }
      },
      "pix": {
        "ispb": "18236120",
        "bank_branch": "0496",
        "account": "51659",
        "account_digit": "7",
        "account_type": "CHECKING"
      }
    }'
  ```

  ```javascript JavaScript - Bank Account theme={null}
  const response = await fetch(
    'https://api.sandbox.wepayout.com.br/v2/payout/payments',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_TOKEN'
      },
      body: JSON.stringify({
        payment_method: 'PIX',
        currency: 'BRL',
        country: 'BR',
        amount: 50.34,
        invoice: 'e3317882-f821-455b-b082-dc3ba36e8a57',
        beneficiary: {
          name: 'Maria Santos',
          document: {
            type: 'CPF',
            number: '58713371126'
          }
        },
        pix: {
          ispb: '18236120',
          bank_branch: '0496',
          account: '51659',
          account_digit: '7',
          account_type: 'CHECKING'
        }
      })
    }
  );

  const payout = await response.json();
  console.log('Payout created:', payout);
  ```

  ```python Python - Bank Account theme={null}
  import requests

  url = 'https://api.sandbox.wepayout.com.br/v2/payout/payments'
  headers = {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_TOKEN'
  }

  payload = {
      'payment_method': 'PIX',
      'currency': 'BRL',
      'country': 'BR',
      'amount': 50.34,
      'invoice': 'e3317882-f821-455b-b082-dc3ba36e8a57',
      'beneficiary': {
          'name': 'Maria Santos',
          'document': {
              'type': 'CPF',
              'number': '58713371126'
          }
      },
      'pix': {
          'ispb': '18236120',
          'bank_branch': '0496',
          'account': '51659',
          'account_digit': '7',
          'account_type': 'CHECKING'
      }
  }

  response = requests.post(url, headers=headers, json=payload)
  payout = response.json()
  print('Payout created:', payout)
  ```
</CodeGroup>

<ResponseExample>
  ```json 201 Created - PIX Key theme={null}
  {
    "id": 124118,
    "merchant": {
      "id": 477,
      "name": "Merchant Name"
    },
    "payment_method": "PIX",
    "country": "BR",
    "currency": "BRL",
    "amount": "R$43.34",
    "source_currency": null,
    "source_amount": null,
    "invoice": "6cc85ff5-7a35-45cb-a8fd-22b9bbe27896",
    "description": null,
    "authentication_code": null,
    "rejection_description": "",
    "notification_url": null,
    "status": {
      "id": 7,
      "name": "Awaiting"
    },
    "beneficiary": {
      "name": "João Silva",
      "document": {
        "type": "CPF",
        "number": "82608288200"
      },
      "birthdate": null,
      "phone": null,
      "address": {
        "address": null,
        "city": null,
        "country": null,
        "state_code": null,
        "zip_code": null
      }
    },
    "receipt_message": "",
    "pix": {
      "pix_key": "82608288200",
      "bank_code": "",
      "bank_branch": null,
      "bank_branch_digit": null,
      "account": null,
      "account_digit": null,
      "account_type": ""
    },
    "purpose": "20",
    "paid_at": null,
    "created_at": "2025-11-21T14:59:59.000000Z",
    "updated_at": "2025-11-21T14:59:59.000000Z"
  }
  ```

  ```json 201 Created - Bank Account theme={null}
  {
    "id": 124117,
    "merchant": {
      "id": 477,
      "name": "Merchant Name"
    },
    "payment_method": "PIX",
    "country": "BR",
    "currency": "BRL",
    "amount": "R$50.34",
    "source_currency": null,
    "source_amount": null,
    "invoice": "27eb1281-e19f-4284-b4b5-b8f598be6148",
    "description": null,
    "authentication_code": null,
    "rejection_description": "",
    "notification_url": null,
    "status": {
      "id": 7,
      "name": "Awaiting"
    },
    "beneficiary": {
      "name": "Maria Santos",
      "document": {
        "type": "CPF",
        "number": "58713371126"
      },
      "birthdate": null,
      "phone": null,
      "address": {
        "address": null,
        "city": null,
        "country": null,
        "state_code": null,
        "zip_code": null
      }
    },
    "receipt_message": "",
    "pix": {
      "pix_key": null,
      "bank_code": "260",
      "bank_branch": null,
      "bank_branch_digit": null,
      "account": null,
      "account_digit": "7",
      "account_type": "CHECKING"
    },
    "purpose": "20",
    "paid_at": null,
    "created_at": "2025-11-21T14:59:24.000000Z",
    "updated_at": "2025-11-21T14:59:24.000000Z"
  }
  ```

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

## Related Resources

<CardGroup cols={2}>
  <Card title="Payout Webhook" icon="webhook" href="/cash-out/payout-webhook">
    Receive real-time payout status notifications
  </Card>

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