OAuth Scopes

How It Works

1. Admin creates an OAuth app in the portal (Sidebar → OAuth Apps). Assigns a display name, an owner (merchant or branch), and one or more scopes.
2. The portal generates an appId and appSecret. The secret is shown once.
3. The integrator authenticates via the same token endpoint as terminals:

   POST /api/v1/oauth/token
   Authorization: Basic base64(appId:appSecret)

4. The returned token includes the granted scopes. Every API call checks the token's scopes — if the required scope is missing, the server returns 403 ERR_FORBIDDEN.
5. Terminal users (BRANCH, MERCHANT, ADMIN) are exempt from scope checks — they continue working exactly as before.

Available Scopes

Endpoint → Scope Mapping

Blocked for Integrators (No Scope Available)

These endpoints are gated by role (BRANCH+, ADMIN, or SYSTEM_ADMIN). No OAuth scope can grant access to them — they are permanently blocked for the INTEGRATOR role.

Integrator Quick Start

# 1. Get your appId + appSecret from the PayUs admin
#    (Admin creates it in Portal → OAuth Apps)

# 2. Authenticate
curl -X POST https://payus.co.nz/api/v1/oauth/token \
  -H "Authorization: Basic $(echo -n 'YOUR_APP_ID:YOUR_APP_SECRET' | base64)"

# Response: { "token": "...", "type": "bearer", "expiryDate": "..." }

# 3. Use the token for scoped API calls
curl -X GET "https://payus.co.nz/api/v1/pos/listTerminals?branchId=123" \
  -H "Authorization: Bearer YOUR_TOKEN"

# 4. If you call an endpoint outside your granted scopes:
# → 403 { "errorCode": "ERR_FORBIDDEN", "message": "Insufficient scope — requires payments:direct" }

Using the SDK as an Integrator

The existing SDKs (Android, Web, iOS) work unchanged for integrators. Just use your appId/appSecret instead of a terminal's clientId/clientSecret:

// Same SDK, different credentials
const client = new OneMyPosMateClient({
  baseUrl: 'https://payus.co.nz',
  system: 'pos',
});

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

// Call endpoints within your granted scopes
const terminals = await client.triggers.listSiblings(branchId);
// ✅ Works if you have terminals:read scope

await client.payments.payNow({ ... });
// ❌ 403 if you DON'T have payments:direct scope

Terminal WebSocket Connection Control

Sample Apps

Minimal single-file demos showing the full integration flow. Each covers: authenticate → list terminals → send trigger → process payment → query transactions.

Sandbox Mode

Payment Scenario Triggers (via amount)

Reference ID Prefix Overrides

For fine-grained control, prefix your referenceId to force any outcome regardless of amount. Prefixes take priority over amount-based triggers.

What still validates normally

• • OAuth scope enforcement → 403 if missing scope
• • Tenant isolation → can't access other merchants' data
• • Duplicate referenceId detection → 409
• • Amount format and range checks → 400
• • Refund cooldown (60s) and balance checks → 400
• • Rate limiting → still enforced globally

Sandbox Transaction Isolation

Sandbox transactions are tagged sandbox=true in the database. Sandbox apps only see sandbox transactions in query results, and production apps never see sandbox transactions. Reports and summaries are computed separately.

Token Lifecycle

• • Tokens expire after 7 days. The SDK auto-refreshes.
• • If the admin revokes the OAuth app, new token requests are blocked immediately. Existing tokens work until expiry (max 7 days).
• • If the admin changes scopes, the integrator must get a new token to pick up the new scopes.
• • Secret rotation: the admin can regenerate the appSecret. The old secret stops working for new token mints immediately.