Skip to main content
After successfully creating a Payment Request, a unique id is returned in the API response. This Payment Request ID is essential for monitoring payment status and retrieving customer payment details. This guide will show you how to use this ID to retrieve the full details and current status of any existing payment request.
What You’ll Achieve:
  1. Understand why and when to retrieve payment request information
  2. Successfully make an API request to fetch a specific payment request
  3. Interpret the comprehensive Payment Request response,including payment timeline
  4. Monitor customer payment progress and status changes

​
Prerequisites

Before you begin, ensure that you have:
Note: Only payment requests created with dry_run: false can be retrieved. Dry run requests are not persisted and will return a “not_found” error.

​
Step 1: Understand the Get Payment Request API Endpoint

To retrieve payment request information, you’ll use the GET method on the /v1/payments/{id} endpoint. This endpoint allows you to query the current state and details of a specific payment request by providing its unique ID. Why Retrieve a Payment Request?
  • Monitor Payment Status: Check if the customer has completed their cryptocurrency payment
  • Get Payment Details: Retrieve the crypto address and amount for customer instructions
  • Track Payment Timeline: Monitor progress through the payment flow steps
  • Confirm Payment Completion: Verify when funds have been received

​
Step 2: Make the Request to Retrieve Payment Information

Use the GET request below, replacing the placeholders with your actual values. To retrieve payment request information:
  1. Open your terminal or command prompt
  2. Construct a GET request to the /v1/payments/{id} endpoint
  3. Replace YOUR_BASE_URL with your chosen environment’s URL (e.g., https://api.sandbox.busha.so)
  4. Replace {id} with the actual ID of the payment request you wish to retrieve (e.g., PAYR_dGK3Xv7kCswk)
  5. Replace {YOUR_PUBLIC_KEY} with your actual Public API Key
$ curl --request GET \
  --url YOUR_BASE_URL/v1/payments/{id} \
  --header 'X-BU-PUBLIC-KEY: {YOUR_PUBLIC_KEY}' \
  --header 'Content-Type: application/json'
Example: 
$ curl "https://api.sandbox.busha.so/v1/payments/PAYR_dGK3Xv7kCswk" \
  -H "X-BU-PUBLIC-KEY: pub_iSQAgqGFoVZOaVjYM1UeW" \
  -H "Content-Type: application/json"

​
Step 3: Interpret the Payment Request Response

Upon a successful request, the API will return the complete Payment Request object, including any status updates since creation. Expected Response: 
{
  "status": "success",
  "message": "Payment request retrieved successfully",
  "data": {
    "id": "PAYR_dGK3Xv7kCswk",
    "additional_info": {
      "email": "john@busha.so",
      "phone_number": "+254 701234567"
    },
    "created_at": "2025-09-01T14:53:25.902853Z",
    "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": "test-payment-real-001",
    "source_amount": "19.423511",
    "status": "pending",
    "target_amount": "19.423511",
    "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.981519Z",
    "source_currency": "USDT",
    "target_currency": "USDT"
  }
}
Key Response Fields Explained: Payment Status:
  • status: Current payment status
  • expires_at: When the payment request expires
  • updated_at: Last time the payment request was modified

​
Troubleshooting

  • Expired Quote: If expires_at is in the past it can not be used. You will need to create a new payment request.
  • Not Found: Trying to retrieve a payment request created with dry_run: true will not be able to be retrieved, set it to false and try again.
  • 401 Unauthorized: Double-check that your secret API key is correct.

​
What’s Next?

Now that you can retrieve payment request information, you can use this ID: