SDK

The SDK is the programmatic interface for creating OpenPayment links from application code. Use it when payment creation should be part of your own product logic rather than a manual or terminal-driven workflow.

What the SDK does

The public SDK exposes one main capability: create a payment definition and return the resulting shareable URL.

Like the CLI, it is currently creation-focused. It does not process settlement or fetch receipts for you.

Install

npm i openpayment

Basic usage

import { create } from "openpayment";

const result = await create({
  type: "SINGLE_USE",
  price: "49",
  payTo: "0xYourWalletAddress",
  network: "eip155:8453",
  description: "Order #2048",
});

console.log(result.paymentId);
console.log(result.url);

Input contract

type PaymentType = "SINGLE_USE" | "MULTI_USE" | "VARIABLE" | "PROXY";

type CreatePaymentInput = {
  type: PaymentType;
  price: string | number;
  payTo: string;
  network: string;
  description?: string;
  resourceUrl?: string;
};

Important notes

• resourceUrl is only valid for PROXY
• price may be passed as a string or number
• network must use the Base CAIP-2 identifier
• payTo must be an EVM address

Return value

{
  paymentId: string;
  url: string;
}

This makes the SDK easy to embed in backend services or server actions where the next step is usually to store the result and present the URL to a user or another system.

Example patterns

Create an invoice payment after order creation

const payment = await create({
  type: "SINGLE_USE",
  price: order.totalUsdc,
  payTo: merchantWallet,
  network: "eip155:8453",
  description: `Order #${order.id}`,
});

Create a reusable donation link

const payment = await create({
  type: "VARIABLE",
  price: "5",
  payTo: creatorWallet,
  network: "eip155:8453",
  description: "Support this project",
});

Create a paid protected resource

const payment = await create({
  type: "PROXY",
  price: "10",
  payTo: merchantWallet,
  network: "eip155:8453",
  description: "Premium report access",
  resourceUrl: "https://example.com/private/report",
});

Validation and error handling

The SDK validates input locally before the request is sent. This catches common issues early, such as:

• unsupported payment types
• invalid addresses
• invalid network values
• non-positive prices
• missing or invalid resourceUrl values for PROXY

If creation fails, the SDK throws an Error with a descriptive message. In practice this means you should wrap calls in try/catch and surface the error in a way that fits your application.

When the SDK is the right choice

Use the SDK when:

• you need to create links from backend code
• payment creation is triggered by application events
• you want to store paymentId and url in your own database
• your product decides the payment type dynamically

Use the CLI instead when you want a terminal-first workflow, or the Web UI when you want a visual flow.