@011bq/payments-sdk

TypeScript SDK for the Bytequests payments API. Phase 1 covers one-time payments only (create order, draft invoice, status check).

Use this from Node.js or Next.js server code (Route Handlers / Server Actions). It is not intended for browser / client components — payment create calls send a cred-id header that should stay on the server.

Install

From the monorepo (local path), or after publish:

# Local workspace (from an app in this repo)
npm install ../packages/sdk

# Or after npm publish
npm install @011bq/payments-sdk

Requires Node.js 18+ (native fetch).

Quick start

import { PaymentsClient, PaymentsApiError } from "@011bq/payments-sdk";

const client = new PaymentsClient({
  credId: process.env.PAYMENTS_CRED_ID!,  // merchant credential UUID
});
// Defaults to https://billing.011bq.app (override with `baseUrl` if needed)

const { orderID, paymentLink } = await client.payments.createOrder({
  amount: 29.99,
  currency: "USD",
  successURL: "https://app.example.com/success",
  failureURL: "https://app.example.com/cancel",
  toolName: "my-app",
  payerEmail: "[email protected]",
});

// Redirect the user to paymentLink

Client options

| Option | Required | Description | |--------|----------|-------------| | baseUrl | no | API origin without trailing slash. Defaults to PAYMENTS_API_URL (https://billing.011bq.app) | | credId | no* | Default cred-id header for create calls | | fetch | no | Custom fetch (tests / agents) |

* credId is required on createOrder / createDraftInvoice either as the client default or via per-call options.credId.

Methods (Phase 1)

payments.createOrder(body, options?)

POST /api/v1/payment/create-order

const result = await client.payments.createOrder({
  amount: 10,
  currency: "USD",
  successURL: "https://app.example.com/ok",
  failureURL: "https://app.example.com/fail",
  toolName: "checkout",
  description: "Pro plan",
  payerEmail: "[email protected]",
  payerName: "Ada",
});
// { orderID, paymentGatewayID, paymentLink }

Override credential per call:

await client.payments.createOrder(body, { credId: "other-cred-uuid" });

payments.createDraftInvoice(body, options?)

POST /api/v1/payment/create-draft-invoice

const result = await client.payments.createDraftInvoice({
  itemName: "Consulting",
  description: "April invoice",
  amount: 100,
  currency: "USD",
  payerEmail: "[email protected]",
  firstName: "Ada",
  lastName: "Lovelace",
  successURL: "https://app.example.com/ok",
  failureURL: "https://app.example.com/fail",
});

payments.check(orderId)

GET /api/v1/payment/check/:orderId

const { status, message } = await client.payments.check(orderID);
// status: unpaid | paid | failed | refunded | …

Next.js Route Handler example

// app/api/checkout/route.ts
import { NextResponse } from "next/server";
import { PaymentsClient, PaymentsApiError } from "@011bq/payments-sdk";

const client = new PaymentsClient({
  credId: process.env.PAYMENTS_CRED_ID!,
});

export async function POST(request: Request) {
  const body = await request.json();

  try {
    const { paymentLink, orderID } = await client.payments.createOrder({
      amount: body.amount,
      currency: body.currency ?? "USD",
      successURL: body.successURL,
      failureURL: body.failureURL,
      toolName: "next-storefront",
      payerEmail: body.email,
    });

    return NextResponse.json({ orderID, paymentLink });
  } catch (err) {
    if (err instanceof PaymentsApiError) {
      return NextResponse.json(
        { error: err.message, code: err.code },
        { status: err.statusCode }
      );
    }
    throw err;
  }
}

Errors

Non-2xx API responses throw PaymentsApiError:

| Property | Meaning | |----------|---------| | message | Human-readable message from the API | | statusCode | HTTP / envelope status | | code | API error code when present | | details | Raw error field or response body |

Both standard (status_code) and validation (statusCode) envelopes are mapped.

Build (contributors)

cd packages/sdk
npm install
npm run build

Roadmap

• Phase 1 (this package): create order, draft invoice, payment check
• Later: subscriptions, public orders, invoices, dashboard APIs