Pocket Pay BN

An ESM Node.js client for the Pocket Pay API. The client handles the required order ID, hash, and payment creation sequence for you.

Install

npm install pocket-pay-bn

Node.js 18 or newer is required.

Create A Payment

import PocketPay from "pocket-pay-bn";

const pocketPay = new PocketPay({
  apiKey: process.env.POCKET_PAY_API_KEY,
  salt: process.env.POCKET_PAY_SALT,
  environment: "production",
});

const payment = await pocketPay.createPayment({
  // Amounts are integer cents: 500 = BND 5.00.
  items: [{ label: "Order total", amount: 500 }],
  order: {
    title: "Order #123",
    description: "Online store order",
  },
  returnUrl: "https://example.com/payment/return",
  callbackUrl: "https://example.com/payment/callback",
});

console.log(payment.paymentUrl);
// Store payment.orderId, payment.orderReference, and payment.successIndicator.

createPayment returns:

{
  orderId: 123,
  orderReference: "64757",
  paymentUrl: "https://pocket-pay.threeg.asia/...?",
  successIndicator: "7Mt2HFzywguxK0S6jDET",
  qr: "base64-encoded-qr"
}

The callback is a GET request containing successIndicator, Message, and OrderId. Make callback and return handlers idempotent so the order cannot be fulfilled twice, and compare the callback indicator with the value stored when the payment was created.

Test Environment

Pocket Pay's public sandbox credentials are used automatically in test mode:

const pocketPay = new PocketPay({ environment: "test" });

The test server is live. Creating payments makes real sandbox requests. Pocket Pay's test card is 4444 5555 6666 7777, CVV 555, expiry 01/35; use another CVV to simulate failure.

Options

Up to five line items are supported. discount and every item amount use integer cents.

const payment = await pocketPay.createPayment({
  items: [
    { label: "Products", amount: 1000 },
    { label: "Delivery", amount: 200 },
  ],
  discount: 100,
  promo: { label: "Welcome discount", code: "WELCOME" },
  order: { title: "Order #124", description: "Two products" },
  returnUrl: "https://example.com/payment/return",
  callbackUrl: "https://example.com/payment/callback",
  methods: { card: true, qr: true, biller: false },
});

Omitted payment methods default to enabled. At least one method must remain enabled.

Check Status

const payment = await pocketPay.getPaymentStatus(orderId);

if (payment.paid) {
  // payment.status is "paid"; other values are "not_paid" and "not_found".
}

Void A Payment

Pocket Pay only permits same-day voids. Provide the orderId returned by createPayment; the client checks that it is paid and resolves its order reference automatically.

const result = await pocketPay.voidPayment({
  orderId,
  adminName: "Store Admin",
  reason: "Customer requested cancellation",
});

You can instead provide orderReference or receiptReference. A receipt reference takes precedence when multiple references are supplied.

Errors

Validation errors are TypeError instances. Network and Pocket Pay API failures are PocketPayError instances with status and response properties when the gateway supplied them.

import PocketPay, { PocketPayError } from "pocket-pay-bn";

try {
  await pocketPay.getPaymentStatus(orderId);
} catch (error) {
  if (error instanceof PocketPayError) {
    console.error(error.status, error.message);
  }
}

Version 7 Migration

Version 7 replaces the old v4.js, v5.js, and v6.js entrypoints with one index.js API. Imports from versioned file paths and the old method/field names are no longer supported.

License

ISC