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.