Web SDK (TypeScript)

Prerequisites

Installation

// npm publication is in progress. Until @onemyposmate/sdk is live on npm,
// vendor it from source (download below, or clients/web in the repo):
//   npm install ./onemyposmate-sdk      # local path to the unpacked SDK
//
// Published coordinate (coming shortly):
//   npm install @onemyposmate/sdk

Quick Start

// 1. Create the client
const client = new OneMyPosMateClient({
  baseUrl: 'https://payus.co.nz',
  system: 'pos',
});

// 2. Authenticate with your OAuth app credentials
await client.auth.loginWithClientCredentials(
  'YOUR_APP_ID',
  'YOUR_APP_SECRET'
);

// 3. Discover terminals in your branch
const terminals = await client.triggers.listSiblings(17);

// 4. Process a payment through a terminal
const resp = await client.payments.payNow({
  grandTotal: '10.00',
  referenceId: `REF-${Date.now()}`,
  branchId: 17,
  configId: terminals[0].configId,
  channel: 'WECHAT',
});

Line items (optional)

payNow (and cloud requestTerminal) accept an optional itemised basket via lineItems. Optional and additive — omit it and nothing changes. The server reconciles it and rejects a bad basket with HTTP 400 (ERR_LINE_ITEM_MISMATCH / ERR_INVALID_LINE_ITEMS). Full field + reconciliation reference: payNow and requestTerminal.

// payNow request body — lineItems is an optional array alongside the usual fields
{
  "grandTotal": "11.00",          // decimal string; includes the tip below
  "referenceId": "ORD-42",        // the refund key — always send one
  "channel": "ALIPAY",
  "branchId": 17, "configId": 123,
  "tipAmount": "1.00",            // decimal string; declared so the basket reconciles
  "lineItems": [                  // amounts in integer cents; sum(lineTotalCents) == merchandise (1100 - 100 = 1000)
    { "name": "Flat White", "quantity": "2", "unitPriceCents": 300, "lineTotalCents": 600, "sku": "FW" },
    { "name": "Muffin",     "quantity": "1", "unitPriceCents": 400, "lineTotalCents": 400, "taxCents": 52 }
  ]
}

Per line: name (≤255), quantity (decimal string, weight-capable), unitPriceCents / lineTotalCents(integer cents), optional taxCents / sku / category; max 200 lines. Reconciliation (strict, ±1c): sum(lineTotalCents) = grandTotal − tip − fee − donation + discount. Line amounts are integer cents on every surface; the modifier amounts (tipAmountetc.) are decimal strings on this REST path and integer cents on the Intent/LAN surfaces — don't mix them. Integrating on-device via the Intent/paycore SDK instead? It ships a typed PayUsLineItem with validation — see the Intent API page.

Authentication

The SDK handles OAuth token exchange, caching, and auto-refresh. You provide your appId and appSecret — the SDK does the rest.

// Authenticate with OAuth app credentials (appId + appSecret)
// Obtain these from your PayUs admin (Portal → OAuth Apps)
const client = new OneMyPosMateClient({
  baseUrl: 'https://payus.co.nz',
  system: 'pos',
});

await client.auth.loginWithClientCredentials(
  'YOUR_APP_ID',
  'YOUR_APP_SECRET'
);

// Token is cached in TokenStore (localStorage by default)
// Every subsequent call auto-refreshes if within 60s of expiry
const token = await client.auth.currentToken();

// Single-flight Promise cache prevents concurrent refreshes
// If token is revoked, loginWithClientCredentials() must be called again

Token Lifecycle

Tokens expire after 7 days. The SDK auto-refreshes 60 seconds before expiry. If an admin revokes your OAuth app or changes your scopes, you need to re-authenticate.

// Tokens expire after 7 days — the SDK auto-refreshes
// If the admin revokes your OAuth app, new tokens are blocked
// If scopes change, get a new token to pick up new permissions

// Get the current token — currentToken() refreshes transparently when near expiry
const token = await client.auth.currentToken();

// Custom token storage (e.g. for SSR / non-browser)
const client = new OneMyPosMateClient({
  baseUrl: 'https://payus.co.nz',
  system: 'pos',
  tokenStore: new MemoryTokenStore(), // or implement TokenStore
});

Error Handling

All SDK methods throw typed exceptions with structured error codes. The SDK auto-retries on ERR_UNAUTHORIZED (once) and ERR_SYSTEM_ERROR (3x).

try {
  await client.payments.payNow(request);
} catch (e) {
  if (e instanceof OneMyPosMateError) {
    switch (e.errorCode) {
      case 'ERR_FORBIDDEN':
        // Missing OAuth scope — ask admin to grant it
        break;
      case 'ERR_GATEWAY_NOT_FOUND':
        // Terminal has no gateway configured
        break;
      case 'ERR_DUPLICATE_TRANSACTION':
        // referenceId already used — generate a unique one
        break;
      case 'ERR_REFUND_EXCEEDED':
        // Refund amount exceeds remaining balance
        break;
      case 'ERR_UNAUTHORIZED':
        // Token expired and auto-refresh failed
        // Call loginWithClientCredentials() again
        break;
      case 'ERR_RATE_LIMITED':
        // Too many requests — back off and retry
        break;
      case 'ERR_SYSTEM_ERROR':
        // Server error — SDK retries 3x automatically
        break;
    }
  }
}

Error Codes Reference

Required Scopes

Each SDK method requires a specific OAuth scope. If your app doesn't have the required scope, the server returns 403 ERR_FORBIDDEN. Ask your admin to update your app's scopes.