Skip to main content
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:
  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:
Important Note: Payment Requests use your Public API Key, not your Secret API Key, as they’re designed for customer-facing payment flows.

​
Step 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
ParameterData TypeRequired/OptionalDescription
quote_currencystringRequiredThe fiat currency for the payment amount
quote_amountstringRequiredThe fiat amount you’re collecting from the customer
source_currencystringRequiredThe cryptocurrency the customer will pay with
target_currencystringRequiredThe cryptocurrency you’ll receive
pay_inobjectRequiredDetails about how the customer will pay
additional_infoobjectRequiredCustomer contact information
dry_runbooleanOptional

​
Step 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 endpoint
  3. Replace YOUR_BASE_URL with your chosen environment’s URL
  4. Replace {YOUR_PUBLIC_KEY} with your actual Public API Key
$ curl -X POST "YOUR_BASE_URL/v1/payments" \
  -H "X-BU-PUBLIC-KEY: {YOUR_PUBLIC_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "additional_info": {
      "email": "john@busha.so",
      "phone_number": "+234 8123456789"
    },
    "dry_run": false,
    "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: 
{
  "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
  • dry_run: When set to true, returns calculated amounts and fees but doesn’t generate a retrievable payment request

​
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.
  • Not Found: Payment requests with dry_run set to True can not be retrieved.
  • 401 Unauthorized: Double-check that your secret API key is correct.

​
What’s Next?

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