Skip to main content
The UQPAY Node.js SDK provides typed access to the UQPAY API, including automatic authentication, pagination, retries, and webhook verification.

npm

@uqpay/sdk
The SDK requires Node.js 20 or higher.

​
Installation

npm install @uqpay/sdk

​
Quick start

import { UQPayClient } from '@uqpay/sdk'

const client = new UQPayClient({
  clientId: 'your-client-id',
  apiKey: 'your-api-key',
  environment: 'sandbox',
})

const account = await client.account.accounts.retrieve('acc-123')
console.log(account.status) // 'ACTIVE'

​
Configuration

Pass options when you create the client: 
const client = new UQPayClient({
  clientId: 'your-client-id',       // required
  apiKey: 'your-api-key',           // required
  environment: 'sandbox',           // 'sandbox' | 'production' — default: 'sandbox'
  webhookSecret: 'whsec_...',       // required for webhook verification
  timeout: 30_000,                  // request timeout in ms — default: 30000
  maxRetries: 2,                    // automatic retry count — default: 2
  logLevel: 'info',                 // 'none' | 'info' | 'debug' — default: 'none'
})

​
Authentication

The SDK handles authentication automatically. It exchanges your clientId and apiKey for a token, caches it, and refreshes it before expiry. You do not need to manage tokens manually.

​
Acting on behalf of a sub-account

To make API calls on behalf of a connected sub-account, pass the x-on-behalf-of header: 
await client.account.accounts.retrieve('acc-123', {
  headers: { 'x-on-behalf-of': 'sub-account-id' },
})

​
Idempotency

Every request includes an auto-generated UUID idempotency key. To provide your own: 
await client.account.subAccounts.create(params, {
  headers: { 'x-idempotency-key': 'your-uuid-v4' },
})

​
Pagination

All list methods return a PaginatedResponse<T> with data, total_pages, and total_items: 
const page = await client.issuing.cards.list({ page_number: 1, page_size: 50 })

console.log(page.data)        // Card[]
console.log(page.total_pages) // total number of pages
console.log(page.total_items) // total number of items
Increment page_number until it reaches total_pages to paginate through all results.

​
Logging

Enable debug logging to see all requests and responses: 
const client = new UQPayClient({
  // ...
  logLevel: 'debug',
})
Sensitive fields (apiKey, card_number, cvc, iban, etc.) are automatically redacted. You can add custom fields to redact: 
const client = new UQPayClient({
  // ...
  logLevel: 'debug',
  redactFields: ['my_secret_field'],
})

​
Escape hatch

For endpoints not yet covered by the SDK, use the generic request method: 
const result = await client.request('POST', '/v1/some/endpoint', {
  body: { key: 'value' },
})

​
Platform info

If you are building a platform on top of UQPAY, attach your app info to the User-Agent header: 
client.setAppInfo('MyPlatform', '2.0.0', 'https://myplatform.com')
// User-Agent: uqpay-node/0.2.0 node/20.0.0 MyPlatform/2.0.0 (https://myplatform.com)