Integration Guide

npm install boom-pay-sdk

const BoomPay = require('boom-pay-sdk');

// Your platform instantiates one BoomPay client per merchant, using the API
// key they entered in your dashboard. Keep keys in your secrets store --
// they must never reach client-side code.
function boompayClientFor(merchant) {
  return new BoomPay({
    apiKey: merchant.boompayApiKey,
    sandbox: process.env.NODE_ENV !== 'production',
  });
}

// When a customer selects Boomcoin at your checkout, your platform creates
// an intent using that merchant's BoomPay client.
async function createBoompaySession(merchant, order) {
  const boomPay = boompayClientFor(merchant);

  const intent = await boomPay.payments.createIntent({
    amount: order.totalBmc,          // BMC amount -- convert from fiat first
    successUrl: `${PSP_BASE}/boompay/return?status=success&order=${order.id}&mid=${merchant.id}`,
    failureUrl: `${PSP_BASE}/boompay/return?status=failure&order=${order.id}&mid=${merchant.id}`,
    label: `${merchant.name} — Order ${order.reference}`,
    metadata: { orderId: order.id, merchantId: merchant.id },
  });

  // Store the intent id so your return handler can verify and re-fetch it.
  await db.setOrderMeta(order.id, 'boompay_intent_id', intent.id);

  // Redirect the customer's browser to this URL.
  return intent.link;
}

// Manual HMAC-SHA1 signature verification (equivalent to boomPay.webhooks()
// but written out explicitly for multi-merchant PSP use cases where you need
// to select the right API key before verifying).
const crypto = require('crypto');

function verifyBoompaySignature(paymentIntentId, rawSignature, apiKey) {
  const expected = crypto
    .createHmac('sha1', apiKey)
    .update(paymentIntentId)
    .digest('base64');
  // URL-decoding can turn '+' into a space; restore it before comparing.
  const received = rawSignature.replace(/ /g, '+');
  if (Buffer.byteLength(expected) !== Buffer.byteLength(received)) return false;
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(received)
  );
}

const express = require('express');
const router = express.Router();

// BoomPay redirects the customer's browser here after they pay or cancel.
// boomPay.webhooks() verifies the HMAC-SHA1 signature before your handler
// runs -- it returns 400 (missing signature), 403 (invalid), or 500 (no
// API key). If it passes, req.query.paymentIntentId is trustworthy.
//
// Note: webhooks() is Express middleware bound to a specific merchant's
// API key. Since PSPs handle multiple merchants, mount it per-request.
router.get('/boompay/return', async (req, res) => {
  const { order: orderId, mid: merchantId, status } = req.query;
  const merchant = await db.getMerchant(merchantId);
  const boomPay = boompayClientFor(merchant);

  // Run BoomPay's signature check inline since we need a per-merchant client.
  const intentId = req.query.paymentIntentId;
  const sig = (req.query['X-Boom-Signature'] || '').replace(/ /g, '+');
  const expected = require('crypto')
    .createHmac('sha1', merchant.boompayApiKey)
    .update(intentId)
    .digest('base64');

  if (!require('crypto').timingSafeEqual(Buffer.from(expected), Buffer.from(sig))) {
    return res.status(403).send('Invalid BoomPay signature');
  }

  // Re-fetch the payment to confirm state -- don't trust query params alone.
  const payment = await boomPay.payments.getPayment(intentId);
  const order = await db.getOrder(orderId);

  if (status === 'success' && payment.paidAt) {
    await db.markOrderPaid(orderId, { provider: 'boompay', reference: intentId });
    await notifyMerchant(merchant, 'PAYMENT_COMPLETE', order, payment);
    return res.redirect(merchant.successReturnUrl);
  }

  await db.markOrderFailed(orderId);
  await notifyMerchant(merchant, 'PAYMENT_FAILED', order, payment);
  res.redirect(merchant.failureReturnUrl);
});

module.exports = router;

// Example: merchant saves their BoomPay API key in your dashboard.
// Validate it by calling getDefaultWallet() -- a lightweight read that
// returns their wallet address and balance, confirming the key works.
async function validateBoompayKey(apiKey, sandbox) {
  const boomPay = new BoomPay({ apiKey, sandbox });
  try {
    await boomPay.wallets.getDefaultWallet();
    return { valid: true };
  } catch (err) {
    return { valid: false, message: err.message };
  }
}