Setup & Authentication

The SDK uses a two-level client pattern. MyPOSGateway is a singleton initialized with your integration credentials. gateway.createClient() creates per-merchant clients, each managing their own session token.

Initialize the Gateway

Create one MyPOSGateway instance at application startup — typically in a module-level singleton file. It holds the shared OAuth token used across all merchant clients.

import { MyPOSGateway, DEMO_GATEWAY_URL } from 'mypos-api-gateway'

export const gateway = new MyPOSGateway({
  gatewayUrl: DEMO_GATEWAY_URL,
  integration: {
    clientId: process.env.MYPOS_INTEGRATION_CLIENT_ID!,
    clientSecret: process.env.MYPOS_INTEGRATION_CLIENT_SECRET!,
  },
  partnerId: process.env.MYPOS_PARTNER_ID!,
  applicationId: process.env.MYPOS_APPLICATION_ID!,
})

const { MyPOSGateway, DEMO_GATEWAY_URL } = require('mypos-api-gateway')

const gateway = new MyPOSGateway({
  gatewayUrl: DEMO_GATEWAY_URL,
  integration: {
    clientId: process.env.MYPOS_INTEGRATION_CLIENT_ID,
    clientSecret: process.env.MYPOS_INTEGRATION_CLIENT_SECRET,
  },
  partnerId: process.env.MYPOS_PARTNER_ID,
  applicationId: process.env.MYPOS_APPLICATION_ID,
})

module.exports = { gateway }

For production, replace DEMO_GATEWAY_URL with PRODUCTION_GATEWAY_URL:

import { MyPOSGateway, PRODUCTION_GATEWAY_URL } from 'mypos-api-gateway'

Create Per-Merchant Clients

Call gateway.createClient() for each merchant whose data you need to access. Merchant clientId values are prefixed with cli_ and secrets with sec_.

const client = gateway.createClient({
  clientId: 'cli_merchant123',
  clientSecret: 'sec_abc456xyz789',
})

// Use client.banking, client.ecommerce, client.epos namespaces
const accounts = await client.banking.getAccounts({ page: 1, size: 20 })

const client = gateway.createClient({
  clientId: 'cli_merchant123',
  clientSecret: 'sec_abc456xyz789',
})

const accounts = await client.banking.getAccounts({ page: 1, size: 20 })

Token Lifecycle

Token type	TTL	Shared by	Auto-refresh trigger
OAuth token	1 hour	All merchant clients	60 seconds before expiry
Session token	5 minutes	Single merchant client	30 seconds before expiry

Both tokens refresh automatically. If a 401 is received mid-request, the SDK retries once with a fresh token before surfacing an error.

Error Handling

Error type	When thrown
`GatewayConfigError`	Invalid or missing gateway configuration
`GatewayAuthError`	Authentication failed (bad credentials, revoked access)

import { MyPOSGateway, GatewayConfigError, GatewayAuthError } from 'mypos-api-gateway'

try {
  const client = gateway.createClient({ clientId: 'cli_...', clientSecret: 'sec_...' })
  const result = await client.banking.getAccounts({ page: 1, size: 10 })
} catch (err) {
  if (err instanceof GatewayConfigError) {
    console.error('Configuration error:', err.message)
  } else if (err instanceof GatewayAuthError) {
    console.error('Authentication failed:', err.message)
  } else {
    throw err
  }
}

const { GatewayConfigError, GatewayAuthError } = require('mypos-api-gateway')

try {
  const result = await client.banking.getAccounts({ page: 1, size: 10 })
} catch (err) {
  if (err instanceof GatewayConfigError) {
    console.error('Configuration error:', err.message)
  } else if (err instanceof GatewayAuthError) {
    console.error('Authentication failed:', err.message)
  } else {
    throw err
  }
}

Demo Environment SSL Note

When using DEMO_GATEWAY_URL, the demo server uses a self-signed TLS certificate. Set NODE_TLS_REJECT_UNAUTHORIZED=0 in your local environment to skip certificate validation. Never use this setting in production.

# .env.local (development only — never commit to production)
NODE_TLS_REJECT_UNAUTHORIZED=0