WorldPay

Register BoomPay as an Alternative Payment Method in WorldPay's order API: your platform routes orders with type BOOMPAY through BoomPay's hosted page and handles the signed return before notifying WorldPay's settlement layer.

GatewayJSON REST APIAPM redirect

WorldPay’s order API routes payments by paymentMethod.type. Adding BOOMPAY as a recognized type in your WorldPay integration layer means any merchant you service can expose Boomcoin at checkout without any code changes on their end — your platform handles the BoomPay API call, the redirect, the signed return, and then fires WorldPay’s own merchant notification as normal.

Payment method registration

Register BoomPay as a supported APM in WorldPay’s partner programme by providing the configuration below to your WorldPay partnership contact. This establishes BOOMPAY as a valid paymentMethod.type in your WorldPay environment and associates your callback URL with it.

worldpay-registration.json

{
  "paymentMethodType": "BOOMPAY",
  "displayName": "Boomcoin (BoomPay)",
  "redirectBased": true,
  "callbackUrl": "https://your-psp.example.com/boompay/return",
  "supportsRefunds": false,
  "settlementCurrency": "BMC",
  "regions": ["GLOBAL"]
}

Flow

Order submitted

Merchant's checkout submits a WorldPay order with paymentMethod.type: BOOMPAY.

Your handler creates intent

Your APM handler calls BoomPay's createIntent() and returns a redirectURL in WorldPay's expected response shape.

Shopper redirected

WorldPay forwards the shopper to BoomPay's hosted page using the redirectURL.

Shopper pays

The customer approves payment from their Boom wallet on BoomPay's hosted page.

Signed return

BoomPay redirects to your callbackUrl with paymentIntentId and X-Boom-Signature.

Notify merchant

Your handler verifies the signature, confirms via getPayment(), and fires WorldPay's ORDER_AUTHORISED notification to the merchant.

Code

worldpay/boompay-order.js

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

// WorldPay routes an order request with paymentMethod.type === 'BOOMPAY'
// to your APM handler. Create a BoomPay intent and return the redirect URL.
async function handleBoompayOrder(worldpayOrder, merchant) {
  const boomPay = new BoomPay({
    apiKey: merchant.boompayApiKey,
    sandbox: process.env.NODE_ENV !== 'production',
  });

  const intent = await boomPay.payments.createIntent({
    amount: toBmc(worldpayOrder.orderDescription.amount, worldpayOrder.orderDescription.currencyCode),
    successUrl: `${process.env.PSP_BASE}/boompay/return?status=success&order=${worldpayOrder.orderCode}&mid=${merchant.id}`,
    failureUrl: `${process.env.PSP_BASE}/boompay/return?status=failure&order=${worldpayOrder.orderCode}&mid=${merchant.id}`,
    label: `WorldPay ${worldpayOrder.orderCode}`,
    metadata: { worldpayOrderCode: worldpayOrder.orderCode, merchantId: merchant.id },
  });

  // WorldPay APM response shape: return a redirectURL for WorldPay's
  // hosted payment pages to forward the shopper to.
  return {
    paymentStatus: 'PRE_AUTHORISED',
    redirectURL: intent.link,
    orderCode: worldpayOrder.orderCode,
  };
}

function toBmc(minorUnitAmount, currency) {
  // Convert WorldPay's minor-unit amount to a BMC value.
  // Replace with your real fiat-to-BMC rate source.
  const majorUnit = minorUnitAmount / 100;
  return majorUnit; // placeholder
}

worldpay/boompay-return.js

const crypto = require('crypto');

// BoomPay returns the shopper's browser here. After verifying BoomPay's
// signature, your platform fires WorldPay's own ORDER_AUTHORISED
// notification to the merchant, keeping your notification pipeline consistent.
async function handleBoompayReturn(req, res) {
  const { order: orderCode, mid, status } = req.query;
  const intentId = req.query.paymentIntentId;
  const signature = (req.query['X-Boom-Signature'] || '').replace(/ /g, '+');

  const merchant = await db.getMerchant(mid);
  const expected = crypto
    .createHmac('sha1', merchant.boompayApiKey)
    .update(intentId)
    .digest('base64');

  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
    return res.status(403).send('Signature verification failed');
  }

  const boomPay = new BoomPay({ apiKey: merchant.boompayApiKey, sandbox: process.env.NODE_ENV !== 'production' });
  const payment = await boomPay.payments.getPayment(intentId);

  if (status === 'success' && payment.paidAt) {
    await db.markOrderAuthorised(orderCode, { boompayIntentId: intentId });
    await worldpayNotify(merchant, 'ORDER_AUTHORISED', orderCode);
    return res.redirect(merchant.successReturnUrl);
  }

  await db.markOrderFailed(orderCode);
  await worldpayNotify(merchant, 'ORDER_FAILED', orderCode);
  res.redirect(merchant.failureReturnUrl);
}

Go-live checklist

Complete WorldPay’s APM partner registration before go-live — BOOMPAY as a payment type won’t route correctly until it’s registered in WorldPay’s environment.
Implement toBmc() with a real conversion rate — WorldPay passes amounts in minor units (e.g. pence, cents).
Confirm your worldpayNotify() call fires the right notification type for your merchant’s WorldPay integration setup.
Run one authorised and one failed payment in sandbox before enabling for live merchants.

← Previous

Adyen

PayPal / Braintree