Documentation Index
Fetch the complete documentation index at: https://developers-sandbox.uqpaytech.com/llms.txt
Use this file to discover all available pages before exploring further.
The UQPAY Node.js SDK provides typed access to the UQPAY API, including automatic authentication, pagination, retries, and webhook verification.
The SDK requires Node.js 20 or higher.
Installation
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' },
})
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
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',
})
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' },
})
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)
