> ## 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 Payout with Inline Markup

> Create a payout payment with inline markup configuration.

# Create Payout with Inline Markup

When creating a payout payment, you can include an `inline markup` object in the request payload.

<Note>
  **Inline markup takes precedence**: If you send a `markup` object in the payment creation request, it will override any global or submerchant markup configurations.
</Note>

## Markup Object Structure

The `markup` object should be added to the request body when creating a payment via `POST /v2/payout/payments`.

<ParamField body="markup" type="object">
  Optional inline markup configuration for this specific payment.

  <Expandable title="Markup Object">
    <ParamField body="mode" type="string" required>
      How the markup value will be applied.

      Allowed values:

      * `fixed`: fixed amount per payment
      * `percent`: percentage over the payment amount
    </ParamField>

    <ParamField body="amount" type="number" required>
      Markup value to be applied.

      Constraints:

      * Must be greater than or equal to `0.01`
    </ParamField>

    <ParamField body="min_charge_value" type="number">
      Minimum markup amount when mode is `percent`.

      Business rules:

      * **Required** when `mode` = `percent`
      * **Prohibited** when `mode` = `fixed`
      * Must be greater than or equal to `0.01`
    </ParamField>

    <ParamField body="max_charge_value" type="number">
      Maximum markup amount when mode is `percent`.

      Business rules:

      * **Optional**
      * Must be greater than or equal to `min_charge_value`
      * **Prohibited** when `mode` = `fixed`
    </ParamField>
  </Expandable>
</ParamField>

<Warning>
  When `mode` is `fixed`, do **not** send `min_charge_value` or `max_charge_value`.
</Warning>

## Request Examples

<CodeGroup>
  ```json PIX with Percent Markup theme={null}
  {
    "payment_method": "PIX",
    "invoice": "e3317882-f821-455b-b082-dc3ba36e8a57",
    "currency": "BRL",
    "amount": 100.50,
    "country": "BR",
    "beneficiary": {
      "name": "John Doe",
      "document": {
        "type": "CPF",
        "number": "12345678901"
      },
      "pix": {
        "key": "12345678901"
      }
    },
    "markup": {
      "mode": "percent",
      "amount": 2.5,
      "min_charge_value": 0.50,
      "max_charge_value": 10.00
    }
  }
  ```

  ```json PIX with Fixed Markup theme={null}
  {
    "payment_method": "PIX",
    "invoice": "e3317882-f821-455b-b082-dc3ba36e8a57",
    "currency": "BRL",
    "amount": 100.50,
    "country": "BR",
    "beneficiary": {
      "name": "John Doe",
      "document": {
        "type": "CPF",
        "number": "12345678901"
      },
      "pix": {
        "key": "12345678901"
      }
    },
    "markup": {
      "mode": "fixed",
      "amount": 5.0
    }
  }
  ```

  ```bash cURL - PIX with Percent Markup theme={null}
  curl -X POST "https://api.sandbox.wepayout.com.br/v2/payout/payments" \
    -H "Authorization: Bearer YOUR_TOKEN_HERE" \
    -H "Content-Type: application/json" \
    -d '{
      "payment_method": "PIX",
      "invoice": "e3317882-f821-455b-b082-dc3ba36e8a57",
      "currency": "BRL",
      "amount": 100.50,
      "country": "BR",
      "beneficiary": {
        "name": "John Doe",
        "document": {
          "type": "CPF",
          "number": "12345678901"
        },
        "pix": {
          "key": "12345678901",
          "key_type": "CPF"
        }
      },
      "markup": {
        "mode": "percent",
        "amount": 2.5,
        "min_charge_value": 0.50,
        "max_charge_value": 10.00
      }
    }'
  ```

  ```bash cURL - PIX with Fixed Markup theme={null}
  curl -X POST "https://api.sandbox.wepayout.com.br/v2/payout/payments" \
    -H "Authorization: Bearer YOUR_TOKEN_HERE" \
    -H "Content-Type: application/json" \
    -d '{
      "payment_method": "PIX",
      "invoice": "e3317882-f821-455b-b082-dc3ba36e8a57",
      "currency": "BRL",
      "amount": 100.50,
      "country": "BR",
      "beneficiary": {
        "name": "John Doe",
        "document": {
          "type": "CPF",
          "number": "12345678901"
        },
        "pix": {
          "key": "12345678901",
          "key_type": "CPF"
        }
      },
      "markup": {
        "mode": "fixed",
        "amount": 5.0
      }
    }'
  ```
</CodeGroup>

## Response

<ResponseField name="id" type="integer">
  WEpayment's auto generated id, use this id to perform conciliation or perform queries via API / Dashboard.
