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

# Processing Markups

> Add custom markup fees to transactions and generate revenue.

This example shows you how to add custom markup fees on top of Busha's infrastructure costs.

## Use Cases

* Charging service fees on transactions
* Adding profit margins to conversions

## How Markups Work

To add your own fees, use a two-step approach:

1. **Customer Deposit**: Create a quote for the total amount (base + markup) with a `pay_in` object
2. **Actual Conversion**: After funds are received, create a second quote for only the base amount with a `pay_out` object

The difference between what the customer pays and what you spend on the conversion remains in your balance as profit.

***

## Example: Markup on USDT Purchase

A customer wants to buy USDT worth 5,000 NGN. You want to charge a 10% markup (500 NGN profit).

<Steps>
  <Step title="Create Quote for Customer Deposit">
    Charge the customer 5,500 NGN (5,000 NGN + 500 NGN markup):

    ```bash theme={null}
        curl -X POST https://api.sandbox.busha.so/v1/quotes \
          -H "Authorization: Bearer YOUR_SECRET_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{
            "source_currency": "NGN",
            "target_currency": "NGN",
            "source_amount": "5500",
            "pay_in": {
              "type": "temporary_bank_account"
            }
          }'
    ```

    **Response:**

    ```json theme={null}
    {
      "status": "success",
      "message": "Created quote successfully",
      "data": {
        "id": "QUO_depositWith5500",
        "source_currency": "NGN",
        "target_currency": "NGN",
        "source_amount": "5500",
        "target_amount": "5500",
        "pay_in": {
          "type": "temporary_bank_account"
        },
        "status": "pending"
      }
    }
    ```
  </Step>

  <Step title="Finalize Deposit Transfer">
    Generate the temporary bank account for customer deposit:

    ```bash theme={null}
        curl -X POST https://api.sandbox.busha.so/v1/transfers \
          -H "Authorization: Bearer YOUR_SECRET_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{
            "quote_id": "QUO_depositWith5500"
          }'
    ```

    **Response:**

    ```json theme={null}
    {
      "status": "success",
      "message": "Created transfer successfully",
      "data": {
        "id": "TRF_customerDeposit",
        "quote_id": "QUO_depositWith5500",
        "source_amount": "5500",
        "pay_in": {
          "recipient_details": {
            "account_name": "Payaza(Business 1 Business)",
            "account_number": "7000384620",
            "bank_name": "78 FINANCE COMPANY LIMITED"
          },
          "type": "temporary_bank_account"
        },
        "status": "pending"
      }
    }
    ```

    Customer deposits 5,500 NGN to this bank account.
  </Step>

  <Step title="Monitor Transfer Status">
    If webhooks is setup, you'll receive a notification when the deposit is complete. The customer's funds are now in your balance and ready for conversion.

    ```json theme={null}
        {
          "event": "transfer.funds_received",
          "data": {
            "transfer_id": "TRF_customerDeposit",
            "source_amount": "5500",
            "source_currency": "NGN",
            "status": "funds_received"
          }
        }
    ```

    Your balance now has 5,500 NGN.
  </Step>

  <Step title="Create Quote for Actual Conversion">
    Convert only 5,000 NGN to USDT (keeping 500 NGN as profit):

    ```bash theme={null}
        curl -X POST https://api.sandbox.busha.so/v1/quotes \
          -H "Authorization: Bearer YOUR_SECRET_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{
            "source_currency": "NGN",
            "target_currency": "USDT",
            "source_amount": "5000",
            "pay_out": {
              "type": "balance"
            }
          }'
    ```

    **Response:**

    ```json theme={null}
    {
      "status": "success",
      "message": "Created quote successfully",
      "data": {
        "id": "QUO_actualConversion",
        "source_currency": "NGN",
        "target_currency": "USDT",
        "source_amount": "5000",
        "target_amount": "3.12",
        "rate": {
          "rate": "1602.56",
          "side": "buy",
          "source_currency": "NGN",
          "target_currency": "USDT"
        },
        "pay_out": {
          "type": "balance"
        }
      }
    }
    ```
  </Step>

  <Step title="Execute Conversion Transfer">
    Finalize the conversion:

    ```bash theme={null}
        curl -X POST https://api.sandbox.busha.so/v1/transfers \
          -H "Authorization: Bearer YOUR_SECRET_TOKEN" \
          -H "Content-Type: application/json" \
          -d '{
            "quote_id": "QUO_actualConversion"
          }'
    ```

    **Result:**

    * Customer receives 3.12 USDT
    * You spent 5,000 NGN from your balance
    * 500 NGN remains in your balance as profit
  </Step>
