Create Your First Payment Request

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.

What You’ll Achieve:

Create payment requests that generate crypto payment addresses
Handle common errors when creating requests
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).

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

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

Parameter	Data Type	Required/Optional	Description
`quote_currency`	string	Required	The fiat currency for the payment amount
`quote_amount`	string	Required	The fiat amount you’re collecting from the customer
`source_currency`	string	Required	The cryptocurrency the customer will pay with
`target_currency`	string	Required	The cryptocurrency you’ll receive
`pay_in`	object	Required	Details about how the customer will pay
`additional_info`	object	Required	Customer contact information

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:

Open your terminal or command prompt
Use the POST request below to the /v1/payments/requests endpoint
Replace YOUR_BASE_URL with your chosen environment’s URL
Replace {YOUR_PUBLIC_KEY} with your actual Public API Key

    $ 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 ResponseA successful response will return a Payment Request object with a unique crypto address for the customer to pay into:

{
  "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

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
How to Set Up Webhooks
How to Create A Quote
Supported Currencies Reference: See available cryptocurrency and fiat pairs
API Reference: Payment Request Object: For a complete list of all parameters, sub-fields for a payment request

Start Here

Accept Payments (API)

Accept Payments (SDK & Widgets)

On/Off Ramp (API)

Customer Onboarding (B2B2C)

Balance & Treasury

Recipients

Token Sharing

Request ID

OAuth2

Webhooks

Reference

Prerequisites

How to create your First Payment Request

Understanding the Payment Timeline

Troubleshooting

What’s Next?

​Prerequisites

​How to create your First Payment Request

​Understanding the Payment Timeline

​Troubleshooting

​What’s Next?

Prerequisites

How to create your First Payment Request

Understanding the Payment Timeline

Troubleshooting

What’s Next?