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

> Create a payin charge with inline markup configuration.

# Create Payin with Inline Markup

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

<Note>
  **Inline markup takes precedence**: If you send a `markup` object in the charge 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 charge via `POST /v2/payin/payments`.

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

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

      Allowed values:

      * `fixed`: fixed amount per charge
      * `percent`: percentage over the charge 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": "YOUR-CODE1234",
    "currency": "BRL",
    "amount": 10000,
    "country": "BR",
    "buyer": {
      "name": "Buyer Name",
      "document": {
        "type": "CPF",
        "number": "34960826312"
      },
      "email": "buyer-email@wepayments.com.br"
    },
    "pix": {
      "expire_date": "2025-12-31T23:59:59"
    },
    "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": "YOUR-CODE1234",
    "currency": "BRL",
    "amount": 10000,
    "country": "BR",
    "buyer": {
      "name": "Buyer Name",
      "document": {
        "type": "CPF",
        "number": "34960826312"
      },
      "email": "buyer-email@wepayments.com.br"
    },
    "pix": {
      "expire_date": "2025-12-31T23:59:59"
    },
    "markup": {
      "mode": "fixed",
      "amount": 5.0
    }
  }
  ```

  ```json Boleto with Percent Markup theme={null}
  {
    "payment_method": "boleto",
    "invoice": "YOUR-INVOICE-CODE",
    "currency": "BRL",
    "amount": 50000,
    "country": "BR",
    "buyer": {
      "name": "Buyer Name",
      "email": "buyer@example.com",
      "document": {
        "type": "CPF",
        "number": "12345678901"
      },
      "address": {
        "street": "Street Name",
        "number": "123",
        "complement": "Apt 456",
        "zipcode": "12345000",
        "city": "City Name",
        "district": "District Name",
        "state_code": "SP"
      }
    },
    "originator_legal_entity": {
      "name": "Company Name",
      "document": "12345678901",
      "helpdesk": "company.com"
    },
    "boleto": {
      "expire_date": "2025-12-31"
    },
    "markup": {
      "mode": "percent",
      "amount": 2.5,
      "min_charge_value": 0.50,
      "max_charge_value": 10.00
    }
  }
  ```

  ```bash cURL - PIX with Percent Markup theme={null}
  curl -X POST "https://api.sandbox.wepayout.com.br/v2/payin/payments" \
    -H "Authorization: Bearer YOUR_TOKEN_HERE" \
    -H "Content-Type: application/json" \
    -d '{
      "payment_method": "pix",
      "invoice": "YOUR-CODE1234",
      "currency": "BRL",
      "amount": 10000,
      "country": "BR",
      "buyer": {
        "name": "Buyer Name",
        "document": {
          "type": "CPF",
          "number": "34960826312"
        },
        "email": "buyer-email@wepayments.com.br"
      },
      "pix": {
        "expire_date": "2025-12-31T23:59:59"
      },
      "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/payin/payments" \
    -H "Authorization: Bearer YOUR_TOKEN_HERE" \
    -H "Content-Type: application/json" \
    -d '{
      "payment_method": "pix",
      "invoice": "YOUR-CODE1234",
      "currency": "BRL",
      "amount": 10000,
      "country": "BR",
      "buyer": {
        "name": "Buyer Name",
        "document": {
          "type": "CPF",
          "number": "34960826312"
        },
        "email": "buyer-email@wepayments.com.br"
      },
      "pix": {
        "expire_date": "2025-12-31T23:59:59"
      },
      "markup": {
        "mode": "fixed",
        "amount": 5.0
      }
    }'
  ```

  ```bash cURL - Boleto with Percent Markup theme={null}
  curl -X POST "https://api.sandbox.wepayout.com.br/v2/payin/payments" \
    -H "Authorization: Bearer YOUR_TOKEN_HERE" \
    -H "Content-Type: application/json" \
    -d '{
      "payment_method": "boleto",
      "invoice": "YOUR-INVOICE-CODE",
      "currency": "BRL",
      "amount": 50000,
      "country": "BR",
      "buyer": {
        "name": "Buyer Name",
        "email": "buyer@example.com",
        "document": {
          "type": "CPF",
          "number": "12345678901"
        },
        "address": {
          "street": "Street Name",
          "number": "123",
          "complement": "Apt 456",
          "zipcode": "12345000",
          "city": "City Name",
          "district": "District Name",
          "state_code": "SP"
        }
      },
      "originator_legal_entity": {
        "name": "Company Name",
        "document": "12345678901",
        "helpdesk": "company.com"
      },
      "boleto": {
        "expire_date": "2025-12-31"
      },
      "markup": {
        "mode": "percent",
        "amount": 2.5,
        "min_charge_value": 0.50,
        "max_charge_value": 10.00
      }
    }'
  ```
</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 payin.
    </ResponseField>

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

<ResponseField name="hash" type="string">
  WEpayments auto generated hash, use this hash to send your user to the payment page.
</ResponseField>

<ResponseField name="payment_page" type="string">
  The WEpayments payment page is the place where you will redirect the end customer to pay the bill.
</ResponseField>

<ResponseField name="invoice" type="string">
  Your identification number.
</ResponseField>

<ResponseField name="payment_method" type="string">
  Payment method that will be used in payin.

  Values: `pix`, `boleto`
</ResponseField>

<ResponseField name="amount" type="integer">
  The payin total amount in cents.
</ResponseField>

<ResponseField name="currency" type="object">
  Currency object.

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

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

<ResponseField name="status" type="string">
  Current status of the payin.

  Example: `pending`
</ResponseField>

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

  <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 charge.
    </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 Charge with Markup theme={null}
  {
    "id": 51687,
    "merchant": {
      "id": 477,
      "name": "Merchant Name"
    },
    "hash": "abc123def456",
    "payment_page": "https://payment.wepayments.com.br/abc123def456",
    "invoice": "YOUR-CODE1234",
    "payment_method": "pix",
    "amount": 10000,
    "currency": {
      "id": 1,
      "code": "BRL"
    },
    "status": "pending",
    "markup": {
      "mode": "percent",
      "amount": 2.5,
      "min_charge_value": 0.50,
      "max_charge_value": 10.00
    }
  }
  ```

  ```json 422 Unprocessable Entity - Invalid markup.mode theme={null}
  {
    "message": "Os dados fornecidos são inválidos.",
    "errors": {
      "markup.mode": [
        "The markup.mode field is invalid"
      ]
    }
  }
  ```

  ```json 422 Unprocessable Entity - Invalid markup.amount theme={null}
  {
    "message": "Os dados fornecidos são inválidos.",
    "errors": {
      "markup.amount": [
        "The markup.amount must be at least 0.01"
      ]
    }
  }
  ```

  ```json 500 Internal Server Error theme={null}
  {
    "error": "Internal server 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 converts the markup amount to percentage: `amount * 100 = percentage%`
   * Then calculates: `transaction_amount * (amount)`
   * 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 Charge" icon="plus" href="/api-reference/cash-in/payin/create-charge">
    Complete documentation for creating payin charges
  </Card>

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