Link2Pay SDK

Official TypeScript/JavaScript SDK for creating Link2Pay payment links and verifying webhook authenticity.

Quickstart | API Reference | Guides | API Design | Examples

---

Table of Contents

• Overview
• Why This Repo Is Public
• Core Features
• Architecture at a Glance
• Install
• Quick Start
• Webhook Verification
• Examples
• Project Structure
• Security Boundary
• Development
• Contributing

---

Overview

@link2pay/sdk is the public integration layer for Link2Pay.

It helps developers:

• Create and fetch payment links with typed request/response models
• Handle API errors consistently
• Verify signed webhook events safely
• Integrate quickly using runnable Next.js and Express examples

---

Why This Repo Is Public

This repository is intentionally open to support adoption and trust:

• Developers can evaluate integration quality before committing
• Teams can prototype quickly with examples and typed APIs
• Contributors can improve docs, SDK ergonomics, and developer tooling

This repository intentionally does not include private backend/indexer internals, billing logic, admin tooling, or infrastructure secrets.

---

Core Features

• Typed Link2Pay client (Link2PayClient)
• Payment links resource (create, get, list)
• Structured error classes (Link2PayApiError, Link2PayNetworkError)
• Webhook helper entrypoint (@link2pay/sdk/webhooks)
• Signature parsing + HMAC verification + constant-time comparison
• Docs for quickstart, API reference, and implementation guides

---

Architecture at a Glance

flowchart LR
  A[Merchant App] --> B["@link2pay/sdk"]
  B --> C[Link2Pay API]
  C --> D[(Stellar-backed settlement pipeline)]
  C --> E[Webhook Delivery]
  E --> F["@link2pay/sdk/webhooks"]
  F --> A

Loading

---

Install

npm install @link2pay/sdk

---

Quick Start

import { Link2PayClient } from "@link2pay/sdk";

const client = new Link2PayClient({
  apiKey: process.env.LINK2PAY_API_KEY!,
  environment: "sandbox"
});

const paymentLink = await client.paymentLinks.create({
  amount: "25.00",
  currency: "USD",
  reference: "order_1001",
  customerEmail: "buyer@example.com"
});

console.log(paymentLink.id, paymentLink.url);

For full setup, see Quickstart.

---

Webhook Verification

import { verifyWebhookSignature } from "@link2pay/sdk/webhooks";

const isValid = verifyWebhookSignature({
  payload: rawRequestBody,
  signatureHeader: req.headers["link2pay-signature"],
  secret: process.env.LINK2PAY_WEBHOOK_SECRET!
});

if (!isValid) {
  throw new Error("Invalid webhook signature");
}

See the complete Webhook Guide.

---

Examples

• Next.js payment link example
• Express webhook receiver example

---

Project Structure

src/
  client/       # SDK client entry + config
  core/         # shared HTTP + error primitives
  resources/    # API resources (payment links)
  types/        # public TypeScript interfaces
  utils/        # shared utility helpers (webhooks)
  webhooks.ts   # subpath export: @link2pay/sdk/webhooks
docs/           # quickstart, API reference, guides
examples/       # nextjs + express-webhook apps
tests/          # unit + integration scaffolding

---

Security Boundary

Public in this repo:

• SDK package code
• Public API types/interfaces
• Webhook signature verification helper
• Documentation and examples

Private in Link2Pay app/backend repos:

• API server implementation
• Watcher/indexer internals and retry strategy
• Billing and entitlement logic
• Admin operations tooling and infra secrets

---

Development

npm install
npm run lint
npm run test
npm run build

Related docs:

• Documentation Index
• API Reference
• Contributing Guide
• Security Policy

---

Contributing

PRs are welcome for SDK ergonomics, docs clarity, tests, and examples.

Please review CONTRIBUTING.md before opening a pull request.