# Creating Payments

Learn how to create payment sessions and redirect customers to checkout.

# Basic Payment

Create a simple payment with amount, currency, and description:

import { HivePay } from '@hivepay/client';

const hivepay = new HivePay({ apiKey: 'sk_live_xxx' });

const payment = await hivepay.payments.create({
  amount: '10500',          // 10.500 (in satoshis/smallest unit)
  currency: 'HBD',          // 'HIVE' or 'HBD'
  description: 'Order #123' // Shown to customer
});

console.log(payment.id);          // Payment ID
console.log(payment.checkoutUrl); // Redirect URL
console.log(payment.status);      // 'pending'

curl -X POST https://hivepay.me/api/public/payments \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "10500",
    "currency": "HBD",
    "description": "Order #123"
  }'

# Amount Format

Amounts are specified as strings in the smallest unit (satoshis):

Input	Actual Amount
`"1000"`	1.000 HIVE/HBD
`"10500"`	10.500 HIVE/HBD
`"100000"`	100.000 HIVE/HBD

Both HIVE and HBD use 3 decimal precision.

# Payment Options

# Redirect URLs

Specify where to redirect customers after payment:

const payment = await hivepay.payments.create({
  amount: '10500',
  currency: 'HBD',
  description: 'Order #123',
  redirectUrl: 'https://yourstore.com/order/123/success',
  cancelUrl: 'https://yourstore.com/order/123/cancelled'
});

curl -X POST https://hivepay.me/api/public/payments \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "10500",
    "currency": "HBD",
    "description": "Order #123",
    "redirectUrl": "https://yourstore.com/order/123/success",
    "cancelUrl": "https://yourstore.com/order/123/cancelled"
  }'

# Custom Metadata

Attach custom data to a payment for your reference:

const payment = await hivepay.payments.create({
  amount: '10500',
  currency: 'HBD',
  description: 'Order #123',
  metadata: {
    orderId: '12345',
    customerId: 'cust_abc',
    items: ['item1', 'item2']
  }
});

// Metadata is returned with the payment
console.log(payment.metadata.orderId); // '12345'

# Payment Response

A successful payment creation returns:

{
  "id": "cmj7b2rg10004d2rimvum8kaz",
  "status": "pending",
  "checkoutUrl": "https://hivepay.me/checkout/cmj7b2rg10004d2rimvum8kaz",
  "amount": {
    "value": "10500",
    "formatted": "10.500 HBD",
    "currency": "HBD",
    "usdCents": 1050
  },
  "fee": "158",
  "net": "10342",
  "description": "Order #123",
  "expiresAt": "2024-01-15T11:30:00.000Z",
  "createdAt": "2024-01-15T10:30:00.000Z"
}

Field	Description
`id`	Unique payment identifier
`status`	Current payment status
`checkoutUrl`	URL to redirect customer to
`amount`	Amount details including USD equivalent
`fee`	HivePay fee (in satoshis)
`net`	Amount you receive after fees
`expiresAt`	When the payment expires

# Redirecting to Checkout

After creating a payment, redirect the customer to the checkout URL:

// Create payment on your server, then redirect
window.location.href = payment.checkoutUrl;

const handleCheckout = async () => {
  const payment = await createPayment(); // Your server call
  window.location.href = payment.checkoutUrl;
};

<button onClick={handleCheckout}>Pay with Hive</button>

<a href="{{ ERROR }}">Complete Payment</a>

# After Payment

When the payment is completed or cancelled:

Customer is redirected to your redirectUrl or cancelUrl
A webhook is sent to your configured endpoint
You can check the status using the payment ID

Best Practice

Always verify payment status via webhook or API before fulfilling orders. Don't rely solely on the redirect.

# Error Handling

import { isHivePayError } from '@hivepay/client';

try {
  const payment = await hivepay.payments.create({
    amount: '10500',
    currency: 'HBD',
    description: 'Order #123'
  });
} catch (error) {
  if (isHivePayError(error)) {
    if (error.isValidation()) {
      console.error('Invalid payment data:', error.message);
    } else if (error.isAuthError()) {
      console.error('Invalid API key');
    } else {
      console.error('Payment creation failed:', error.message);
    }
  }
}