@vantagepay/vantagepay 0.17.3 → 0.18.0

package/README.md

@@ -1,516 +1,356 @@
-# VantagePay API and Client SDK
+# VantagePay SDK for TypeScript/JavaScript
 
-The VantagePay client SDK is intended to be used by web or mobile applications to integrate into the VantagePay payments, consumer and merchant API's.
+`@vantagepay/vantagepay` is the official TypeScript/JavaScript SDK for integrating with VantagePay APIs.
 
-The library includes automatic retries for network failures and automatic token refresh on expiry. You can optionally subscribe to events published by the library to react appropriately from the client as well.
+It provides:
+
+- typed API modules backed by VantagePay model types
+- automatic HTTP retries for transient failures
+- automatic token refresh using `refreshToken`
+- real-time payment status updates via SignalR
+- event publishing for session and payment lifecycle signals
+
+This package is client-focused. Administrative API-key capabilities are available in the .NET SDK ([VantagePay.SDK](https://www.nuget.org/packages/VantagePay.SDK)) and are not part of this package.
 
 ---
-# Installation
 
-Install the latest package into your project from NPM.
+## Table of Contents
+
+- [Installation](#installation)
+- [Client Types](#client-types)
+- [Basic Usage](#basic-usage)
+- [Configuration and Construction](#configuration-and-construction)
+- [Authentication and Tokens](#authentication-and-tokens)
+- [Error Handling](#error-handling)
+- [Public API Surface](#public-api-surface)
+- [Payments and Signals](#payments-and-signals)
+- [Server-side Admin Usage](#server-side-admin-usage)
+- [Additional Modules](#additional-modules)
 
-```ps
-npm install @vantagepay/vantagepay --save
-```
 ---
-# Basic Usage
-The library can be imported just like any other NPM package.
-```js
-import { VantagePay, ApiTokens, ApiError } from '@vantagepay/vantagepay'
-```
-Once imported you can create an instance with options specific to your environment.
-```js
-const VantagePayClient = new VantagePay({ baseUrl: 'https://sandbox-api.vantagepay.dev/' })
-```
-When you are done using the client or when the application exits, you can close the client to flush logs, unsubscribe to events and cancel active web requests.
-```js
-await VantagePayClient.close()
+
+## Installation
+
+```sh
+npm install @vantagepay/vantagepay
 ```
 
-The following options are available when creating an instance.
-```js
-{
-  // The partner URL you are integrating with, this will point to the local development server by default.
-  baseUrl: 'https://sandbox-api.vantagepay.dev/',
+---
 
-  // Optional extra headers (string key/value pairs) that you may want to send to the server with each call.
-  headers: {
-    'X-EXAMPLE-HEADER': 'Test'
-  },
+## Client Types
 
-  // Optional language if you need to have response messages translated.
-  language: 'en',
+This package exposes one top-level client:
 
-  // The number of automatic retries required for network failures, the default is 3.
-  retries: 3,
+- `VantagePay` for client-facing integrations (web/mobile/POS-style app integrations).
 
-  // For additional request/response and signal logging which can be useful when debugging.
-  consoleLogging: false,
+Important:
 
-  // The batch size limit when logs should immediately be sent to the server, the default is 100, use 0 to disable.
-  logBatchSize: 100,
+- there is no `VantagePayAdminClient` in TypeScript.
+- for server-side admin API-key workflows, use the [.NET SDK](https://www.nuget.org/packages/VantagePay.SDK).
 
-  // The interval in milliseconds to send any queued logs the server, the default is 60000, use 0 to disable.
-  logBatchInterval: 60000,
-}
-```
+---
 
-To flush any logs to the server you can call the `log.flush()` method manually or `close()` on the client instance when closing your application.
-```js
-// Do this when the application close to push final logs to the server.
-VantagePayClient.log.flush()
+## Basic Usage
 
-// You can also just close the client when you are done using it.
-await VantagePayClient.close()
-```
+```ts
+import { VantagePay } from '@vantagepay/vantagepay'
 
-The instance will contain all the methods available for making API calls. All methods return a [`Promise`](https://javascript.info/async) so you can either use modern async/await syntax or promise-based chaining. The rest of the examples that follow use the async/await syntax.
+const client = new VantagePay({
+  baseUrl: 'https://sandbox-api.vantagepay.dev/',
+})
 
-## Error Handling
-The API will respond with typical REST HTTP error status codes (4xx and 5xx) for errors that will trigger an exception. You can use the following generic error handling code for the typical exceptions that you may experience.
+await client.auth.login('233548306110', 'Password123!')
 
-```js
-try {
-  // ... Call a method on the client library.
-} catch (error) {
-  // First check if it's an API error.
-  if (error instanceof ApiError) {
-    // You can always display the `message` property to handle things generically.
-    console.error('\n%s\n', error.message)
-
-    // Or you can decide to handle things in a custom way depending on the status code.
-    if (error.statusCode === 400 || error.statusCode === 422) {  // 400/422 - Validation Errors
-      if (Array.isArray(error.result)) {
-        // Multiple errors.
-        error.result.forEach(validationError => console.error(validationError))
-      }
-      else {
-        // Single error message.
-        console.error(error.message || error.result)
-      }
-    }
-    else if (error.statusCode === 401 || error.statusCode === 403) {  // 401/403 - Auth Errors
-      // Login calls will contain extra information on failure (401).
-      // No access will not have any specific details on why (403).
-    }
-    else if (error.statusCode === 429) {  // 429 - Too Many Requests
-      // Contains the limit.
-      console.error(error.message)
-      // This will also contain a standard 'Retry-After' header if you need to know how long to wait.
-    }
-    else if (error.statusCode === 500) {  // 500 - Server Error
-      // General error message.
-      console.error(error.message)
-    }
-    else {
-      console.error('Unknown status code from VantagePay client library: ' + error.statusCode)
-      throw error
-    }
-  } else {
-    // Not a client library error...
-    throw error
-  }
-}
+const currencies = await client.lookups.getCurrencies()
+const summary = await client.reports.getTransactionSummary('GHS')
+
+await client.close()
 ```
 
 ---
-# Authentication
 
-## Login
-Use credentials to login and retrieve access and refresh tokens.
-```js
-try {
- 
-  const testLogin = await VantagePayClient.auth.login('test', 'test@#$123abCD')
+## Configuration and Construction
 
-  // Store tokens in secure storage if you want to use biometrics etc.
-  my_secure_storage.set('accessToken', testLogin.accessToken)
-  my_secure_storage.set('refreshToken', testLogin.refreshToken)
+Available `VantagePay` constructor options:
 
-  // An alternative is to just use the static ApiTokens object where the tokens are stored after a login/refresh.
-  my_secure_storage.set('accessToken', ApiTokens.accessToken)
-  my_secure_storage.set('refreshToken', ApiTokens.refreshToken)
+```ts
+import { VantagePay } from '@vantagepay/vantagepay'
 
-} catch (error) {
-    if (error.statusCode === 401) {
-    // Authentication error
-    // {
-    //   invalidUsernameOrPassword: true,
-    //   mustChangePassword: false,
-    //   mustValidatePhoneNumber: false,
-    //   mustValidateEmailAddress: false,
-    //   registrationRequired: false,
-    //   lockedOut: false
-    // }
-
-    const authError = error.result
-
-    if (authError.mustChangePassword) {
-      console.log('Navigate to a change password page, the token is internally set to allow calls to auth.changePassword()')
-
-      // A successful change will automatically log you in.
-      await VantagePayClient.auth.changePassword('NewComplexP@55word!')
-    }
+const client = new VantagePay({
+  baseUrl: 'https://sandbox-api.vantagepay.dev/',
+  headers: { 'X-EXAMPLE-HEADER': 'Test' },
+  language: 'en',
+  retries: 3,
+  consoleLogging: false,
+  logBatchSize: 100,
+  logBatchInterval: 60000,
+})
+```
 
-    if (authError.mustValidatePhoneNumber || authError.mustValidateEmailAddress) {
-      console.log('Navigate to the OTP page password page, the token is internally set to allow calls to auth.resendOtp() and auth.validateOtp()')
+Notes:
 
-      // A successful OTP verification will automatically log you in.
-      await VantagePayClient.auth.validateOtp('1234')
-    }
+- `baseUrl` defaults to `http://localhost:5000`.
+- `close()` flushes logs, stops payment status checks, unsubscribes events, and aborts in-flight requests.
 
-    if (authError.deactivated) {
-      console.log('User account has been deactivated')
-    }
+---
 
-    if (authError.lockedOut) {
-      console.log('User is currently locked out')
-    }
+## Authentication and Tokens
 
-    if (authError.invalidUsernameOrPassword) {
-      console.log('User credentials supplied are invalid')
-    }
-  }
+### Login and token storage
 
-  if (error.statusCode === 429) {
-    // Rate limited
-    // Maximum number of requests exceeded. The maximum number of requests allowed is 3 per 30s. Please try again in 13 second(s).
-    console.log(error.message)
-  }
-}
+```ts
+import { ApiTokens } from '@vantagepay/vantagepay'
+
+const tokenResponse = await client.auth.login('233548306110', 'Password123!')
+
+console.log(tokenResponse.accessToken)
+console.log(ApiTokens.accessToken)
+console.log(ApiTokens.refreshToken)
 ```
 
-## Using Existing Tokens
-Tokens are kept in memory for the lifetime of the client instance and are used automatically to make authenticated calls and refresh when necessary.
-To avoid having to login each time your application starts, you can store access and refresh tokens (securely using biometrics for example) and re-use them when starting the application to "auto-login". You simply assign any tokens you have to the static instance of `ApiTokens`.
+### Restore existing tokens
+
+```ts
+import { ApiTokens } from '@vantagepay/vantagepay'
 
-```js
-ApiTokens.accessToken = my_secure_storage.get('accessToken') || null
-ApiTokens.refreshToken = my_secure_storage.get('refreshToken') || null
+ApiTokens.accessToken = secureStore.get('accessToken') || null
+ApiTokens.refreshToken = secureStore.get('refreshToken') || null
 ```
 
-It is usually not necessary to set the `accessToken`, if there is no access token then an automatic refresh will be triggered to retrieve one.
-You can also use this to clear out tokens manually which is also used internally when `logout` is called.
+### Session helpers
 
-## Logout
-Logout of the system which revokes the refresh token as well. Use this when you need to forcibly log a user out due to multiple device unlock failures for example.
-```js
-await VantagePayClient.auth.logout()
+```ts
+const isLoggedIn = client.auth.isLoggedIn()
+await client.auth.refresh()
+await client.auth.logout()
 ```
 
-## Refresh
-This is used internally to automatically refresh if the access token is no longer valid. If you need to refresh manually for any reason to start a new access session then you can call this as well to avoid expiry. This will use the current refresh token that has been set (`ApiKeys.refreshToken`).
-```js
-await VantagePayClient.auth.refresh()
+### Token claim helpers
+
+```ts
+client.auth.getCurrentUserReference()
+client.auth.getCurrentConsumerReference()
+client.auth.getCurrentMerchantReference()
+client.auth.getCurrentBusinessReference()
+client.auth.getCurrentTerminalReference()
+client.auth.getCurrentUserName()
+client.auth.getMobileNumber()
+client.auth.getEmailAddress()
+client.auth.getRedirectAction()
 ```
 
 ---
-# Lookups
-There are a number of lookup values that can be retrieved from the server. This is preferred over static client data because it allows for dynamic configuration and disabling of things from the server without redeploying the client.
 
-## Currencies
-Get a list of configured currencies for the partner. The `isAvailable` flag can be used to disable items from selection, the text will also indicate if it is currently available. Other properties can be useful for displaying currency values.
-```js
-var currencies = await VantagePayClient.lookups.getCurrencies()
-```
+## Error Handling
 
-Example Output
-```js
-[
-  {
-    isAvailable: true,
-    currency: 'GHS',
-    currencyName: 'Ghana Cedi',
-    currencyCode: 'GHS',
-    symbol: '¢',
-    numericIsoCode: 936
-  },
-  {
-    isAvailable: true,
-    currency: 'NGN',
-    currencyName: 'Nigeria Naira',
-    currencyCode: 'NGN',
-    symbol: '₦',
-    numericIsoCode: 566
-  },
-  {
-    isAvailable: true,
-    currency: 'ZAR',
-    currencyName: 'South Africa Rand',
-    currencyCode: 'ZAR',
-    symbol: 'R',
-    numericIsoCode: 710
-  }
-]
-```
+All API methods throw `ApiError` for HTTP/API failures.
 
-## Countries
-Get a list of configured countries for the partner. The `isAvailable` flag can be used to disable items from selection, the text will also indicate if it is currently available. Other values are useful for adding drop-downs to mobile numbers for example.
-```js
-var countries = await VantagePayClient.lookups.getCountries()
-```
+```ts
+import { ApiError } from '@vantagepay/vantagepay'
 
-Example Output
-```js
-[
-  {
-    isAvailable: true,
-    country: 'GHA',
-    countryName: 'Ghana',
-    longIsoCode: 'GHA',
-    shortIsoCode: 'GH',
-    numericIsoCode: 288,
-    diallingCode: '233'
-  },
-  {
-    isAvailable: true,
-    country: 'NGA',
-    countryName: 'Nigeria',
-    longIsoCode: 'NGA',
-    shortIsoCode: 'NG',
-    numericIsoCode: 566,
-    diallingCode: '234'
-  },
-  {
-    isAvailable: false,
-    country: 'ZAF',
-    countryName: 'South Africa (Currently Unavailable)',
-    longIsoCode: 'ZAF',
-    shortIsoCode: 'ZA',
-    numericIsoCode: 710,
-    diallingCode: '27'
-  }
-]
-```
+try {
+  await client.auth.login('user', 'wrong-password')
+} catch (error) {
+  if (error instanceof ApiError) {
+    console.error(error.statusCode)
+    console.error(error.message)
+    console.error(error.result)
 
-## Languages
-Get a list of configured languages for the partner. The `isAvailable` flag can be used to disable items from selection, the text will also indicate if it is currently available. This can be useful for apps that are translated to change the language header.
-```js
-var languages = await VantagePayClient.lookups.getLanguages()
-```
+    if (error.statusCode === 401 && error.result?.mustChangePassword) {
+      await client.auth.changePassword('OldPassword', 'NewPassword123!')
+    }
 
-Example Output
-```js
-[ { isAvailable: true, languageCode: 'ENG', languageName: 'English' } ]
+    if (error.statusCode === 401 && (error.result?.mustValidatePhoneNumber || error.result?.mustValidateEmailAddress)) {
+      await client.auth.resendOtp()
+      await client.auth.validateOtp('123456')
+    }
+  } else {
+    throw error
+  }
+}
 ```
 
-## Mobile Wallet Operators
-Get a list of configured mobile wallet operators for the partner. The `isAvailable` flag can be used to disable items from selection, the text will also indicate if it is currently available. This can be used when setting up mobile wallets for example by limiting the types to only what the partner supports. The `operatorCode` is what can be passed into payment request packets for mobile wallet sources or destinations.
-```js
-var mobileWalletOperators = await VantagePayClient.lookups.getMobileWalletOperators()
-```
+---
 
-Example Output
-```js
-[
-  {
-    isAvailable: false,
-    operatorCode: 'ATG',
-    operatorName: 'AirtelTigo (Currently Unavailable)'
-  },
-  { isAvailable: true, operatorCode: 'MTN', operatorName: 'MTN' },
-  { isAvailable: true, operatorCode: 'VDF', operatorName: 'Vodafone' }
-]
+## Public API Surface
+
+`VantagePay` modules:
+
+| Module | Purpose |
+|---|---|
+| `auth` | Login/logout, refresh, OTP, password, face/liveness checks, token claim helpers |
+| `lookups` | Countries, currencies, languages, banks, wallet operators, categories, product types, address resolution |
+| `consumers` | Consumer profile operations, files, limits, debit orders, feedback/support |
+| `merchants` | Merchant profile operations, OTP verify, merchant user flows, product catalog and merchant product management, POS setup/config |
+| `payments` | Payment initiation, status monitoring, tokenization, interactive payment submissions |
+| `notifications` | In-app message retrieval and lifecycle |
+| `qrCodes` | QR decode and QR image generation |
+| `reports` | Recent transactions, summaries, daily and detailed transaction reporting |
+| `system` | Health ping |
+| `content` | Client content and contact-details retrieval (cached) |
+| `log` | Structured application logging with batching |
+| `events` | PubSub event bus for session and payment signals |
+
+Example API calls:
+
+```ts
+const banks = await client.lookups.getBanks()
+const consumer = await client.consumers.getConsumer()
+const merchant = await client.merchants.getMerchant()
+const productTypes = await client.merchants.getActiveProductTypes()
+const messages = await client.notifications.getMessages()
+const recent = await client.reports.getRecentTransactions(10, true)
+await client.system.ping()
 ```
 
-## Banks
-Get a list of configured banks for the partner. The `isAvailable` flag can be used to disable items from selection, the text will also indicate if it is currently available. This can be used when setting up bank accounts for example by limiting the types to only what the partner supports. The `bankCode` is what can be passed into payment request packets for bank account sources or destinations.
-```js
-var banks = await VantagePayClient.lookups.getBanks()
-```
+---
 
-You can also optionally filter the banks returned for a specific country.
-```js
-// Only return banks in Ghana.
-var banks = await VantagePayClient.lookups.getBanks('GHA')
-```
+## Payments and Signals
+
+### Basic payment submission
 
-Example Output
-```js
-[
-  {
-    isAvailable: true,
-    bank: 'ABG',
-    bankCode: 'ABG',
-    bankName: 'ABSA Bank Ghana',
-    country: 'GHA'
+```ts
+const status = await client.payments.pay({
+  yourReference: 'ORDER-1001',
+  paymentSources: {
+    mobileWallets: [{
+      mobileWalletOperator: 'MTN',
+      msisdn: '233555666112',
+      amountInCents: 5000,
+      currency: 'GHS',
+    }],
   },
-  {
-    isAvailable: true,
-    bank: 'ABL',
-    bankCode: 'ABL',
-    bankName: 'Access Bank Ghana',
-    country: 'GHA'
+  paymentDestinations: {
+    merchants: [{
+      merchantReference: 'merchant-reference',
+      amountInCents: 5000,
+      currency: 'GHS',
+      paymentType: 'BuyingGoods',
+    }],
   },
-  {
-    isAvailable: false,
-    bank: 'FNB',
-    bankCode: 'FNB',
-    bankName: 'First National Bank Ghana (Currently Unavailable)',
-    country: 'GHA'
-  }
-]
+})
 ```
 
-## Card Issuer Country
-It is sometimes necessary to determine which country a card was issued in, you can use the card issuer country lookup with a card number to lookup the country.
-```js
-var country = await VantagePayClient.lookups.getCardIssuerCountry('5200000000000114')
-```
+### Subscribing to payment/session signals
 
-Partial numbers are also supported, 6 digits is usually sufficient, 8 digits is better.
-```js
-var country = await VantagePayClient.lookups.getCardIssuerCountry('520001')
-```
+```ts
+import {
+  OnSessionStarted,
+  OnSessionExpired,
+  OnAutomaticRefresh,
+  OnApiRetry,
+  OnPaymentStatusUpdate,
+  OnPaymentComplete,
+  OnRequiresPin,
+  OnRequiresConfirmation,
+  OnRequires3DSecure,
+  OnComplete3DSecure,
+  OnRequiresAddress,
+} from '@vantagepay/vantagepay'
 
-Example Output
-```js
-{
-  isAvailable: true,
-  country: 'MYS',
-  countryName: 'Malaysia',
-  longIsoCode: 'MYS',
-  shortIsoCode: 'MY',
-  numericIsoCode: 458,
-  diallingCode: '60'
-}
-```
+const sub1 = client.events.subscribe(OnPaymentStatusUpdate, (_, data) => {
+  console.log('status update', data)
+})
 
----
-# Subscribing to Events
-The library uses [pubsub-js](https://www.npmjs.com/package/pubsub-js) to publish messages for subscribers. To subscribe to events you can use the `events` property on the client instance, which is a wrapper around PubSub so all the functions for the base library are available.
-
-These events can be useful if your application needs to react to certain things happening behind the scenes. It is especially useful when used to automatically receive payment status updates during payment processing.
-```js
-import { VantagePay, OnApiRetry, OnAutomaticRefresh, OnSessionStarted, OnSessionExpired } from '@vantagepay/vantagepay'
-...
-const onApiRetrySub = VantagePayClient.events.subscribe(OnApiRetry, (_, retryInfo) => console.log('API performed an automatic retry', retryInfo))
-const onAutoRefreshSub = VantagePayClient.events.subscribe(OnAutomaticRefresh, (_, tokenResponse) => console.log('Automatic refresh was triggered', tokenResponse))
-const onSessionStartedSub = VantagePayClient.events.subscribe(OnSessionStarted, () => console.log('Session started'))
-const onSessionExpiredSub = VantagePayClient.events.subscribe(OnSessionExpired, () => console.log('Session expired'))
-...
-// Unsubscribe if you no longer want to receive events.
-VantagePayClient.events.unsubscribe(onApiRetrySub)
-VantagePayClient.events.unsubscribe(onAutoRefreshSub)
-VantagePayClient.events.unsubscribe(onSessionStartedSub)
-VantagePayClient.events.unsubscribe(onSessionExpiredSub)
-```
+const sub2 = client.events.subscribe(OnPaymentComplete, (_, data) => {
+  console.log('payment complete', data.paymentReference)
+})
 
-## OnSessionExpired ('login.session.expired')
-This will be fired when an automatic refresh fails or a refresh token is no longer available when making a call and you are now logged out. No data will be included with this event.
+client.events.subscribe(OnRequiresPin, async (_, data) => {
+  await client.payments.submitPinCode(data.transactionReference, '1234')
+})
 
-## OnAutomaticRefresh ('login.session.refreshed')
-This will be fired when an automatic token refresh occurs. This is useful to know when new tokens are available that you may want to save in secure storage. The token response is included with the event, you can also use `ApiTokens.accessToken` and `ApiTokens.refreshToken` to read the new values.
+client.events.subscribe(OnRequiresConfirmation, async (_, data) => {
+  await client.payments.submitConfirmation(data.transactionReference, true)
+})
 
-## OnApiRetry ('api.retry')
-This will be fired whenever there is an automatic API request retry. This is useful to indicate to application users that the network may be slow or they lack connectivity.
-The data included in the event indicates how many times the call has been retried.
-```js
-{ retryCount: 2 }
-```
+client.events.subscribe(OnRequiresAddress, async (_, data) => {
+  await client.payments.submitAddress(data.transactionReference, {
+    addressType: 'BILL',
+    addressLine1: '10 Main Road',
+    city: 'Johannesburg',
+    countryIsoCode: 'ZAF',
+    postalCode: '2196',
+  })
+})
 
-## OnPaymentStatusUpdate ('payment.status')
-During payment processing (call to `payments.pay()`) this will be fired for any status change to the payment. This is mainly due to transaction status changes that the client can display or react to. Certain status changes will also change the transaction amounts (adjustments, fees, failures and others). The recommendation here is to create a single view that renders the transaction status and on each event render the new state.
+client.events.subscribe(OnRequires3DSecure, (_, data) => {
+  window.open(data.url)
+})
 
-Transaction status data will be based on the request made. The source and destination data will be based on the source ans destinations provided in the request. All the possibilities will be documented separately.
+client.events.subscribe(OnComplete3DSecure, () => {
+  console.log('3DS completed')
+})
 
-## OnPaymentComplete ('payment.complete')
-This will be fired when the payment processing is complete. In the most basic payment processing client you can ignore `OnPaymentStatusUpdate` if you do not want to show progress and simply go to the completion screen when this fires. The event will include full payment status data the same as `OnPaymentStatusUpdate` so the transaction statuses and final amounts can be displayed. Success or failure will be based on the various transaction statues in the final results.
+client.events.subscribe(OnSessionStarted, () => console.log('session started'))
+client.events.subscribe(OnSessionExpired, () => console.log('session expired'))
+client.events.subscribe(OnAutomaticRefresh, (_, token) => console.log('refreshed', token))
+client.events.subscribe(OnApiRetry, (_, data) => console.log('retry', data.retryCount))
 
-## OnRequires3DSecure ('payment.wait.requires3dSecure')
-If card payment requires 3D Secure the client will need to launch a browser ot open an iFrame with the supplied URL and wait for `OnComplete3DSecure` to be fired before closing the browser or iFrame.
-The data will include the URL to launch.
-```js
-{ url: 'https://some_url_that_will_start-3ds' }
+client.events.unsubscribe(sub1)
+client.events.unsubscribe(sub2)
 ```
 
-### Pseudo Code
-```js
-async function handleRequires3DS(signalData) {
-  // You are given a URL that you simply need to launch or set at the `src` on an iFrame.
-  webBrowser = await open(signalData.url)
-}
+### Manual status-check control
+
+```ts
+await client.payments.startPaymentStatusChecking()            // external/incoming payment listener
+await client.payments.stopPaymentStatusChecking('payment-ref') // one payment
+await client.payments.stopPaymentStatusChecking()              // all payments
 ```
 
-## OnComplete3DSecure ('payment.complete3dSecure')
-This will fire once 3DS has completed as an indication that you can close the browser or iFrame that was launched when `OnRequires3DSecure` was fired. There is no additional data included in this event.
+### Tokenization and notifications
 
-## OnRequiresPin ('payment.wait.requiresPin')
-This will be fired if a transaction requires a PIN/OTP. The event data will include the message to display to the user so they are aware of what to provide. The text field can generally be numbers only.
-```js
-{ 
-  message: 'Please enter you Vodafone PIN to complete this transaction.',
-  transactionReference: '84125510-B042-417D-A532-47A7EBD47488',
-  pinLength: 6
-}
+```ts
+const cardToken = await client.payments.createCardToken({
+  cardNumber: '5200000000000114',
+  nameOnCard: 'John Doe',
+  expiryMonth: 9,
+  expiryYear: 2028,
+})
+
+await client.payments.sendEmailPaymentNotification('payment-reference', 'user@example.com')
+await client.payments.sendSmsPaymentNotification('payment-reference', '233548306110')
 ```
 
-Once the PIN has been captured you can make a call to `payments.submitPinCode()` with the `transactionReference` that was sent in the event to continue payment processing.
+### Payment helpers
 
-### Pseudo Code
-```js
-function handleRequiresPin(signalData) {
-  // You need to capture a PIN code and call `submitPinCode`.
-  const pin = prompt(signalData.message)
-  VantagePayClient.payments.submitPinCode(signalData.transactionReference, pin)
-}
+```ts
+client.payments.getRequiredPinLength('VDF') // 6
+client.payments.getRequiredPinLength('MTN') // 4
+client.payments.luhnCheck('5200000000000114') // true
 ```
 
-## OnRequiresConfirmation ('payment.wait.requiresConfirmation')
-This will be fired if a transaction requires confirmation such as additional fees or even to verify account information. The event data will include the message to display to the user so they are aware of what they are confirming. The dialog to display can just have Yes/No buttons.
-```js
-{ 
-  message: 'The transaction requires an additional e-levy fee of GHS 3.00. Do you want to continue?',
-  transactionReference: '6FD502DE-20FF-4110-ABBE-8FE6D7733AAE',
-  confirmationData: {
-    amountInCents: 1025,
-    sourceAccountHolder: 'Steve Rogers',
-    destinationAccountHolder: 'Tony Stark',
-    fees: []
-  }
-}
-```
+---
 
-Once the response has been captured you can make a call to `payments.submitConfirmation()` with the `transactionReference` that was sent in the event to continue payment processing.
+## Server-side Admin Usage
 
-### Pseudo Code
-```js
-function handleRequiresConfirmation(signalData) {
-  // You need to ask the user for a Yes/No answer.
-  const confirmation = prompt(signalData.message + ' -Y/N - ')
-  VantagePayClient.payments.submitConfirmation(signalData.transactionReference, confirmation === 'Y' || confirmation === 'y')
-}
+This TypeScript package does not expose admin API-key modules.
+
+For administrative workflows (for example user administration, KYC/KYB administration, template management, and admin payment/refund orchestration), use the .NET SDK `VantagePay.SDK` with `VantagePayAdminClient`.
+
+---
+
+## Additional Modules
+
+### QR utilities
+
+```ts
+const decoded = await client.qrCodes.decode('000201010211...')
+const qrBase64 = await client.qrCodes.generate('https://example.com/pay', 500)
 ```
 
-## OnRequiresAddress ('payment.wait.requiresAddress')
-This will be fired if address validation failed or an address is required but was not provided in the initial payment request. The event data will include the message to display to the user. The client should launch an address capture screen with the information provided (so it can corrected) a blank if no address information was provided.
-```js
-{ 
-  message: 'The address information provided does not appear to be valid. Please provide billing address information for this transaction.',
-  transactionReference: '6F4F250E-BF64-4BC2-936C-02E5A2982969'
-}
+### Content
+
+```ts
+const clientContent = await client.content.getClientContent()
+const contactDetails = await client.content.getContactDetails()
 ```
 
-Once the address details have been captured you can make a call to `payments.submitAddress()` with the `transactionReference` that was sent in the event to continue payment processing.
-
-### Pseudo Code
-```js
-function handleRequiresAddress(signalData) {
-  // Let the user know what is required.
-  alert(signalData.message)
-
-  // You need to capture a PIN code and call `submitPinCode`.
-  const address = {
-    addressType:    prompt('Type: ')        || 'BILL',
-    addressLine1:   prompt('Line 1: ')      || '10 Whitley Road',
-    addressLine2:   prompt('Line 2: ')      || null,
-    addressLine3:   prompt('Line 3: ')      || null,
-    countryIsoCode: prompt('Country: ')     || 'ZAF',
-    city:           prompt('City: ')        || 'Johannesburg',
-    state:          prompt('State: ')       || null,
-    postalCode:     prompt('Postal Code: ') || '2196',
-  }
+### Structured logging
 
-  VantagePayClient.payments.submitAddress(signalData.transactionReference, address)
-}
+```ts
+client.log.info('User {Username} logged in from {Country}', 'john', 'GHA')
+client.log.warn('Payment {PaymentRef} is delayed', 'PAY-123')
+await client.log.flush()
 ```