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

# Create Your First Payment Request

> Generate payment requests for customers. Accept crypto payments with fixed or variable amounts.

This guide will show you how to create a Payment Request on Busha. Use this feature to easily collect payments from your customers in both crypto and fiat, simplifying your payment process.

<Tip>
  **What You'll Achieve:**

  1. Create payment requests that generate crypto payment addresses
  2. Handle common errors when creating requests
  3. Learn the different essential parameters of a payment request
</Tip>

## Prerequisites

Before you begin, ensure you have:

* A Busha Business Account and Public API Key.

* An understanding of API Environments (Sandbox vs. Production) and their base URLs (from the [Make Your First Request Guide](../getting-started/make-first-request)).

<Danger>
  **Important Note:** Payment Requests use your Public API Key, not your Secret
  API Key, as they're designed for customer-facing payment flows. Your Public
  API Key is automatically generated for your account, you do not need to create
  a new token to access it. You can find it in **Settings → Developer Tools →
  API Tokens**.
</Danger>

## How to create your First Payment Request

<Steps>
  <Step title="Understand Payment Request Parameters">
    Payment Requests are fundamentally different from Quotes because they're fiat-first: you specify the fiat amount you want to collect, and Busha calculates the equivalent crypto amount at current market rates.

    **Essential Parameters**

    <table style={{ width: "100%", borderCollapse: "collapse" }}>
      <thead>
        <tr>
          <th style={{ width: "25%", textAlign: "left", padding: "12px" }}>
            Parameter
          </th>

          <th style={{ width: "15%", textAlign: "left", padding: "12px" }}>
            Data Type
          </th>

          <th style={{ width: "20%", textAlign: "left", padding: "12px" }}>
            Required/Optional
          </th>

          <th style={{ width: "40%", textAlign: "left", padding: "12px" }}>
            Description
          </th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td style={{ padding: "12px" }}>
            <code>quote\_currency</code>
          </td>

          <td style={{ padding: "12px" }}>string</td>
          <td style={{ padding: "12px" }}>Required</td>

          <td style={{ padding: "12px" }}>
            The fiat currency for the payment amount
          </td>
        </tr>

        <tr>
          <td style={{ padding: "12px" }}>
            <code>quote\_amount</code>
          </td>

          <td style={{ padding: "12px" }}>string</td>
          <td style={{ padding: "12px" }}>Required</td>

          <td style={{ padding: "12px" }}>
            The fiat amount you're collecting from the customer
          </td>
        </tr>

        <tr>
          <td style={{ padding: "12px" }}>
            <code>source\_currency</code>
          </td>

          <td style={{ padding: "12px" }}>string</td>
          <td style={{ padding: "12px" }}>Required</td>

          <td style={{ padding: "12px" }}>
            The cryptocurrency the customer will pay with
          </td>
        </tr>

        <tr>
          <td style={{ padding: "12px" }}>
            <code>target\_currency</code>
          </td>

          <td style={{ padding: "12px" }}>string</td>
          <td style={{ padding: "12px" }}>Required</td>
          <td style={{ padding: "12px" }}>The cryptocurrency you'll receive</td>
        </tr>

        <tr>
          <td style={{ padding: "12px" }}>
            <code>pay\_in</code>
          </td>

          <td style={{ padding: "12px" }}>object</td>
          <td style={{ padding: "12px" }}>Required</td>

          <td style={{ padding: "12px" }}>
            Details about how the customer will pay
          </td>
        </tr>

        <tr>
          <td style={{ padding: "12px" }}>
            <code>additional\_info</code>
          </td>

          <td style={{ padding: "12px" }}>object</td>
          <td style={{ padding: "12px" }}>Required</td>
          <td style={{ padding: "12px" }}>Customer contact information</td>
        </tr>
      </tbody>
    </table>
  </Step>

  <Step title="Create Your First Payment Request">
    Let's create a payment request where a customer pays 50000 NGN worth of USDT.

    To create a payment request:

    1. Open your terminal or command prompt
    2. Use the `POST` request below to the `/v1/payments/requests` endpoint
    3. Replace `YOUR_BASE_URL` with your chosen environment's URL
    4. Replace `{YOUR_PUBLIC_KEY}` with your actual Public API Key

    ```shell theme={null}
        $ curl -X POST "YOUR_BASE_URL/v1/payments/requests" \
          -H "X-BU-PUBLIC-KEY: {YOUR_PUBLIC_KEY}" \
          -H "Content-Type: application/json" \
          -d '{
            "additional_info": {
              "email": "john@busha.so",
              "phone_number": "+234 8123456789"
            },
            "quote_amount": "50000",
            "quote_currency": "NGN",
            "source_currency": "USDT",
            "target_currency": "USDT",
            "pay_in": {
              "type": "address",
              "network": "TRX"
            },
            "reference": "order-2025-001"
          }'
    ```

    **Expected Response**

    A successful response will return a Payment Request object with a unique crypto address for the customer to pay into:

    ```json theme={null}
    {
      "status": "success",
      "message": "Payment request created sucessfully",
      "data": {
        "id": "PAYR_dGK3Xv7kCswk",
        "additional_info": {
          "email": "john@busha.so",
          "phone_number": "+234 8123456789"
        },
        "created_at": "2025-09-01T14:53:25.902853715Z",
        "expires_at": "2025-09-01T15:53:25.835834Z",
        "fees": [],
        "merchant_info": {
          "email": "business@example.com",
          "name": "Your Business Name"
        },
        "pay_in": {
          "address": "TTc5HBAEETmqPTarVUU3xLB3fY7b1YxNzm",
          "expires_at": "2025-09-01T15:53:25.835834Z",
          "network": "TRX",
          "type": "address"
        },
        "rate": {
          "product": "",
          "rate": "1",
          "side": "sell",
          "type": "FIXED",
          "source_currency": "USDT",
          "target_currency": "USDT"
        },
        "reference": "order-2025-001",
        "source_amount": "29.585432",
        "status": "pending",
        "target_amount": "29.585432",
        "timeline": {
          "total_steps": 2,
          "current_step": 1,
          "transfer_status": "pending",
          "events": [
            {
              "step": 1,
              "done": true,
              "status": "pending",
              "title": "Transfer Started",
              "description": "Waiting for your USDT payment",
              "timestamp": "2025-09-01T14:53:25.747904Z"
            },
            {
              "step": 2,
              "done": false,
              "status": "funds_received",
              "title": "Payment Received",
              "description": "We received your USDT Payment",
              "timestamp": "2025-09-01T14:53:25.747904Z"
            }
          ]
        },
        "updated_at": "2025-09-01T14:53:25.90285377Z",
        "source_currency": "USDT",
        "target_currency": "USDT"
      }
    }
    ```

    **Key Response Fields:**

    * **id:** The unique payment request ID
    * **pay\_in.address:** The crypto address where customers send payment
    * **source\_amount:** The calculated crypto amount customer must pay
    * **expires\_at:** When the payment request expires
  </Step>
</Steps>

## Understanding the Payment Timeline

Payment Requests include a timeline object showing the payment progress:

* **Step 1: "Transfer Started"** - Payment request created, waiting for customer payment
* **Step 2: "Payment Received"** - Customer has sent the cryptocurrency to the provided address

<Check>
  Monitor the `timeline.current_step` to track payment progress using a Webhook.
</Check>

## Troubleshooting

* **Offline Product:** "This pair is currently unavailable to trade." Try a different `source_currency` or check the Pairs API for currently available pairs.
* **`401 Unauthorized`:** Double-check that your public API key is correct.

## What's Next?

Now that you have successfully created a payment request, check out the following guides:

* [How to Retrieve Payment Requests](/guides/payment-requests/retrieve-payment)
* [How to Set Up Webhooks](/guides/webhooks/setup)
* [How to Create A Quote](/guides/quotes/create-first-quote)
* [Supported Currencies Reference](/guides/reference/supported-currencies): See available cryptocurrency and fiat pairs
* [API Reference: Payment Request Object](/api-reference/paymentrequests/create-a-payment-request): For a complete list of all parameters, sub-fields for a payment request