Checkout Payments

Overview

Checkout Payments is the easiest way to start accepting cryptocurrency. With this method, BlockBee handles the entire payment interface, multi-currency selection, and real-time status updates on a secure, hosted page.

Your only responsibility is to handle the final payment notification (webhook) to confirm and process the order on your end. This makes it the perfect solution if you want a fast, secure, and simple integration without building a custom UI.

Setup

Before you can start accepting payments, you need to configure your BlockBee account and get your API credentials.

1. Create a BlockBee Account

If you haven't already, sign up for a BlockBee account to get access to the dashboard.

2. Configure Addresses

Set up the cryptocurrency addresses where you want to receive payments at Addresses.

3. Configure Payment Settings

1. Set Default Currency: Go to Payment Settings and configure your default FIAT currency (USD, EUR, GBP, etc.)
2. Customize Checkout Page: Optionally customize the appearance and branding of your checkout pages

4. Generate API Key

1. Navigate to the API Keys section in your dashboard
2. Click "Generate New API Key"
3. Copy the generated API key - you'll need this for all API requests

Step 1: Create Payment Request

First, make a request to our Checkout API. This will generate a unique payment URL for your customer.

API Endpoint

Method: GET URL: https://api.blockbee.io/checkout/request/

Code Examples

// Create a checkout payment
const createCheckoutPayment = async (orderId, amount) => {
  const params = new URLSearchParams({
    apikey: 'YOUR_API_KEY',
    redirect_url: `https://yoursite.com/success/?order_id=${orderId}`,
    value: amount.toString(),
    currency: 'usd',
    item_description: `Order #${orderId}`,
    notify_url: `https://yoursite.com/webhook/?order_id=${orderId}`,
    post: '1'
  });

  const response = await fetch(`https://api.blockbee.io/checkout/request/?${params}`);
  const result = await response.json();

  if (result.status === 'success') {
    return {
      paymentId: result.payment_id,
      paymentUrl: result.payment_url,
      successToken: result.success_token
    };
  } else {
    throw new Error('Failed to create payment: ' + result.message);
  }
};

// Using the official Node.js library
const BlockBee = require('@blockbee/api');

const params = {
  order_id: orderId,
};

const blockbeeParams = {
  currency: 'usd',
  item_description: `Order #${orderId}`,
  post: '1'
};

const payment = await BlockBee.paymentRequest(
  'https://yoursite.com/success/',
  'https://yoursite.com/webhook/',
  amount.toString(),
  params,
  blockbeeParams,
  'YOUR_API_KEY'
);
// payment.payment_url

Required Parameters

• apikey - Your BlockBee API key from the Dashboard
• redirect_url - URL where customers are redirected after payment completion.
• notify_url - Webhook URL where BlockBee sends payment notifications.
• value - Payment amount in your configured FIAT currency.

Optional Parameters

• currency - Override the default FIAT currency set in your Payment Settings (USD, EUR, GBP, etc.).
• item_description - Description that appears on the checkout page.
• expire_at - Payment expiration time (Unix timestamp, minimum 1 hour).
• post - Set to 1 to receive webhooks as POST requests.

Response

The API returns a JSON response containing the payment_url.

{
  "status": "success",
  "payment_id": "fG78jtx96ugjtu0eIbeLmFB9z0feJf9N",
  "success_token": "fG78jtx96ugjtu0eIbeLmFB9z0feJf9NfG78jtx96ugjtu0eIbeLmFB9z0feJf9N",
  "payment_url": "https://pay.blockbee.io/payment/fG78jtx96ugjtu0eIbeLmFB9z0feJf9N"
}

Step 2: Redirect Customer to Payment

After creating the payment request in Step 1, you will receive a payment_url in the API response.

Simply redirect your customer to this URL. BlockBee's hosted page takes over from here, handling everything from coin selection to payment confirmation.

// Redirect customer to payment page
window.location.href = paymentResult.paymentUrl;

Step 3: Handle the Webhook

This is the final and most important step. When a payment is made, BlockBee will send a notification (webhook) to the notify_url you provided. Your application needs to listen for this webhook to mark the order as paid.

Webhook Endpoint

Create an endpoint in your application to receive the webhook. The payload will contain all the details of the transaction.

// Express.js webhook handler
app.post('/webhook', express.json(), (req, res) => {
  // 1. Verify the webhook signature
  if (!verifyWebhookSignature(req)) {
    return res.status(401).send('Unauthorized');
  }

  // 2. Extract data from the payload
  const { is_paid, payment_id, order_id, paid_amount, paid_coin, txid, status } = req.body;
  
  // Note: order_id comes from the custom parameter you added to notify_url when creating the payment

  // Use the payment_id to prevent processing the same webhook twice
  if (isWebhookAlreadyProcessed(payment_id)) {
    return res.status(200).send('*ok*');
  }

  // Check if the payment is complete and the status is 'done'
  if (is_paid === 1 && status === 'done') {
    // 1. Find the order in your database using the order_id

    // 2. Update the order status to "paid" and store payment details
    // e.g., db.orders.update({ id: order_id }, { 
    //   status: 'paid',
    //   paid_amount: paid_amount,
    //   paid_coin: paid_coin,
    //   txid: txid
    // });

    // 3. Fulfill the order (e.g., ship product, grant access)
  }

  // Mark this webhook as processed using its unique payment_id
  markWebhookAsProcessed(payment_id);

  // Respond with *ok* to let BlockBee know you've received the webhook
  res.status(200).send('*ok*');
});

Best Practices

• Verify Signatures: Always verify the webhook signature to ensure the request is from BlockBee.
• Idempotency: Use the payment_id from the webhook payload to ensure you only process each transaction once.
• Respond Quickly: Always respond with a *ok* and a 200 status code to prevent BlockBee from resending the webhook.
• Asynchronous Processing: For long-running tasks (like calling other APIs), process them in a background job after responding to the webhook.

Alternative: Checking Logs Manually

While webhooks are recommended, you can also check the payment status by polling our Checkout Logs API endpoint. This can be useful for reconciliation or as a backup if your webhook endpoint fails. You will need the payment_id returned in Step 1.

// Using the official Node.js library
const BlockBee = require('@blockbee/api');

const logs = await BlockBee.paymentLogs(paymentId, 'YOUR_API_KEY');
// logs.notifications contains the payment history

Testing Your Integration

Test your checkout flow using real cryptocurrency with minimal cost.

1. Use Litecoin for Testing

We recommend using Litecoin (LTC) for testing because:

• Low transaction fees (typically under $0.01)
• Fast confirmation times (2.5 minutes average)
• Real blockchain testing without high costs

2. Test with a Small Amount

• Create a checkout payment for a small value (e.g., $2.00)
• Complete the payment on the hosted page using Litecoin
• This covers all fees with minimal cost (typically under $0.10)
• Allows you to test both pending and confirmed webhook states

3. Testing Checklist

• ✅ Payment creation works as expected
• ✅ Redirect to hosted checkout page is successful
• ✅ Webhooks are received for pending and confirmed states
• ✅ Order status is updated correctly in your system
• ✅ Customer is notified of successful payment

4. Local Webhook Testing

To test webhooks on your local machine, you need to expose your server to the internet. ngrok is a great tool for this.

# Use ngrok for local webhook testing
ngrok http 3000

# Your test webhook URL: https://abc12345.ngrok.io/webhook
# Use this as the notify_url when creating the payment.