Checkout Deposits

Overview

Checkout Deposits allow you to create reusable deposit links where customers can make multiple payments over time. Unlike one-time payments, deposit links remain active and can receive multiple transactions from different users or the same user making recurring deposits.

This makes it perfect for:

• Account funding - Let users add funds to their account balance
• Donations - Accept multiple donations from supporters
• Recurring payments - Allow customers to make regular deposits
• Static payment links - Create permanent payment addresses for your business

Setup

Before you can start accepting deposits, 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 deposits 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 Deposit Page: Optionally customize the appearance and branding of your deposit 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 Deposit Link

First, make a request to our Deposit API. This will generate a unique deposit link that can receive multiple payments.

API Endpoint

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

Code Examples

// Create a deposit link
const createDepositLink = async (userId) => {
  const params = new URLSearchParams({
    apikey: 'YOUR_API_KEY',
    notify_url: `https://yoursite.com/webhook/?user_id=${userId}`,
    currency: 'usd',
    item_description: 'Account Deposit',
    post: '1'
  });

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

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

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

const params = {
  user_id: userId,
};

const blockbeeParams = {
  currency: 'usd',
  item_description: 'Account Deposit',
  post: '1'
};

const deposit = await BlockBee.depositRequest(
  'https://yoursite.com/webhook/',
  'YOUR_API_KEY',
  params,
  blockbeeParams
);
// deposit.payment_url and deposit.payment_id

Required Parameters

• apikey - Your BlockBee API key from the Dashboard
• notify_url - Webhook URL where BlockBee sends payment notifications for each deposit.

Optional Parameters

• currency - Override the default FIAT currency set in your Payment Settings (USD, EUR, GBP, etc.).
• item_description - Description that appears on the deposit page.
• post - Set to 1 to receive webhooks as POST requests.
• suggested_value - Suggested amount for deposits (optional, users can still send any amount).

Response

The API returns a JSON response containing the payment_url and payment_id.

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

Step 2: Share the Deposit Link

After creating the deposit link in Step 1, you will receive a payment_url in the API response.

You can share this URL with your customers in multiple ways:

• Direct link - Send the URL directly to customers
• QR code - Generate a QR code for the deposit URL
• Embed in your app - Display the deposit link in your application
• Static page - Create a permanent deposit page using this URL

// Share deposit link with customer
const shareDepositLink = (depositResult) => {
  // Option 1: Direct link
  console.log(`Share this link: ${depositResult.paymentUrl}`);
  
  // Option 2: Generate QR code (using a QR library)
  // const qrCode = generateQRCode(depositResult.paymentUrl);
  
  // Option 3: Embed in your app
  // document.getElementById('deposit-link').href = depositResult.paymentUrl;
};

Step 3: Handle the Webhooks

This is the most important step. When a deposit is made, BlockBee will send a notification (webhook) to the notify_url you provided. Your application needs to listen for these webhooks to process each deposit.

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, uuid, paid_amount, paid_coin, txid, status, user_id } = req.body;
  
  // Note: user_id comes from the custom parameter you added to notify_url when creating the deposit link

  // 3. Check for duplicates using UUID
  if (isWebhookAlreadyProcessed(uuid)) {
    return res.status(200).send('*ok*');
  }

  // 4. Check if the payment is complete and the status is 'done'
  if (is_paid === 1 && status === 'done') {
    // 5. Find the user in your database using the user_id
    console.log(`User ${user_id} has made a deposit: ${paid_amount} ${paid_coin}`);

    // 6. Update the user's account balance
    // e.g., db.users.update({ id: user_id }, { 
    //   $inc: { balance: paid_amount },
    //   $push: { transactions: { amount: paid_amount, coin: paid_coin, txid: txid } }
    // });

    // 7. Send confirmation to the user
    console.log(`Crediting ${paid_amount} ${paid_coin} to user ${user_id}...`);
  }

  // 8. Mark this webhook as processed using its unique UUID
  markWebhookAsProcessed(uuid);

  // 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 uuid 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 deposit status by polling our Deposit 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.depositLogs(paymentId, 'YOUR_API_KEY');
// logs.notifications contains the deposit history

Testing Your Integration

Test your deposit 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 deposit link
• Make a small deposit (e.g., $2.00) using Litecoin
• This covers all fees with minimal cost (typically under $0.10)
• Test multiple deposits to the same link

3. Testing Checklist

• ✅ Deposit link creation works as expected
• ✅ Webhooks are received for each deposit
• ✅ User account balance is updated correctly
• ✅ Duplicate webhooks are properly handled
• ✅ Multiple deposits to the same link work

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 deposit link.