Node.js SDK

@bitmomo/merchant-sdk is the official server-side SDK. It works with Node.js 18 or later, in both CommonJS and ES modules, and includes TypeScript types.

npm install @bitmomo/merchant-sdk

Configure a client

import { CryptoPOS } from '@bitmomo/merchant-sdk';

const bitmomo = new CryptoPOS({
  apiKey: process.env.BITMOMO_API_KEY!,
  baseURL: 'https://api.dev.bitmomo.app',
  timeout: 10_000, // milliseconds
});

baseURL is required. It must be an https:// origin with no path, query, fragment or credentials. Plain http:// is accepted only for localhost.
The client never follows redirects, so your key is never sent to another host.

Create one client per API key, for example one for checkout and another for webhook administration.

Methods

Method	Endpoint	Scope
`createPayment(request)`	`POST /gateway/payments`	`payments:write`
`getPayment(id)`	`GET /gateway/payments/{id}`	`payments:read`
`listPayments(params?)`	`GET /gateway/payments`	`payments:read`
`getBalances()`	`GET /gateway/balances`	`payments:read`
`requestPayout(request)`	`POST /gateway/payouts`	`payouts:write`
`getWebhookConfig()`	`GET /gateway/webhooks/config`	`webhooks:read`
`updateWebhookConfig(request)`	`PUT /gateway/webhooks/config`	`webhooks:write`
`deleteWebhookConfig()`	`DELETE /gateway/webhooks/config`	`webhooks:write`
`rotateWebhookSecret()`	`POST /gateway/webhooks/config/rotate`	`webhooks:write`
`createPaymentLink(request)`	`POST /gateway/payment-links`	`payments:write`
`listPaymentLinks()`	`GET /gateway/payment-links`	`payments:read`
`getPaymentLink(id)`	`GET /gateway/payment-links/{id}`	`payments:read`
`getPaymentStatus(id)`	`GET /payments/{id}/status`	none (public)
`getRates()`	`GET /rates`	none (public)

getPaymentStatus returns only the public status string for showing to buyers. Use getPayment to verify a payment before fulfilling an order.

requestPayout requires an idempotency_key; create it with newIdempotencyKey(), save it, and reuse it on retries.

Webhook helpers

Helper	Use
`CryptoPOS.verifyWebhookEvent(rawBody, signature, options)`	Full verification: signature, freshness and signed headers. Returns `{ valid: true, envelope }` or `{ valid: false, reason }`.
`CryptoPOS.verifyWebhookSignature(rawBody, signature, secret)`	Signature check only. Prefer `verifyWebhookEvent`.
`CryptoPOS.createDeliveryDedupeCache(ttlMs?)`	In-memory duplicate filter keyed by `deliveryId` (default 24 hours). Use a database for anything that matters.

The same functions are also exported directly, for example import { verifyWebhookEvent } from '@bitmomo/merchant-sdk'. See Webhooks for the full flow.

Errors and retries

Failed calls throw an SDKError with status, code, message, request_id and retriable. The client retries reads up to 3 times on 429 and 5xx, honouring Retry-After. It never retries writes automatically; see Errors.

Money values

Amounts are decimal strings ("100.00"), both in requests and responses. Fields ending in _exact are the authoritative values. Never convert money to JavaScript numbers for comparisons.

Reference merchant

The package includes a complete integration under guides/: reference-merchant.sql and reference-merchant.cjs. See Build a merchant server.