> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Node.js SDK

> Install and configure the official UQPAY Node.js SDK to integrate payment, banking, and card issuance APIs.

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

<Card title="npm" icon="npm" href="https://www.npmjs.com/package/@uqpay/sdk">
  @uqpay/sdk
</Card>

<Info>
  The SDK requires **Node.js 20** or higher.
</Info>

## Installation

```bash theme={null}
npm install @uqpay/sdk
```

## Quick start

```ts theme={null}
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:

```ts theme={null}
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:

```ts theme={null}
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:

```ts theme={null}
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`:

```ts theme={null}
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:

```ts theme={null}
const client = new UQPayClient({
  // ...
  logLevel: 'debug',
})
```

Sensitive fields (`apiKey`, `card_number`, `cvc`, `iban`, etc.) are automatically redacted. You can add custom fields to redact:

```ts theme={null}
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:

```ts theme={null}
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:

```ts theme={null}
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)
```