theypaid-sdk

theypaid-sdk

Official JavaScript / TypeScript SDK for TheyPaid — a non-custodial crypto payment gateway. Merchants create invoices; customers send crypto directly to the merchant’s wallet. No custody, no KYC, no intermediaries.

Runtime	Node.js 18+ (uses native fetch; zero runtime dependencies)
Package	theypaid-sdk on npm
API key	merchant.theypaid.io

Documentation: API reference · Changelog · Contributing & releases

---

Table of contents

• Install
• Quick start
• Module layout
• Configuration
• Invoices
• Store
• HTTP behavior
• Webhook helpers
• Errors
• TypeScript
• Examples
• Troubleshooting
• License

---

Install

npm install theypaid-sdk

yarn add theypaid-sdk
pnpm add theypaid-sdk

---

Quick start

import { TheyPaid } from 'theypaid-sdk';

const client = new TheyPaid(process.env.THEYPAID_API_KEY!);

const assets = await client.store.assets();
const invoice = await client.invoices.create({
  assetId: assets[0].assetId,
  amountInTether: 49.99,
  callbackUrl: 'https://yoursite.com/webhook/theypaid',
});

const result = await client.invoices.poll(invoice.id, {
  interval: 5000,
  onStatusChange: (status) => console.log('Status:', status),
});

console.log('Final:', result.status);

---

Module layout

Export	Role
TheyPaid	Main client — use this for all API calls
parse, isPaid, isTerminal, getPaymentUri	Webhook helpers (no network)
TheyPaidError, TheyPaidApiError, …	See Errors
Types (InvoiceDetails, CreateInvoiceParams, …)	Full list in TypeScript

REST mapping (base URL https://merchant.theypaid.io, header apiKey on every request):

SDK	HTTP
invoices.create()	POST /invoice
invoices.get(id)	GET /invoice/{id}
invoices.list()	GET /store/invoices
store.assets()	GET /store/assets

---

Configuration

new TheyPaid('your-api-key');

new TheyPaid({
  apiKey: 'your-api-key',
  baseUrl: 'https://merchant.theypaid.io', // optional override
  timeout: 10000,   // ms per request, default 10000
  retries: 3,       // max retries after first attempt, default 3
  retryDelay: 500,  // ms base delay; exponential backoff (×2 each retry)
  debug: false,     // log retry attempts to console
});

Property	Description
invoices	Invoice CRUD + polling
store	Enabled assets for checkout

---

Invoices

Method	Description
create(params)	Create invoice — see CreateInvoiceParams in docs/API.md
get(invoiceId)	Full invoice with txs, paidAmount, timestamps
list({ offset?, limit? })	Paginated invoice reports
poll(invoiceId, options?)	Poll until PAID, INSUFFICIENT, or EXPIRED

poll() — First GET runs immediately; then polls every interval ms (default 5000). Stops when status is terminal or when total timeout ms elapse (default 1 hour). Throws TheyPaidPollTimeout if the time budget is exceeded.

Invoice statuses: WAITING → awaiting payment · PAID · INSUFFICIENT (below tolerance) · EXPIRED

---

Store

Method	Description
assets()	All enabled coins / networks for the merchant (with logos and IDs for create)

---

HTTP behavior (retries & timeouts)

• Auth: apiKey: <key> on every request.
• Timeout: AbortController aborts the request after timeout ms → TheyPaidTimeoutError.
• Retries: Network failures and 429, 500, 502, 503, 504 are retried with exponential backoff (starting at retryDelay). 400, 401, 403, 404 are not retried.
• Failures: Non-success responses throw TheyPaidApiError with statusCode and parsed body.

---

Webhook helpers

TheyPaid POSTs the full invoice JSON (same shape as InvoiceDetails) to your callbackUrl when status changes. There is no HMAC or signature — always verify id (and amounts) against your database before fulfilling orders.

import { parse, isPaid, isTerminal, getPaymentUri } from 'theypaid-sdk';

const payload = parse(rawBody); // Buffer | string JSON
if (isPaid(payload)) { /* mark order paid */ }
if (isTerminal(payload)) { /* PAID | INSUFFICIENT | EXPIRED */ }
const qrUri = getPaymentUri(payload);

Function	Description
parse(body)	Parse + validate; throws TheyPaidWebhookError if invalid
isPaid(payload)	status === 'PAID'
isTerminal(payload)	PAID, INSUFFICIENT, or EXPIRED
getPaymentUri(invoice)	Payment URI for BTC, LTC, BCH, DOGE, DASH, XRP, XLM, TON; otherwise plain address

Frameworks:

• Express: examples/express-webhook.ts — use express.raw({ type: 'application/json' }).
• Next.js Pages API: examples/nextjs-webhook.ts — disable body parser; read raw Buffer.

---

Errors

Class	When
TheyPaidError	Base class
TheyPaidApiError	HTTP error — statusCode, body
TheyPaidTimeoutError	Request exceeded timeout
TheyPaidPollTimeout	poll() exceeded PollOptions.timeout
TheyPaidWebhookError	parse() validation failed

import { TheyPaidApiError } from 'theypaid-sdk';

try {
  await client.invoices.get('unknown-id');
} catch (e) {
  if (e instanceof TheyPaidApiError) {
    console.error(e.statusCode, e.body);
  }
  throw e;
}

---

TypeScript

Exported types include:

• InvoiceStatus — 'WAITING' \| 'PAID' \| 'INSUFFICIENT' \| 'EXPIRED'
• Asset, Invoice, InvoiceDetails, StoreAsset, InvoiceReport
• CreateInvoiceParams, TheyPaidConfig, PollOptions

Declaration files ship with the package (dist/index.d.ts). See docs/API.md for parameter tables.

---

Examples

From the repo root (sdk/):

THEYPAID_API_KEY=your_key npx tsx examples/create-invoice.ts
THEYPAID_API_KEY=your_key npx tsx examples/poll-invoice.ts

File	Topic
examples/create-invoice.ts	List assets, create invoice
examples/poll-invoice.ts	Poll until terminal
examples/express-webhook.ts	Express webhook
examples/nextjs-webhook.ts	Next.js API route

---

Troubleshooting

Symptom	What to check
TheyPaidTimeoutError	Network, firewall, or timeout too low for slow links
TheyPaidApiError + 401	Invalid or revoked API key
TheyPaidApiError + 404	Wrong invoiceId or resource missing
Webhook never fires	Site must be publicly reachable; local .local URLs need a tunnel (ngrok, Live Link, etc.)
TheyPaidWebhookError from parse()	Body must be valid JSON matching InvoiceDetails (TheyPaid’s webhook shape)

---

License

MIT — see LICENSE.

---

Maintainer quick reference

Update and publish a new version:

npm run lint && npm test && npm run build
# Edit CHANGELOG.md, then:
npm version patch   # or minor | major
npm publish --access public
git push --follow-tags

Full steps: CONTRIBUTING.md.