</Steps>

***

## Example: Sell USDT for NGN with Markup

A customer wants to sell 50 USDT for NGN. You want to charge a 5% markup.

<Steps>
  <Step title="Get a Quote">
    Create a quote to see how much NGN the customer will receive:

    ```bash theme={null}
        curl -X POST https://api.sandbox.busha.so/v1/quotes \
          -H "Authorization: Bearer YOUR_SECRET_KEY" \
          -H "Content-Type: application/json" \
          -d '{
            "source_currency": "USDT",
            "target_currency": "NGN",
            "source_amount": "50"
          }'
    ```

    **Response:**

    ```json theme={null}
    {
      "status": "success",
      "message": "Created quote successfully",
      "data": {
        "id": "QUO_8xTKmNpR2vWq",
        "profile_id": "BUS_9rDAqqREdmMQcQj3zsRlL",
        "source_currency": "USDT",
        "target_currency": "NGN",
        "source_amount": "50",
        "target_amount": "74487",
        "rate": {
          "product": "USDTNGN",
          "rate": "1489.74",
          "side": "sell",
          "type": "FIXED",
          "source_currency": "USDT",
          "target_currency": "NGN"
        },
        "fees": [],
        "reference": "QUO_8xTKmNpR2vWq",
        "status": "pending",
        "expires_at": "2025-11-27T14:43:26.906019648Z",
        "created_at": "2025-11-27T14:13:26.905993939Z"
      }
    }
    ```

    **Calculate your markup:**

    * Base amount: ₦74,487
    * 5% markup: ₦3,724
    * Customer receives: ₦70,763 (₦74,487 - ₦3,724)
    * You keep: ₦3,724 as profit
  </Step>

  <Step title="Execute the Sale">
    Use the quote ID to finalize the conversion:

    ```bash theme={null}
        curl -X POST https://api.sandbox.busha.so/v1/transfers \
          -H "Authorization: Bearer YOUR_SECRET_KEY" \
          -H "Content-Type: application/json" \
          -d '{
            "quote_id": "QUO_8xTKmNpR2vWq"
          }'
    ```

    **Response:**

    ```json theme={null}
    {
      "status": "success",
      "message": "Created transfer successfully",
      "data": {
        "id": "TRF_2mKpVxNzQwYr",
        "profile_id": "BUS_9rDAqqREdmMQcQj3zsRlL",
        "quote_id": "QUO_8xTKmNpR2vWq",
        "description": "Sold USDT",
        "sub_description": "For NGN",
        "source_currency": "USDT",
        "target_currency": "NGN",
        "source_amount": "50",
        "target_amount": "74487",
        "trade": "sell",
        "rate": {
          "product": "USDTNGN",
          "rate": "1489.74",
          "side": "sell",
          "type": "FIXED"
        },
        "fees": [],
        "status": "pending",
        "created_at": "2025-11-27T14:14:06.134616492Z"
      }
    }
    ```
  </Step>

  <Step title="Apply Your Markup">
    **Your transaction breakdown:**

    * 50 USDT converted to ₦74,487 (from Busha)
    * Customer paid: ₦70,763 (after your 5% markup)
    * Your profit: ₦3,724

    You would then send ₦70,763 to the customer via bank transfer or their preferred payout method, keeping ₦3,724 as your service fee.

    ```bash theme={null}
    curl -X POST https://api.sandbox.busha.so/v1/quotes \
      -H "Authorization: Bearer YOUR_SECRET_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "source_currency": "NGN",
        "target_currency": "NGN",
        "target_amount": "70763",
        "pay_out": {
          "type": "bank_transfer",
          "recipient_id": "63837bdybd3783bd"
        }
      }'
    ```
  </Step>
</Steps>

***

## Example: Crypto Payout with Markup

A customer wants to withdraw 100 USDT to their external wallet. You want to charge a 2% markup (withdrawal fee).

