Checkout Node SDK

@meru.app/checkout-node is the server-side SDK for Meru Checkout. Use it on your backend to create checkout sessions and reconcile their status.

This SDK holds your secret key (sk_live_…). Use it only on your backend. The browser/React side never sees it — it only receives the session id/url.

Install

npm install @meru.app/checkout-node

Requires Node 18+ (uses the global fetch). Zero dependencies.

Construct a client

import { MeruCheckout } from "@meru.app/checkout-node";

const meru = new MeruCheckout(process.env.MERU_SECRET_KEY);

apiKey falls back to process.env.MERU_SECRET_KEY, so you can also construct with no arguments. Pass an options object to override defaults:

const meru = new MeruCheckout({
  apiKey: process.env.MERU_SECRET_KEY,
  baseUrl: "https://checkout-api.meru.com", // default
  timeoutMs: 20000, // default
});

Create a session

Create the session

Call meru.checkouts.create(...). The returned session includes a url to redirect the customer to, and an id to hand to the React SDK.

const session = await meru.checkouts.create({
  amountFiat: 50,
  reference: "order_123",
  paymentMethod: "qr-bolivia",
  successUrl: "https://your-site.com/success",
  cancelUrl: "https://your-site.com/cancel",
});

// Redirect the customer to session.url, or send session.id to the React SDK.
console.log(session.id, session.url);

Expose it from your backend

A typical Express handler creates the session and returns the id/url to your frontend.

import express from "express";
import { MeruCheckout } from "@meru.app/checkout-node";

const app = express();
const meru = new MeruCheckout(process.env.MERU_SECRET_KEY);

app.post("/api/checkout", express.json(), async (req, res) => {
  const session = await meru.checkouts.create({
    amountFiat: 50,
    reference: req.body.orderId,
    paymentMethod: "qr-bolivia",
  });

  res.json({ id: session.id, url: session.url });
});

Embed the session you created here

Pass session.id to @meru.app/checkout-react to embed or redirect on the frontend.

Idempotency

Pass an idempotencyKey to make session creation safe to retry. Retrying with the same key returns the original session instead of creating a duplicate — useful when a network error leaves you unsure whether the first call succeeded.

Create with an idempotency key

const session = await meru.checkouts.create(
  { amountFiat: 50, reference: "order_123" },
  { idempotencyKey: "order_123" },
);

Retry safely

If the call fails or times out, retry with the same key. The SDK sends an Idempotency-Key header (scoped to your account), so you get the same session back rather than a second charge.

const retried = await meru.checkouts.create(
  { amountFiat: 50, reference: "order_123" },
  { idempotencyKey: "order_123" },
);

// retried.id === session.id

Use a stable, unique value per logical order (for example, your order id) as the idempotency key.

Reconcile status

Read a session with meru.checkouts.retrieve(id) and treat succeeded as paid.

const session = await meru.checkouts.retrieve("cmqx8r2f00012abcde34fghij");

if (session.status === "succeeded") {
  // Fulfill the order.
}

This server-side check is the authoritative confirmation. The React SDK’s success event is for UX only — always verify with retrieve (or your own reconciliation) before fulfilling anything of value.

Errors

Any non-2xx response throws a MeruApiError with a .status (HTTP status number) and .body (the parsed error payload).

import { MeruCheckout, MeruApiError } from "@meru.app/checkout-node";

const meru = new MeruCheckout(process.env.MERU_SECRET_KEY);

try {
  const session = await meru.checkouts.create({ amountFiat: 50 });
} catch (err) {
  if (err instanceof MeruApiError) {
    console.error("Meru API error", err.status, err.body);
  } else {
    throw err; // network/timeout or unexpected error
  }
}

Configuration

Construct the client with an options object to override defaults.

string

Your Checkout secret key (sk_live_…). Falls back to process.env.MERU_SECRET_KEY.

string

default:"https://checkout-api.meru.com"

Checkout API base URL. Override for sandbox or self-hosted environments.

number

default:"20000"

Request timeout in milliseconds.

typeof fetch

Custom fetch implementation. Defaults to the global fetch.

const meru = new MeruCheckout({
  apiKey: process.env.MERU_SECRET_KEY,
  baseUrl: "https://checkout-api.sandbox.meru.com",
});

API reference

Method	HTTP	Returns
`meru.checkouts.create(params, options?)`	`POST /v1/checkouts`	`CheckoutSession` (with `url`)
`meru.checkouts.retrieve(id)`	`GET /checkouts/:id`	`CheckoutSession`

`CreateCheckoutParams`

number

Amount in fiat. Required for crypto-exchanges; optional for qr-bolivia (the form can capture it).

string

default:"USD"

ISO currency code for amountFiat.

'crypto-exchanges' | 'qr-bolivia'

Force a payment method. Omit to let the customer choose.

'USDC' | 'USDT'

Stablecoin to receive for crypto payments.

string

Description shown on the checkout.

string

Your order id. Echoed back on the session.

string

External partner identifier.

string

URL to redirect to after a confirmed payment.

string

URL to redirect/return to on cancel.

Record<string, unknown>

Arbitrary key/value pairs, echoed back on reads.

`CheckoutSession`

string

The session identifier.

string

The hosted checkout URL. Returned by create only.

string

Your order id, echoed back.

string

The description shown on the checkout.

string | null

The fiat amount as a string, or null.

string

ISO currency code for amountFiat.

'mesh' | 'qr_bolivia' | null

The selected method, or null when the customer still has to choose.

string[]

Methods offered for this session.

string

One of created, pending, processing, succeeded, failed, expired.

string | null

On-chain transaction hash for crypto payments, or null.

object | null

QR payment details. null until a QR is generated. See the qr object.

object

Customer details captured on the checkout page (name, email, document).

string

ISO-8601 creation timestamp.

string

ISO-8601 expiration timestamp.

string | null

ISO-8601 timestamp when payment succeeded, or null.

React SDK

Embed or redirect to the session on the frontend.

Create a session (REST)

The underlying POST /v1/checkouts reference.

Payment status (REST)

The underlying GET /checkouts/{id} reference.

API Documentation

Guides

Balances

Quotes

Payouts

Payins

Checkout

Cards

Webhooks

Checkout Node SDK

Install

Construct a client

Create a session

Embed the session you created here

Idempotency

Reconcile status

Errors

Configuration

API reference

`CreateCheckoutParams`

`CheckoutSession`

React SDK

Create a session (REST)

Payment status (REST)

​Install

​Construct a client

​Create a session

Embed the session you created here

​Idempotency

​Reconcile status

​Errors

​Configuration

​API reference

​CreateCheckoutParams

​CheckoutSession

​Related

React SDK

Create a session (REST)

Payment status (REST)

Install

Construct a client

Create a session

Idempotency

Reconcile status

Errors

Configuration

API reference

`CreateCheckoutParams`

`CheckoutSession`

Related