Blockpay
Sign Up Free
JavaScript SDK

The @blockpay/checkout reference.

A small, sharp surface for stablecoin checkout. Six methods, one type-safe client, zero ceremony.

Install

Add the SDK to your project. It is a pure ESM package, ships with TypeScript declarations, and has zero runtime dependencies.

bashbash
npm install @blockpay/checkout

Initialize

Construct a single client and reuse it. The API key is a secret — keep it server-side.

new BlockPay(options: BlockPayOptions): BlockPay
server.ts@blockpay/checkout
import { BlockPay } from "@blockpay/checkout";
const bp = new BlockPay({
  apiKey: process.env.BLOCKPAY_API_KEY!,
  // Optional. Defaults to https://api.blockpay.dev
  baseUrl: "https://api.blockpay.dev",
});

Invoices

Invoices are the canonical record of a charge. Create one, redirect the customer to invoice.checkoutUrl, and your webhook handler fires when the on-chain transfer lands.

bp.invoices.create

bp.invoices.create(params: CreateInvoiceParams): Promise<Invoice>

Creates a fresh invoice in open state. The chain and currency lock the settlement asset; you cannot switch them after creation.

invoices.create@blockpay/checkout
const invoice = await bp.invoices.create({
  amount: "49.00",
  currency: "USDC",
  chainKey: "arc-testnet",
  merchantAddress: "0xYourSettlementWallet",
  lineItems: [{ label: "Pro Plan", amount: "49.00" }],
  // Optional. Unix seconds.
  expiresAt: Math.floor(Date.now() / 1000) + 60 * 30,
});
console.log(invoice.id);          // "inv_01HE2..."
console.log(invoice.checkoutUrl); // "/checkout/inv_01HE2..."

bp.invoices.get

bp.invoices.get(id: string): Promise<Invoice>

Fetches a single invoice by id. Returns the latest known status, including which chain transaction settled it.

invoices.get@blockpay/checkout
const invoice = await bp.invoices.get("inv_01HE2...");
if (invoice.status === "paid") {
  // fulfill the order
}

bp.invoices.list

bp.invoices.list(filter: InvoiceFilter): Promise<{ invoices: Invoice[] }>

Lists invoices, optionally filtered by merchant or status. Useful for backfilling your own database.

invoices.list@blockpay/checkout
const { invoices } = await bp.invoices.list({
  merchantId: "merchant_acme",
  status: "open",
});

Webhooks

Webhooks fire on every state change. The SDK ships a helper that verifies the signature using a constant-time comparison and gives you a typed event back.

verifyWebhook(params: VerifyWebhookParams): BlockPayEvent

Throws if the signature does not match. Always pass the raw request body — re-serialised JSON will not match the signature.

route.ts@blockpay/checkout
import { verifyWebhook } from "@blockpay/checkout/webhooks";
export async function POST(req: Request) {
  const raw = await req.text();
  const signature = req.headers.get("x-blockpay-signature") ?? "";
  const event = verifyWebhook({
    payload: raw,
    signature,
    secret: process.env.BLOCKPAY_WEBHOOK_SECRET!,
  });
  switch (event.type) {
    case "invoice.paid":
      // event.data.invoice
      break;
  }
  return new Response("ok");
}

Receipts

Every settled invoice produces a signed receipt CID. Verify it client-side to prove fulfilment without trusting the merchant or the BlockPay API.

bp.receipts.verify(params: VerifyReceiptParams): Promise<VerifiedReceipt>
receipts.verify@blockpay/checkout
// Verify a signed receipt CID produced by the BlockPay indexer.
const receipt = await bp.receipts.verify({
  cid: "0x9b1c...e3f0",
});
if (receipt.valid) {
  console.log(receipt.invoiceId, receipt.txHash, receipt.amount);
}
REST API referenceOutgoing webhooks