<Steps>
  <Step title="Calculate Markup and Net Amount">
    **Customer request:** Withdraw 100 USDT

    **Your calculation:**

    * Gross amount: 100 USDT
    * 2% markup: 2 USDT
    * Net payout: 98 USDT (amount customer actually receives)
    * You keep: 2 USDT as profit
  </Step>

  <Step title="Create Recipient for Customer's Wallet">
    Create a crypto recipient for the customer's external wallet address:

    ```bash theme={null}
    curl -X POST https://api.sandbox.busha.so/v1/recipients \
      -H "Authorization: Bearer YOUR_SECRET_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "crypto",
        "currency": "USDT",
        "network": "TRX",
        "address": "TTc5HBAEETmqPTarVUU3xLB3fY7b1YxNzm",
        "account_name": "Customer Wallet"
      }'
    ```

    **Response:**

    ```json theme={null}
    {
      "status": "success",
      "message": "Recipient created successfully",
      "data": {
        "id": "6996cd8c772863763d64f3e3",
        "type": "crypto",
        "currency": "USDT",
        "network": "TRX",
        "address": "TTc5HBAEETmqPTarVUU3xLB3fY7b1YxNzm",
        "account_name": "Customer Wallet"
      }
    }
    ```
  </Step>

  <Step title="Create Quote for Net Payout">
    Create a quote for the net amount (98 USDT) that the customer will actually receive:

    ```bash theme={null}
    curl -X POST https://api.sandbox.busha.so/v1/quotes \
      -H "Authorization: Bearer YOUR_SECRET_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "source_currency": "USDT",
        "target_currency": "USDT",
        "source_amount": "98",
        "pay_in": {
          "type": "balance"
        },
        "pay_out": {
          "type": "address",
          "recipient_id": "6996cd8c772863763d64f3e3"
        }
      }'
    ```

    **Response:**

    ```json theme={null}
    {
      "status": "success",
      "message": "Created quote successfully",
      "data": {
        "id": "QUO_payoutNet98USDT",
        "source_currency": "USDT",
        "target_currency": "USDT",
        "source_amount": "98",
        "target_amount": "98",
        "pay_in": {
          "type": "balance"
        },
        "pay_out": {
          "type": "address",
          "recipient_id": "6996cd8c772863763d64f3e3",
          "network": "TRX"
        },
        "status": "pending"
      }
    }
    ```
  </Step>

  <Step title="Execute Payout Transfer">
    Finalize the payout:

    ```bash theme={null}
    curl -X POST https://api.sandbox.busha.so/v1/transfers \
      -H "Authorization: Bearer YOUR_SECRET_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "quote_id": "QUO_payoutNet98USDT"
      }'
    ```

    **Response:**

    ```json theme={null}
    {
      "status": "success",
      "message": "Created transfer successfully",
      "data": {
        "id": "TRF_cryptoPayout",
        "quote_id": "QUO_payoutNet98USDT",
        "source_amount": "98",
        "source_currency": "USDT",
        "target_amount": "98",
        "target_currency": "USDT",
        "pay_out": {
          "type": "address",
          "address": "TTc5HBAEETmqPTarVUU3xLB3fY7b1YxNzm",
          "network": "TRX"
        },
        "status": "pending"
      }
    }
    ```

    **Result:**

    * Customer receives: 98 USDT in their external wallet
    * You spent: 98 USDT from your balance
    * You keep: 2 USDT as profit (from the original 100 USDT customer paid you)
  </Step>

  <Step title="Monitor Payout Status">
    If webhooks are set up, you'll receive notifications as the payout progresses:

    ```json theme={null}
    {
      "event": "transfer.completed",
      "data": {
        "transfer_id": "TRF_cryptoPayout",
        "source_amount": "98",
        "source_currency": "USDT",
        "status": "completed",
        "pay_out": {
          "type": "address",
          "address": "TTc5HBAEETmqPTarVUU3xLB3fY7b1YxNzm",
          "network": "TRX"
        }
      }
    }
    ```
  </Step>
</Steps>

**Transaction Summary:**

* Customer paid you: 100 USDT
* Customer received: 98 USDT
* Your markup profit: 2 USDT
* Network fee: Covered by Busha

