Docs
Powered by

# Tracking Payments

Learn how to check payment status and monitor payment progress.

# Get Payment Details

Retrieve full details of a payment by ID:

const payment = await hivepay.payments.get('cmj7b2rg10004d2rimvum8kaz');

console.log(payment.status);           // 'pending', 'completed', etc.
console.log(payment.amount.formatted); // '10.500 HBD'
console.log(payment.amount.usdCents);  // USD equivalent
console.log(payment.expiresAt);        // Date object
console.log(payment.completedAt);      // Date or null
 
curl https://hivepay.me/api/public/payments/cmj7b2rg10004d2rimvum8kaz \
  -H "Authorization: Bearer sk_live_xxx"

# Check Status Only

For quick status checks, use the status endpoint:

const status = await hivepay.payments.getStatus('cmj7b2rg10004d2rimvum8kaz');

if (status === 'completed') {
  // Fulfill the order
} else if (status === 'pending') {
  // Still waiting for payment
}
 
curl https://hivepay.me/api/public/payments/cmj7b2rg10004d2rimvum8kaz/status \
  -H "Authorization: Bearer sk_live_xxx"

# Wait for Completion

Poll until a payment reaches a terminal status:

try {
  const status = await hivepay.payments.waitFor('cmj7b2rg10004d2rimvum8kaz', {
    timeout: 300000,   // 5 minutes max
    interval: 3000     // Check every 3 seconds
  });

  if (status === 'completed') {
    console.log('Payment completed!');
  } else {
    console.log('Payment ended with status:', status);
  }
} catch (error) {
  console.error('Polling timed out');
}

# Polling Options

Option Default Description
timeout 300000 Maximum wait time in milliseconds
interval 3000 Polling interval in milliseconds

# Terminal Statuses

Polling stops when payment reaches any of these statuses:

  • completed
  • failed
  • user_cancelled
  • system_cancelled

# List All Payments

Retrieve a paginated list of your payments:

// Get first page (default: 20 items)
const result = await hivepay.payments.list();

console.log(result.data);                  // Array of payments
console.log(result.pagination.page);       // Current page: 1
console.log(result.pagination.limit);      // Items per page: 20
console.log(result.pagination.total);      // Total items
console.log(result.pagination.totalPages); // Total pages

// Get specific page with custom size
const page3 = await hivepay.payments.list({
  page: 3,
  limit: 50  // Max: 100
});
 
# First page
curl "https://hivepay.me/api/public/payments" \
  -H "Authorization: Bearer sk_live_xxx"

# Page 3 with 50 items
curl "https://hivepay.me/api/public/payments?page=3&limit=50" \
  -H "Authorization: Bearer sk_live_xxx"

# Iterate All Payments

Use async iterators to process all payments without manual pagination:

// Direct iteration (default page size: 20)
for await (const payment of hivepay.payments) {
  console.log(payment.id, payment.status);
}

// With custom page size for efficiency
for await (const payment of hivepay.payments.iterate({ pageSize: 50 })) {
  await processPayment(payment);
}

// Early exit with break
for await (const payment of hivepay.payments) {
  if (payment.status === 'completed') {
    console.log('Found completed payment:', payment.id);
    break;
  }
}

# Payment Response Structure 

{
  "id": "cmj7b2rg10004d2rimvum8kaz",
  "merchantId": "cmkfgjmim00008rcxp81upef9",
  "status": "completed",
  "checkoutUrl": "https://hivepay.me/checkout/cmj7b2rg10004d2rimvum8kaz",
  "amount": {
    "value": "10500",
    "formatted": "10.500 HBD",
    "currency": "HBD",
    "usdCents": 1050
  },
  "fee": "158",
  "net": "10342",
  "description": "Order #123",
  "metadata": { "orderId": "12345" },
  "redirectUrl": "https://yourstore.com/success",
  "cancelUrl": "https://yourstore.com/cancel",
  "expiresAt": "2024-01-15T11:30:00.000Z",
  "completedAt": "2024-01-15T10:45:00.000Z",
  "createdAt": "2024-01-15T10:30:00.000Z"
}

# Best Practices

HivePay © 2026