@uniwebpay/sdk

Server-side TypeScript SDK for Uniweb payments.

Do not use this SDK in browser code, React client components, mobile clients, or any public bundle. It sends API secrets on authenticated requests.

Install

npm install @uniwebpay/sdk

Requirements:

| Runtime | Requirement | | --- | --- | | Node.js | >=18 | | Browser | Not supported |

Production defaults:

| Option | Default | | --- | --- | | baseUrl | https://apiskill.uniwebpay.com | | payUrl | https://skill.uniwebpay.com | | timeout | 30000 ms | | maxRetries | 2 |

Use a restricted sk_server_ key for deployed applications when possible. Full sk_live_ keys are accepted, but should be kept for administrative flows.

Quick Start

import Uniweb from '@uniwebpay/sdk';

const uniweb = new Uniweb(process.env.UNIWEB_SERVER_KEY!);

const product = await uniweb.products.create({
  name: 'Pro Plan',
  description: 'Monthly subscription',
});

const price = await uniweb.prices.create({
  productId: product.id,
  amount: 999,
  currency: 'SGD',
  type: 'recurring',
  interval: 'month',
});

console.log(price.paymentUrl);

Amounts are always in the currency's minor unit. For example, 100 means SGD 1.00 and 1000 means SGD 10.00.

Checkout Sessions

Create a one-time checkout session on your server and redirect the customer:

const session = await uniweb.checkout.create({
  mode: 'payment',
  lineItems: [{ priceId: price.id, quantity: 1 }],
  successUrl: 'https://example.com/success',
  cancelUrl: 'https://example.com/cancel',
  customerEmail: '[email protected]',
  paymentMethodTypes: ['card', 'paynow'],
  metadata: { orderId: 'ord_123' },
});

return Response.redirect(session.url!, 303);

Create a subscription checkout session:

const session = await uniweb.checkout.create({
  mode: 'subscription',
  lineItems: [{ priceId: price.id, quantity: 1 }],
  successUrl: 'https://example.com/billing/success',
  cancelUrl: 'https://example.com/billing/cancel',
  trialPeriodDays: 14,
  paymentMethodTypes: ['card'],
});

Subscription checkout uses card payments only.

Payment Links

const link = await uniweb.links.create({
  amount: 100,
  currency: 'SGD',
  name: 'Test order',
  description: 'SGD 1.00 payment',
  paymentMethodTypes: ['card'],
});

console.log(link.url);

Payment links are useful for fixed-amount invoices and manual collection flows.

Payments and Refunds

const payment = await uniweb.payments.get('pay_xxx');

const refreshed = await uniweb.payments.sync(payment.id);

const refund = await uniweb.refunds.create({
  paymentId: refreshed.id,
  amount: 100,
  reason: 'Customer requested refund',
});

const refundStatus = await uniweb.refunds.get(refund.id, { gateway: true });

List all succeeded payments:

for await (const payment of uniweb.payments.listAll({ status: 'succeeded' })) {
  console.log(payment.id, payment.amount, payment.currency);
}

Webhooks

Configure a webhook URL with the CLI or SDK, then verify events with the raw request body:

import { verifyWebhook } from '@uniwebpay/sdk';

const event = await verifyWebhook(
  rawBody,
  request.headers.get('uniweb-signature') ?? '',
  process.env.UNIWEB_WEBHOOK_SECRET!,
);

switch (event.type) {
  case 'payment.succeeded':
    // Mark the order as paid after checking amount, currency, and metadata.
    break;
  case 'payment.failed':
    // Keep the order unpaid or notify the customer.
    break;
}

Webhook signatures use the uniweb-signature header. Store the returned whsec_xxx secret when setting or rolling a webhook secret.

Constructor Options

const uniweb = new Uniweb(process.env.UNIWEB_SERVER_KEY!, {
  baseUrl: 'http://localhost:3000',
  payUrl: 'http://localhost:3001',
  timeout: 30000,
  maxRetries: 2,
});

The SDK rejects non-HTTPS remote API URLs to avoid leaking keys over plaintext. localhost and 127.0.0.1 are allowed for development.

Resources

| Resource | Common methods | | --- | --- | | uniweb.products | create, list, listAll, get, update, del | | uniweb.prices | create, list, listAll, get, update, activate, deactivate | | uniweb.checkout | create, list, get | | uniweb.links | create, list, listAll, get, update, deactivate | | uniweb.payments | create, list, listAll, get, listRefunds, sync, void | | uniweb.refunds | create, get | | uniweb.customers | create, list, listAll, get, update, del | | uniweb.subscriptions | create, list, listAll, get, update, cancel, resume | | uniweb.wallet | current, update | | uniweb.webhooks | set, info, remove, rollSecret |

Error Handling

import Uniweb, { UniwebError } from '@uniwebpay/sdk';

try {
  await uniweb.payments.get('pay_missing');
} catch (error) {
  if (error instanceof UniwebError) {
    console.error(error.type, error.statusCode, error.message);
  }
  throw error;
}

Local Development

From the monorepo root:

pnpm --filter @uniwebpay/sdk build
pnpm test -- packages/sdk