***

## Example: Bank Payout with Markup

A customer wants to withdraw 50,000 NGN to their bank account. You charge a 1% markup (500 NGN).

<Steps>
  <Step title="Calculate Markup">
    **Customer request:** Withdraw 50,000 NGN

    **Your calculation:**

    * Gross amount: 50,000 NGN
    * 1% markup: 500 NGN
    * Net payout: 49,500 NGN
    * You keep: 500 NGN as profit
  </Step>

  <Step title="Create Bank Recipient">
    Create a recipient for the customer's bank account:

    ```bash theme={null}
    curl -X POST https://api.sandbox.busha.so/v1/recipients \
      -H "Authorization: Bearer YOUR_SECRET_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "currency": "NGN",
        "country_code": "NG",
        "type": "ngn_bank",
        "bank_name": "GUARANTY TRUST BANK",
        "bank_code": "000013",
        "account_number": "0123456789",
        "account_name": "John Doe"
      }'
    ```

    **Response:**

    ```json theme={null}
    {
      "status": "success",
      "message": "Recipient created successfully",
      "data": {
        "id": "69980a2c70586e72bb718d1aa",
        "type": "ngn_bank",
        "currency": "NGN",
        "bank_name": "GUARANTY TRUST BANK",
        "bank_code": "000013",
        "account_number": "0123456789",
        "account_name": "John Doe"
      }
    }
    ```
  </Step>

  <Step title="Create Quote for Net Payout">
    Create a quote for 49,500 NGN (after your 1% markup):

    ```bash theme={null}
    curl -X POST https://api.sandbox.busha.so/v1/quotes \
      -H "Authorization: Bearer YOUR_SECRET_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "source_currency": "NGN",
        "target_currency": "NGN",
        "source_amount": "49500",
        "pay_in": {
          "type": "balance"
        },
        "pay_out": {
          "type": "bank_transfer",
          "recipient_id": "69980a2c70586e72bb718d1aa"
        }
      }'
    ```

    **Response:**

    ```json theme={null}
    {
      "status": "success",
      "message": "Created quote successfully",
      "data": {
        "id": "QUO_bankPayout49500",
        "source_currency": "NGN",
        "target_currency": "NGN",
        "source_amount": "49500",
        "target_amount": "49500",
        "pay_out": {
          "type": "bank_transfer",
          "recipient_id": "69980a2c70586e72bb718d1aa"
        },
        "fees": [
          {
            "name": "Transfer Fee",
            "amount": "107.50",
            "type": "FIXED",
            "currency": "NGN"
          }
        ],
        "status": "pending"
      }
    }
    ```
  </Step>

  <Step title="Execute Bank Payout">
    Finalize the bank transfer:

    ```bash theme={null}
    curl -X POST https://api.sandbox.busha.so/v1/transfers \
      -H "Authorization: Bearer YOUR_SECRET_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "quote_id": "QUO_bankPayout49500"
      }'
    ```

    **Response:**

    ```json theme={null}
    {
      "status": "success",
      "message": "Created transfer successfully",
      "data": {
        "id": "TRF_bankPayout",
        "quote_id": "QUO_bankPayout49500",
        "source_amount": "49500",
        "target_amount": "49500",
        "pay_out": {
          "type": "bank_transfer",
          "recipient_details": {
            "account_name": "John Doe",
            "account_number": "0123456789",
            "bank_name": "GUARANTY TRUST BANK"
          }
        },
        "status": "pending"
      }
    }
    ```

    **Result:**

    * Customer receives: ₦49,500 in their bank account
    * You spent: ₦49,607.50 from your balance (₦49,500 + ₦107.50 transfer fee)
    * Your markup profit: ₦500 (before transfer fee)
    * Net profit: ₦392.50 (after ₦107.50 transfer fee)
  </Step>
</Steps>

***

## Learn More

* [Customer Deposits](/examples/customer-deposits) - Accept fiat and crypto deposits
* [Sell Crypto for Fiat](/examples/crypto-to-fiat) - Sell cryptocurrency for fiat
* [Webhooks Setup](/guides/webhooks/setup) - Monitor transaction status
* [Understanding Quotes](/overview/quotes) - How quotes work