AcountPay SDK

TypeScript SDK for AIS (bank account linking, balances when available, transactions) and optional hosted payments. Enriched account helpers are available for display and server-backed audit flows; regulatory PDF documents are not generated from this package.

Core: account information (typical app)

1. Configure the API host and your client id (from the AcountPay dashboard). You can set API_BASE_URL and ACOUNTPAY_CLIENT_ID in a .env file (see .env.example) and use Account.fromEnv() in Node, or pass new Account({ clientId, apiBaseUrl }) in the browser.
2. Consent: linkAccount with ACCOUNT_PERMISSIONS (user completes bank flow / MitID as required).
3. List accounts: getLinkedAccounts (balances are included when the bank returns them for that call).
4. Balance (when missing on list): getAccountBalance — calls Token.io’s balance endpoint with consent (same pattern as the dashboard/JWT POST /v1/ais/accounts/balance).
5. Transactions: getTransactions for a chosen accountId and date range.

import Account, { ACCOUNT_PERMISSIONS } from '@acountpay/ais-sdk';

const account = new Account({
  clientId: process.env.ACOUNTPAY_CLIENT_ID!,
  apiBaseUrl: process.env.API_BASE_URL, // optional; normalizes to include /v1
});

// or: const account = Account.fromEnv();

const link = await account.linkAccount({
  userId: 'user_…',
  permissions: [
    ACCOUNT_PERMISSIONS.READ_ACCOUNTS_DETAIL,
    ACCOUNT_PERMISSIONS.READ_BALANCES,
    ACCOUNT_PERMISSIONS.READ_TRANSACTIONS_DETAIL,
  ],
});
// Redirect to link.authorizationUrl / linkUrl when present

const { accounts } = await account.getLinkedAccounts({ userId: 'user_…' });
// If accounts[0].balance is undefined, many banks only expose balance on a dedicated call:
const bal = await account.getAccountBalance({
  userId: 'user_…',
  accountId: accounts[0].accountId,
});
const { transactions } = await account.getTransactions({
  userId: 'user_…',
  accountId: accounts[0].accountId,
  fromDate: '2025-01-01',
  toDate: '2025-01-31',
});

Who needs what

| Goal | Use these SDK methods | |------|------------------------| | Your own app (balances, tx history, account picker) | linkAccount, then getLinkedAccounts, optionally getAccountBalance, then getTransactions (and your backend or JWT APIs if you use them). | | Enriched account data for UI or backend audit | getAccountInformationForCompliance, storeAccountInformationRequest (no client-side PDF). |

Server-side security: This SDK no longer calls the compliance PDF HTTP endpoint. Your API may still expose POST /sdk/generate-compliance-pdf; restrict it to internal or trusted services so merchants cannot create sensitive documents with public credentials alone.

The npm test script (test-node.js) runs link, accounts, balance (if backend supports it), transactions. Optional verbose SDK logs:

ACOUNT_SDK_DEBUG=1 node test-node.js

SDK logging: by default the package does not emit verbose logs. Set ACOUNT_SDK_DEBUG=1 in Node or window.ACOUNT_SDK_DEBUG = true in the browser to print URLs and payloads (useful when integrating).

Installation

npm install @acountpay/ais-sdk

Local demo (browser)

After npm run build, from this directory run python3 -m http.server 8080 and open http://localhost:8080/index.html for a step-by-step Link, Accounts, Transactions UI. For optional enriched account and store-audit steps, use test.html instead.

Payments (optional)

Initialize the SDK

Same constructor as above. clientId is your SDK client id from the dashboard.

Process Payments

// Initiate a payment
await account.initiatePayment({
  amount: 100.00,
  referenceNumber: 'REF-12345'
});
// User gets redirected to Token.io payment page

API Reference

Account Class

Constructor

new Account({ clientId: string; apiBaseUrl?: string })

Account.fromEnv(overrides?) (Node)

Account.fromEnv({ clientId?: string; apiBaseUrl?: string })

Uses ACOUNTPAY_CLIENT_ID and optional API_BASE_URL from process.env unless overridden.

Methods

initiatePayment(options)

Initiates a payment and redirects user to Token.io hosted payment page.

Parameters:

• amount: number - Payment amount
• referenceNumber: string - Unique reference number

Returns: Promise<void>

linkAccount(options)

Links a customer's bank account for accessing financial data.

Parameters:

• userId: string - Customer's user ID
• permissions: string[] - Array of permission strings (ACCOUNT_PERMISSIONS)
• merchantId (optional) - Legacy; URLs use the SDK clientId from the constructor

Returns: Promise<AccountLinkingResponse>

Types

AccountLinkingResponse

interface AccountLinkingResponse {
  success: boolean;
  linkUrl?: string;
  message?: string;
}

AccountLinkingOptions

interface AccountLinkingOptions {
  merchantId: string;
  userId: string;
  permissions: string[];
  authorizationToken: string;
}

Constants

ACCOUNT_PERMISSIONS

Predefined permission constants:

• ACCOUNT_PERMISSIONS.READ_ACCOUNTS_DETAIL - "ReadAccountsDetail"
• ACCOUNT_PERMISSIONS.READ_BALANCES - "ReadBalances"
• ACCOUNT_PERMISSIONS.READ_TRANSACTIONS_DETAIL - "ReadTransactionsDetail"

Merchant onboarding helpers (no PDF in SDK)

getAccountInformationForCompliance(options)

Returns enriched account data (holder, IBAN, resolved bank name) for UI or to send to your own backend. This SDK does not download or render regulatory PDFs.

Parameters:

• merchantId: string - Your merchant ID
• userId: string - Customer's user ID
• accountId?: string - Optional specific account ID

Returns: Promise<{ success: boolean; accountInfo?: AccountInformationRequest; accounts?: AccountInformationRequest[]; message?: string }>

Example:

const result = await account.getAccountInformationForCompliance({
  merchantId: 'merchant_abc123',
  userId: 'user_2def456ghi789',
});

if (result.success && result.accountInfo) {
  console.log('Account Holder:', result.accountInfo.accountHolderName);
  console.log('Account Number:', result.accountInfo.accountNumber);
  console.log('Bank Name:', result.accountInfo.bankName);
}

storeAccountInformationRequest(accountInfo)

Stores account information request data via your configured backend endpoint.

Parameters:

• accountInfo: AccountInformationRequest - Account information to store

Returns: Promise<StoreAccountInfoResponse>

Environment Configuration

The SDK reads configuration from:

• ACOUNTPAY_CLIENT_ID: merchant SDK client id (Node: use with Account.fromEnv() or pass into new Account({ clientId })).
• API_BASE_URL: API host (optional; trailing slashes stripped, /v1 added once). Browser: set window.API_BASE_URL if not using a bundler env.
• TOKEN_ENVIRONMENT: "sandbox" or "production" where applicable.

Copy .env.example to .env for local scripts and tests.

ACOUNTPAY_CLIENT_ID=your-client-id
API_BASE_URL=https://api.acountpay.com
TOKEN_ENVIRONMENT=sandbox

Backend Integration

Your backend needs to provide these endpoints:

Payment Creation

POST {API_URL}/sdk/payment/{clientId}?amount={amount}&referenceNumber={referenceNumber}
Response: { paymentId: string }

Link Token Generation

POST {API_URL}/sdk/link-token/{clientId}?paymentId={paymentId}
Response: { tokenRequestUrl: string }

License

MIT