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

## 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](https://docs.busha.io/guides/getting-started/make-first-request.md)).

> [!CAUTION]
>
> **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**.

## How to create your First Payment Request

**1. 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>
  <thead>
    <tr>
      <th>
        Parameter
      </th>

      <th>
        Data Type
      </th>

      <th>
        Required/Optional
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `quote_currency`
      </td>

      <td>string</td>
      <td>Required</td>

      <td>
        The fiat currency for the payment amount
      </td>
    </tr>

    <tr>
      <td>
        `quote_amount`
      </td>

      <td>string</td>
      <td>Required</td>

      <td>
        The fiat amount you're collecting from the customer
      </td>
    </tr>

    <tr>
      <td>
        `source_currency`
      </td>

      <td>string</td>
      <td>Required</td>

      <td>
        The cryptocurrency the customer will pay with
      </td>
    </tr>

    <tr>
      <td>
        `target_currency`
      </td>

      <td>string</td>
      <td>Required</td>
      <td>The cryptocurrency you'll receive</td>
    </tr>

    <tr>
      <td>
        `pay_in`
      </td>

      <td>object</td>
      <td>Required</td>

      <td>
        Details about how the customer will pay
      </td>
    </tr>

    <tr>
      <td>
        `additional_info`
      </td>

      <td>object</td>
      <td>Required</td>
      <td>Customer contact information</td>
    </tr>
  </tbody>
</table>

**2. 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

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

> [!TIP]
>
> Monitor the `timeline.current_step` to track payment progress using a Webhook.

## 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](https://docs.busha.io/guides/payment-requests/retrieve-payment.md)
* [How to Set Up Webhooks](https://docs.busha.io/guides/webhooks/setup.md)
* [How to Create A Quote](https://docs.busha.io/guides/quotes/create-first-quote.md)
* [Supported Currencies Reference](https://docs.busha.io/guides/reference/supported-currencies.md): See available cryptocurrency and fiat pairs
* [API Reference: Payment Request Object](https://docs.busha.io/api-reference/paymentrequests/create-a-payment-request.md): For a complete list of all parameters, sub-fields for a payment request


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.