Web SDK (TypeScript)

Prerequisites

Installation

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.terminals.list(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',
});

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

// Check if authenticated
if (client.auth.isAuthenticated()) {
  // Token is valid — proceed with API calls
}

// Force a token refresh
await client.auth.refreshToken();

// 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.