GuideReference

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

  1. Create a payment

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 (from the Quick Start Tutorial)

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

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

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

dry_run

boolean

Optional

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:

  1. Step 1: "Transfer Started" Payment request created, waiting for customer payment

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