</ResponseField>

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

  <Expandable title="Merchant">
    <ResponseField name="id" type="integer">
      Id of the WE account that created the payout.
    </ResponseField>

    <ResponseField name="name" type="string">
      Name of the WE account that created the payout.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="payment_method" type="string">
  Payment method used for the payout.

  Values: `PIX`
</ResponseField>

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

<ResponseField name="currency" type="string">
  Currency code (ISO 4217).
</ResponseField>

<ResponseField name="invoice" type="string">
  Invoice identifier.
</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>
  </Expandable>
</ResponseField>

<ResponseField name="markup" type="object">
  Inline markup configuration applied to this payment.

  <Expandable title="Markup Object">
    <ResponseField name="mode" type="string">
      Markup mode applied.

      Values: `fixed`, `percent`
    </ResponseField>

    <ResponseField name="amount" type="number">
      Markup value configured for this payment.
    </ResponseField>

    <ResponseField name="min_charge_value" type="number or null">
      Minimum markup value when `mode` is `percent`. Will be `null` when `mode` is `fixed`.
    </ResponseField>

    <ResponseField name="max_charge_value" type="number or null">
      Maximum markup value when `mode` is `percent`. Will be `null` when `mode` is `fixed` or when not specified.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 201 Created - PIX Payment with Markup theme={null}
  {
    "id": 12345,
    "merchant": {
      "id": 477,
      "name": "Merchant Name"
    },
    "payment_method": "PIX",
    "amount": "R$ 100,50",
    "currency": "BRL",
    "invoice": "e3317882-f821-455b-b082-dc3ba36e8a57",
    "status": {
      "id": 1,
      "name": "Awaiting"
    },
    "beneficiary": {
      "name": "John Doe",
      "document": {
        "type": "CPF",
        "number": "12345678901"
      }
    },
    "markup": {
      "mode": "percent",
      "amount": 2.5,
      "min_charge_value": 0.50,
      "max_charge_value": 10.00
    },
    "purpose": null,
    "paid_at": null,
    "created_at": "2024-01-15T10:30:00.000000Z",
    "updated_at": "2024-01-15T10:30:00.000000Z"
  }
  ```

  ```json 422 Unprocessable Entity - Markup Only for PIX theme={null}
  {
    "message": "The given data was invalid",
    "errors": {
      "markup": [
        "Markup is only allowed for PIX payments"
      ]
    }
  }
  ```

  ```json 422 Unprocessable Entity - Invalid markup.mode theme={null}
  {
    "message": "The given data was invalid",
    "errors": {
      "markup.mode": [
        "The selected markup.mode is invalid."
      ]
    }
  }
  ```

  ```json 422 Unprocessable Entity - Invalid markup.amount theme={null}
  {
    "message": "The given data was invalid",
    "errors": {
      "markup.amount": [
        "The markup.amount must be at least 0.01."
      ]
    }
  }
  ```

  ```json 422 Unprocessable Entity - Missing min_charge_value for percent mode theme={null}
  {
    "message": "The given data was invalid",
    "errors": {
      "markup.min_charge_value": [
        "The markup.min_charge value field is required when markup.mode is percent."
      ]
    }
  }
  ```

  ```json 422 Unprocessable Entity - Invalid charge values for fixed mode theme={null}
  {
    "message": "The given data was invalid",
    "errors": {
      "markup.min_charge_value": [
        "Invalid charge values for fixed mode"
      ]
    }
  }
  ```

  ```json 422 Unprocessable Entity - Markup Required theme={null}
  {
    "message": "The given data was invalid",
    "errors": {
      "markup": [
        "Inline markup is required when no global markup is configured"
      ]
    }
  }
  ```

  ```json 500 Internal Server Error theme={null}
  {
    "message": "Internal error"
  }
  ```
</ResponseExample>

## How It Works

1. **Priority**: The inline markup configuration takes precedence over global and submerchant markup settings.

2. **Calculation** (for percent mode):
   * The system calculates: `payment_amount * (amount / 100)`
   * If calculated value \< `min_charge_value` → applies `min_charge_value`
   * If calculated value > `max_charge_value` → applies `max_charge_value`
   * Otherwise → applies the calculated value

3. **Fixed Mode**: When using `fixed` mode, the markup amount is applied directly regardless of the transaction value.

## Related Resources

<CardGroup cols={2}>
  <Card title="Create Payment" icon="plus" href="/api-reference/cash-out/payout/create-payment">
    Complete documentation for creating payout payments
  </Card>

  <Card title="About Markup" icon="circle-info" href="/markup/about-markup">
    Learn about markup types and configuration levels
  </Card>
</CardGroup>