### Install Azampay Node.js SDK

Source: https://context7.com/flexcodelabs/azampay/llms.txt

Install the SDK using npm. Supports both ES6 and CommonJS import styles.

```bash
npm i azampay
```

```typescript
// ES6 import
import azampay from 'azampay';

// CommonJS require
const azampay = require('azampay').default;
```

--------------------------------

### Install Azampay SDK

Source: https://github.com/flexcodelabs/azampay/blob/main/README.md

Install the Azampay Node.js SDK using npm. Run this command in your project's root directory.

```sh
npm i azampay
```

--------------------------------

### Get Payment Partners (from Instance)

Source: https://github.com/flexcodelabs/azampay/blob/main/README.md

Instantiate the Azampay client with access token and API key, then call the partners method to get registered payment partners. The options argument is optional.

```JS
const instance = new azampay.instance({accessToken: token.data.accessToken,apiKey: 'YOUR API KEY'})
await instance.partners(options)
```

--------------------------------

### Get Payment Partners (from Token Response)

Source: https://github.com/flexcodelabs/azampay/blob/main/README.md

Call the partners method using a token object to retrieve registered payment partners. Ensure the token is valid.

```JS
await token.partners(options)
```

--------------------------------

### Get Token

Source: https://github.com/flexcodelabs/azampay/blob/main/README.md

Retrieves an access token from AzamPay using provided credentials. This token is required for subsequent API calls.

```APIDOC
## Get Token

### Description
Retrieves an access token from AzamPay. This method is essential for authenticating with the AzamPay API.

### Method
`azampay.getToken(payload)`

### Parameters
#### Request Body
- **env** (String) - Optional - Enum: SANDBOX | LIVE. Azampay environment. Default SANDBOX.
- **clientId** (String) - Required - It will be the client id generated during application registration.
- **appName** (String) - Required - It will be the name of application.
- **clientSecret** (String) - Required - It will be the secret key generated during application registration.
- **apiKey** (String) - Required - Azam Pay API key given as token in the settings page.

### Request Example
```json
{
  "env": "string",
  "clientId": "string",
  "appName": "string",
  "clientSecret": "string",
  "apiKey": "string"
}
```

### Response
#### Success Response (200 or 201)
- **data** (Object) - Azam Pay response with access token and expiry time.
- **success** (Boolean) - A `true` boolean value indicating that the request was successful.
- **message** (String) - Response message.
- **code** (Number | String) - Response code.
- **statusCode** (Number) - Response Http Status code.

#### Response Example
```json
{
  "data": {
    "accessToken": "string",
    "expire": "string"
  },
  "success": true,
  "message": "string",
  "code": "string | number",
  "statusCode": 200
}
```
```

--------------------------------

### Get Azampay Access Token

Source: https://github.com/flexcodelabs/azampay/blob/main/README.md

Retrieve an access token from AzamPay using the `getToken` method. Ensure you provide the correct payload with environment, client ID, application name, client secret, and API key.

```JSON
{
  "env": "string",
  "clientId": "string",
  "appName": "string",
  "clientSecret": "string",
  "apiKey": "string",
}
```

```JS
const token = await azampay.getToken(payload);
```

--------------------------------

### Initiate Bank Checkout from Azam Pay Instance

Source: https://github.com/flexcodelabs/azampay/blob/main/README.md

Instantiate Azam Pay with access token and API key, then use the `bankCheckout` method. The `options` argument is mandatory if not passed during instantiation.

```javascript
const instance = new azampay.instance({accessToken: token.data.accessToken,apiKey: 'YOUR API KEY'})
await instance.bankCheckout(payload, options)
```

--------------------------------

### AzamPay Instance - Direct Class Instantiation

Source: https://context7.com/flexcodelabs/azampay/llms.txt

Allows direct instantiation of the AzamPay class with credentials for managing token retrieval and payment methods independently. This is useful for long-lived instances, token refresh flows, or dependency injection.

```APIDOC
## `AzamPay` instance — Direct class instantiation

The `azampay.instance` export is the `AzamPay` class, allowing direct instantiation with credentials for use cases where the token retrieval and payment methods need to be managed independently (e.g., long-lived instances, token refresh flows, or dependency injection).

### Constructor

```ts
new azampay.instance({
  accessToken: 'your-access-token',
  apiKey: 'your-api-key',
  env: 'LIVE', // omit for SANDBOX (default)
});
```

### Usage

All methods available directly on the instance.

```ts
const instance = new azampay.instance({
  accessToken: 'your-access-token',
  apiKey: 'your-api-key',
  env: 'LIVE',
});

// Example: MNO Checkout
const mnoResult = await instance.mnoCheckout({
  accountNumber: '255787654321',
  amount: '5000',
  currency: 'TZS',
  externalId: 'order-2024-0042',
  provider: 'Airtel',
});

// Example: Bank Checkout with RequestOptions override
const bankResult = await instance.bankCheckout(
  {
    amount: '1500',
    currencyCode: 'TZS',
    merchantAccountNumber: '987654',
    merchantMobileNumber: '255711111111',
    otp: '5678',
    provider: 'CRDB',
    referenceId: 'ref-crdb-001',
  },
  { env: 'SANDBOX', accessToken: 'override-token', apiKey: 'override-key' }
);
```
```

--------------------------------

### Direct AzamPay Instance Instantiation

Source: https://context7.com/flexcodelabs/azampay/llms.txt

Allows direct instantiation of the `AzamPay` class for managing token retrieval and payment methods independently. Useful for long-lived instances or dependency injection. Environment and credentials can be overridden per-request using `RequestOptions`.

```typescript
import azampay from 'azampay';

// Instantiate with credentials obtained externally
const instance = new azampay.instance({
  accessToken: 'your-access-token',
  apiKey: 'your-api-key',
  env: 'LIVE',                  // omit for SANDBOX (default)
});

// All methods available directly on the instance
const mnoResult = await instance.mnoCheckout({
  accountNumber: '255787654321',
  amount: '5000',
  currency: 'TZS',
  externalId: 'order-2024-0042',
  provider: 'Airtel',
});

// Override env/credentials per-request via RequestOptions
const bankResult = await instance.bankCheckout(
  {
    amount: '1500',
    currencyCode: 'TZS',
    merchantAccountNumber: '987654',
    merchantMobileNumber: '255711111111',
    otp: '5678',
    provider: 'CRDB',
    referenceId: 'ref-crdb-001',
  },
  { env: 'SANDBOX', accessToken: 'override-token', apiKey: 'override-key' }
);
```

--------------------------------

### Initiate Disbursement from Instance

Source: https://github.com/flexcodelabs/azampay/blob/main/README.md

Initiates a disbursement transaction using an Azampay instance. Requires an access token and API key for initialization.

```javascript
const instance = new azampay.instance({accessToken: token.data.accessToken,apiKey: 'YOUR API KEY'})
await instance.disburse(payload, options)
```

--------------------------------

### Initiate Bank Checkout with bankCheckout

Source: https://context7.com/flexcodelabs/azampay/llms.txt

Initiate a bank checkout using OTP for CRDB or NMB accounts. This can be called from the `getToken` response or directly using an `AzamPay` instance with explicit `RequestOptions`.

```typescript
import azampay from 'azampay';

const token = await azampay.getToken({
  env: 'SANDBOX',
  appName: 'MyShopApp',
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  apiKey: 'your-api-key',
});

if (token.success && token.bankCheckout) {
  const result = await token.bankCheckout({
    amount: '2000',
    currencyCode: 'TZS',
    merchantAccountNumber: '1292-123',
    merchantMobileNumber: '255123123123',
    merchantName: null,                 // optional
    otp: '1234',
    provider: 'NMB',                    // 'CRDB' | 'NMB'
    referenceId: '123321',
    additionalProperties: null,         // optional extra JSON
  });

  if (result.success) {
    console.log('Transaction ID:', result.transactionId);
    console.log('Message:', result.message);
    // { transactionId: 'txn_xyz', message: 'Success', success: true, statusCode: 200 }
  }
}

// --- Alternative: using azampay.instance directly ---
const instance = new azampay.instance({
  accessToken: 'your-access-token',
  apiKey: 'your-api-key',
  env: 'SANDBOX',
});

const bankResult = await instance.bankCheckout({
  amount: '2000',
  currencyCode: 'TZS',
  merchantAccountNumber: '1292-123',
  merchantMobileNumber: '255123123123',
  otp: '1234',
  provider: 'CRDB',
  referenceId: 'ref-001',
});
```

--------------------------------

### Initiate MNO Checkout from Instance

Source: https://github.com/flexcodelabs/azampay/blob/main/README.md

Initiates an MNO checkout transaction using an Azampay instance. Requires an access token and API key for initialization.

```javascript
const instance = new azampay.instance({accessToken: token.data.accessToken,apiKey: 'YOUR API KEY'})
await instance.mnoCheckout(payload, options)
```

--------------------------------

### Initiate Bank Checkout from Token Response

Source: https://github.com/flexcodelabs/azampay/blob/main/README.md

Use this method to initiate a bank checkout directly from a token response object. The `options` argument is optional if provided during instantiation.

```javascript
await token.bankCheckout(payload, options)
```

--------------------------------

### bankCheckout

Source: https://context7.com/flexcodelabs/azampay/llms.txt

Initiates a bank checkout by charging an amount from a specified bank account using an OTP. This can be called directly from the `getToken` response or via an `AzamPay` instance.

```APIDOC
## bankCheckout

### Description
Initiates a bank checkout by charging an amount from a specified bank account (CRDB or NMB) using a one-time password (OTP). Can be called directly from the `getToken` response or via an `AzamPay` instance with explicit `RequestOptions`.

### Method
POST

### Endpoint
/v1/bank-checkout

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **amount** (string) - Required - The amount to charge.
- **currencyCode** (string) - Required - The currency code (e.g., 'TZS').
- **merchantAccountNumber** (string) - Required - The merchant's account number.
- **merchantMobileNumber** (string) - Required - The merchant's mobile number.
- **otp** (string) - Required - The one-time password.
- **provider** (string) - Required - The bank provider ('CRDB' | 'NMB').
- **referenceId** (string) - Required - A unique reference ID for the transaction.
- **merchantName** (string | null) - Optional - The merchant's name.
- **additionalProperties** (object | null) - Optional - Additional JSON properties.

### Request Example
```ts
// Using getToken response
if (token.success && token.bankCheckout) {
  const result = await token.bankCheckout({
    amount: '2000',
    currencyCode: 'TZS',
    merchantAccountNumber: '1292-123',
    merchantMobileNumber: '255123123123',
    otp: '1234',
    provider: 'NMB',
    referenceId: '123321',
  });
}

// Using azampay.instance
const instance = new azampay.instance({
  accessToken: 'your-access-token',
  apiKey: 'your-api-key',
  env: 'SANDBOX',
});

const bankResult = await instance.bankCheckout({
  amount: '2000',
  currencyCode: 'TZS',
  merchantAccountNumber: '1292-123',
  merchantMobileNumber: '255123123123',
  otp: '1234',
  provider: 'CRDB',
  referenceId: 'ref-001',
});
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the transaction was successful.
- **transactionId** (string) - The unique ID of the transaction.
- **message** (string) - A message indicating the status of the transaction.
- **statusCode** (number) - HTTP status code.

#### Response Example
```json
{
  "transactionId": "txn_xyz",
  "message": "Success",
  "success": true,
  "statusCode": 200
}
```
```

--------------------------------

### Generate Hosted Payment Checkout URL with postCheckout

Source: https://context7.com/flexcodelabs/azampay/llms.txt

Use this to generate a hosted payment URL for customers. Ensure redirect URLs for success and failure are correctly configured.

```typescript
import azampay from 'azampay';

const token = await azampay.getToken({
  env: 'SANDBOX',
  appName: 'MyShopApp',
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  apiKey: 'your-api-key',
});

if (token.success && token.postCheckout) {
  const result = await token.postCheckout({
    amount: '100',
    appName: 'AzampayApp',
    cart: { items: [{ name: 'Shoes' }, { name: 'Shirt' }] },
    clientId: '1292123',
    currency: 'TZS',
    externalId: 'EXT89772223',           // max 30 chars
    language: 'en',
    redirectFailURL: 'https://myshop.com/payment/fail',
    redirectSuccessURL: 'https://myshop.com/payment/success',
    requestOrigin: 'https://myshop.com',
    vendorId: 'uuid-vendor-id',
    vendorName: 'My Shop Vendor',
  });

  if (result.success) {
    // result.data contains the checkout URL — open this in a new window
    console.log('Checkout URL:', result.data);
  }
}
```

--------------------------------

### ES6 Import for Azampay SDK

Source: https://github.com/flexcodelabs/azampay/blob/main/README.md

Import the Azampay SDK using ES6 syntax. This is the recommended way to import for modern JavaScript projects.

```JS
import azampay from 'azampay'
```

--------------------------------

### Authenticate and Obtain Access Token with getToken

Source: https://context7.com/flexcodelabs/azampay/llms.txt

Use `getToken` to authenticate with Azampay API using app credentials. It returns an access token and pre-bound payment methods. Ensure correct environment and credentials are provided.

```typescript
import azampay from 'azampay';
import { TokenResponse, ErrorResponse } from 'azampay';

const token: TokenResponse | ErrorResponse = await azampay.getToken({
  env: 'SANDBOX',                       // 'SANDBOX' | 'LIVE', defaults to SANDBOX
  appName: 'MyShopApp',
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  apiKey: 'your-api-key',
});

if (!token.success) {
  console.error('Auth failed:', token.message, 'Status:', token.statusCode);
  // { success: false, message: 'Unauthorized', statusCode: 400, code: 'FAILED' }
} else {
  console.log('Access token:', token.data?.accessToken);
  console.log('Expires:', token.data?.expire);
  // token.bankCheckout, token.mnoCheckout, etc. are now available
}
```

--------------------------------

### Bank Checkout

Source: https://github.com/flexcodelabs/azampay/blob/main/README.md

Initiates a bank checkout process through AzamPay.

```APIDOC
## Bank Checkout

### Description
Initiates a Bank checkout with Azam Pay. This method is part of the `instance` class exported by the SDK.

### Method
`instance.bankCheckout(payload, options)`

### Parameters
#### Request Body (`payload`)
- **[BankCheckout properties]** - Type and description depend on the `BankCheckout` interface definition (not provided in source).

#### Request Options (`options`)
- **[RequestOptions properties]** - Type and description depend on the `RequestOptions` interface definition (not provided in source).

### Response
#### Success Response
- **[CheckoutResponse properties]** - Type and description depend on the `CheckoutResponse` interface definition (not provided in source).

#### Response Example
(Response structure depends on `CheckoutResponse` interface)
```

--------------------------------

### Request Options

Source: https://github.com/flexcodelabs/azampay/blob/main/README.md

Configuration options for making authenticated requests to the Azampay API.

```APIDOC
# Request Options

This object is used to configure authentication and environment settings for API requests.

## Payload
```json
{
  "apiKey": "string",
  "accessToken": "string",
  "env": "LIVE" | "SANDBOX"
}
```

### Properties
- **apiKey** (string) - Your Azampay API key.
- **accessToken** (string) - The access token obtained after authentication.
- **env** (string) - Specifies the environment, either 'LIVE' or 'SANDBOX'.
```

--------------------------------

### Module Require for Azampay SDK

Source: https://github.com/flexcodelabs/azampay/blob/main/README.md

Require the Azampay SDK using CommonJS syntax. Use this if you are working in a Node.js environment that uses `require`.

```JS
const azampay = require('azampay').default
```

--------------------------------

### Initiate MNO Checkout from Token Response

Source: https://github.com/flexcodelabs/azampay/blob/main/README.md

Initiates an MNO checkout transaction using a provided token. Ensure the payload and options are correctly formatted.

```javascript
await token.mnoCheckout(payload, options)
```

--------------------------------

### Azampay SDK Error Handling

Source: https://context7.com/flexcodelabs/azampay/llms.txt

Demonstrates how to handle errors from Azampay SDK methods. All methods return an `ErrorResponse` shape with `success: false` on failure. It's recommended to check `result.success` before accessing response data.

```typescript
import azampay from 'azampay';
import { TokenResponse, ErrorResponse, CheckoutResponse } from 'azampay';

const token = await azampay.getToken({
  env: 'SANDBOX',
  appName: '',          // intentionally empty — triggers auth failure
  clientId: '',
  clientSecret: '',
  apiKey: '',
});

if (!token.success) {
  // ErrorResponse shape
  console.error({
    success: token.success,         // false
    message: token.message,         // 'Unauthorized' or server error text
    statusCode: token.statusCode,   // 400, 401, 500, etc.
    code: token.code,               // 'FAILED' or server error code
  });
  process.exit(1);
}

// After successful token retrieval, handle payment method errors
const checkout = await token.mnoCheckout!({
  accountNumber: 'invalid',
  amount: '0',
  currency: 'TZS',
  externalId: 'x',
  provider: 'Airtel',
});

if (!checkout.success) {
  console.error('Checkout error:', checkout.message, '| HTTP:', checkout.statusCode);
}
```

--------------------------------

### getToken

Source: https://context7.com/flexcodelabs/azampay/llms.txt

Authenticates with the Azampay API using app credentials and returns an access token along with pre-bound payment methods. On failure, returns an ErrorResponse with success: false.

```APIDOC
## getToken

### Description
Authenticates with the Azampay API using app credentials and returns an access token along with pre-bound payment methods (`bankCheckout`, `mnoCheckout`, `disburse`, `transactionStatus`, `nameLookup`, `partners`, `postCheckout`). On failure, returns an `ErrorResponse` with `success: false`.

### Method
POST

### Endpoint
/oauth/token

### Parameters
#### Request Body
- **env** (string) - Required - 'SANDBOX' | 'LIVE', defaults to SANDBOX
- **appName** (string) - Required - The name of your application.
- **clientId** (string) - Required - Your application's client ID.
- **clientSecret** (string) - Required - Your application's client secret.
- **apiKey** (string) - Required - Your application's API key.

### Request Example
```ts
import azampay from 'azampay';

const token = await azampay.getToken({
  env: 'SANDBOX',
  appName: 'MyShopApp',
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  apiKey: 'your-api-key',
});
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the authentication was successful.
- **data** (object) - Contains the access token and expiration time.
  - **accessToken** (string) - The obtained access token.
  - **expire** (number) - The expiration time of the access token in seconds.
- **bankCheckout** (function) - Pre-bound function for bank checkouts.
- **mnoCheckout** (function) - Pre-bound function for MNO checkouts.

#### Error Response (400 or other)
- **success** (boolean) - Always false.
- **message** (string) - Error message.
- **statusCode** (number) - HTTP status code.
- **code** (string) - Error code (e.g., 'FAILED').

### Response Example
```json
{
  "success": true,
  "data": {
    "accessToken": "your-access-token",
    "expire": 3600
  },
  "bankCheckout": [Function],
  "mnoCheckout": [Function]
}
```

```json
{
  "success": false,
  "message": "Unauthorized",
  "statusCode": 400,
  "code": "FAILED"
}
```
```

--------------------------------

### postCheckout

Source: https://context7.com/flexcodelabs/azampay/llms.txt

Generates a hosted payment checkout URL by sending checkout parameters to Azampay. The merchant application can then open this URL for the customer to complete the payment.

```APIDOC
## `postCheckout` — Generate a hosted payment checkout URL

Sends checkout parameters to Azampay and returns a hosted payment URL. The merchant application opens this URL in a browser window to let the customer complete the payment flow. Supports redirect URLs for success and failure cases.

### Parameters

#### Request Body

- **amount** (string) - Required - The payment amount.
- **appName** (string) - Required - The name of the application.
- **cart** (object) - Optional - Details about the items in the cart.
  - **items** (array) - Optional - List of items.
    - **name** (string) - Optional - Name of the item.
- **clientId** (string) - Required - The client ID.
- **currency** (string) - Required - The currency code (e.g., 'TZS').
- **externalId** (string) - Required - A unique external identifier for the transaction (max 30 characters).
- **language** (string) - Optional - The preferred language for the checkout page.
- **redirectFailURL** (string) - Required - The URL to redirect to if the payment fails.
- **redirectSuccessURL** (string) - Required - The URL to redirect to if the payment is successful.
- **requestOrigin** (string) - Required - The origin of the request.
- **vendorId** (string) - Required - The vendor's unique ID.
- **vendorName** (string) - Required - The name of the vendor.

### Response

#### Success Response (200)

- **data** (string) - The hosted payment checkout URL.

### Request Example

```ts
const result = await token.postCheckout({
  amount: '100',
  appName: 'AzampayApp',
  cart: { items: [{ name: 'Shoes' }, { name: 'Shirt' }] },
  clientId: '1292123',
  currency: 'TZS',
  externalId: 'EXT89772223',
  language: 'en',
  redirectFailURL: 'https://myshop.com/payment/fail',
  redirectSuccessURL: 'https://myshop.com/payment/success',
  requestOrigin: 'https://myshop.com',
  vendorId: 'uuid-vendor-id',
  vendorName: 'My Shop Vendor',
});

if (result.success) {
  console.log('Checkout URL:', result.data);
}
```
```

--------------------------------

### Bank Checkout

Source: https://github.com/flexcodelabs/azampay/blob/main/README.md

Initiates a bank checkout process. This method can be called either from a token response object or an Azam Pay instance. It requires a request payload and optionally accepts additional options.

```APIDOC
## Bank Checkout

### Description
Initiates a bank checkout process using the provided request payload and optional configuration.

### Method
- `token.bankCheckout(payload, options)`: Called from a token response object.
- `instance.bankCheckout(payload, options)`: Called from an Azam Pay instance.

### Parameters
#### Request Payload
- **amount** (String) - Required - The amount to be charged.
- **currencyCode** (String) - Required - The code of the currency.
- **merchantAccountNumber** (String) - Required - The account number or MSISDN from which the amount will be deducted.
- **merchantMobileNumber** (String) - Required - The mobile number associated with the transaction.
- **merchantName** (String) - Optional - A nullable consumer name.
- **otp** (String) - Required - The one-time password for authentication.
- **provider** (String) - Required - Enum: 'CRDB' | 'NMB'. The bank provider.
- **referenceId** (String) - Required - An identifier for the calling application (max 128 ASCII characters).
- **additionalProperties** (Object) - Optional - Additional JSON data provided by the calling application.

#### Request Options
- These are optional if used with `token.bankCheckout` and the options were passed during instantiation. They are mandatory if using `instance.bankCheckout` and options were not provided during instantiation.

### Request Example
```json
{
  "amount": "1000",
  "currencyCode": "UGX",
  "merchantAccountNumber": "1234567890",
  "merchantMobileNumber": "0700000000",
  "otp": "123456",
  "provider": "CRDB",
  "referenceId": "REF12345"
}
```

### Response
#### Success Response (200)
- **transactionId** (String) - The unique identifier for the transaction.
- **message** (String) - A message indicating the status of the transaction.
- **success** (Boolean) - True if the operation was successful.

#### Response Example
```json
{
  "transactionId": "txn_abc123",
  "message": "Checkout initiated successfully",
  "success": true
}
```

#### Error Response
- If the operation is not successful, the response will be of type [Error Response](#error-response).
```

--------------------------------

### Post Checkout

Source: https://github.com/flexcodelabs/azampay/blob/main/README.md

Initiates a checkout process by sending transaction details to the Azampay endpoint. The response includes a URL to complete the payment.

```APIDOC
## Post Checkout

### Description
This endpoint processes a POST request to initiate a checkout. It requires a payload containing transaction details and returns a payment URL.

### Method
POST

### Endpoint
/checkout

### Parameters
#### Request Body
- **appName** (string) - Required - The name of the application.
- **clientId** (string) - Required - A unique identifier for the client.
- **vendorId** (string) - Required - A unique identifier for the vendor.
- **language** (string) - Required - The language code for the transaction.
- **currency** (string) - Required - The currency code for the transaction amount.
- **externalId** (string) - Required - A unique string, up to 30 characters, for the transaction.
- **requestOrigin** (string) - Required - The URL from which the request originates.
- **redirectFailURL** (string) - Required - The URL to redirect to upon transaction failure.
- **redirectSuccessURL** (string) - Required - The URL to redirect to upon successful transaction.
- **vendorName** (string) - Required - The name of the vendor.
- **amount** (string) - Required - The amount to be charged.
- **cart** (object) - Required - Shopping cart details.

### Request Example
```json
{
  "appName": "string",
  "clientId": "string",
  "vendorId": "string",
  "language": "string",
  "currency": "string",
  "externalId": "string",
  "requestOrigin": "string",
  "redirectFailURL": "string",
  "redirectSuccessURL": "string",
  "vendorName": "string",
  "amount": "string",
  "cart": {}
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (string) - The URL for the payment checkout.

#### Response Example
```json
{
  "success": true,
  "data": "string"
}
```
```

--------------------------------

### Request Options for Azampay API

Source: https://github.com/flexcodelabs/azampay/blob/main/README.md

Configuration options required for Azampay API requests, including API key, access token, and environment selection.

```JS
{
  apiKey: string;
  accessToken: string;
  env: 'LIVE' | 'SANDBOX';
}
```

--------------------------------

### Disbursement

Source: https://github.com/flexcodelabs/azampay/blob/main/README.md

Initiates a disbursement transaction through AzamPay.

```APIDOC
## Disbursement

### Description
Initiates a disbursement transaction through Azam Pay. This method is part of the `instance` class exported by the SDK.

### Method
`instance.disburse(payload, options)`

### Parameters
#### Request Body (`payload`)
- **[Disburse properties]** - Type and description depend on the `Disburse` interface definition (not provided in source).

#### Request Options (`options`)
- **[RequestOptions properties]** - Type and description depend on the `RequestOptions` interface definition (not provided in source).

### Response
#### Success Response
- **[DisburseResponse properties]** - Type and description depend on the `DisburseResponse` interface definition (not provided in source).

#### Response Example
(Response structure depends on `DisburseResponse` interface)
```

--------------------------------

### Retrieve Payment Partners with Azampay SDK

Source: https://context7.com/flexcodelabs/azampay/llms.txt

Fetches a list of registered payment partners for the authenticated merchant. Requires a valid token obtained via `azampay.getToken`. The `partners()` method can be called directly on the token object or on an `azampay.instance` with `RequestOptions`.

```typescript
import azampay from 'azampay';

const token = await azampay.getToken({
  env: 'SANDBOX',
  appName: 'MyShopApp',
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  apiKey: 'your-api-key',
});

if (token.success) {
  const result = await token.partners();

  if (result.success) {
    result.partners.forEach(partner => {
      console.log('Partner:', partner.partnerName);
      console.log('Provider ID:', partner.provider);  // e.g. airtel=2, tigo=3, halopesa=4
      console.log('Currency:', partner.currency);
      console.log('Logo:', partner.logoUrl);
    });
    // partners: [{ partnerName: 'Tigo', provider: 3, currency: 'TZS', ... }, ...]
  }
}

// --- Using instance with RequestOptions ---
const instance = new azampay.instance({
  accessToken: 'your-access-token',
  env: 'SANDBOX',
});
const partnersResult = await instance.partners({ apiKey: 'your-api-key' });
```

--------------------------------

### Post Checkout

Source: https://github.com/flexcodelabs/azampay/blob/main/README.md

Handles post-checkout operations with AzamPay.

```APIDOC
## Post Checkout

### Description
Handles post-checkout operations with Azam Pay. This method is part of the `instance` class exported by the SDK.

### Method
`instance.postCheckout(payload, options)`

### Parameters
#### Request Body (`payload`)
- **[PostCheckOut properties]** - Type and description depend on the `PostCheckOut` interface definition (not provided in source).

#### Request Options (`options`)
- **[RequestOptions properties]** - Type and description depend on the `RequestOptions` interface definition (not provided in source).

### Response
#### Success Response
- **[PostCheckOutInterface properties]** - Type and description depend on the `PostCheckOutInterface` interface definition (not provided in source).

#### Response Example
(Response structure depends on `PostCheckOutInterface` interface)
```

--------------------------------

### Initiate Disbursement from Token Response

Source: https://github.com/flexcodelabs/azampay/blob/main/README.md

Initiates a disbursement transaction using a provided token. The payload and options must be structured according to the API specifications.

```javascript
await token.disburse(payload, options)
```

--------------------------------

### Error Handling

Source: https://context7.com/flexcodelabs/azampay/llms.txt

Provides a consistent `ErrorResponse` shape for all SDK methods when a request fails, indicated by `success: false`. It's recommended to check the `result.success` property before accessing response data.

```APIDOC
## Error Handling

All SDK methods return a consistent `ErrorResponse` shape when a request fails, with `success: false`. Checking `result.success` before accessing response data is the recommended pattern.

### Error Response Shape

```json
{
  "success": false,
  "message": "string",      // Error message from the server
  "statusCode": number,     // HTTP status code of the error
  "code": "string"          // Server-defined error code
}
```

### Example Usage

```ts
import azampay from 'azampay';

// Example: getToken failure
const token = await azampay.getToken({
  env: 'SANDBOX',
  appName: '',          // intentionally empty — triggers auth failure
  clientId: '',
  clientSecret: '',
  apiKey: '',
});

if (!token.success) {
  console.error({
    success: token.success,
    message: token.message,
    statusCode: token.statusCode,
    code: token.code,
  });
  process.exit(1);
}

// Example: Payment method failure
const checkout = await token.mnoCheckout!({
  accountNumber: 'invalid',
  amount: '0',
  currency: 'TZS',
  externalId: 'x',
  provider: 'Airtel',
});

if (!checkout.success) {
  console.error('Checkout error:', checkout.message, '| HTTP:', checkout.statusCode);
}
```
```

--------------------------------

### Source or Destination Payload Structure

Source: https://github.com/flexcodelabs/azampay/blob/main/README.md

Payload structure for specifying source or destination account details for transactions. Includes country code, full name, bank name, account number, and currency.

```JS
 {
  countryCode: string;
  fullName: string;
  bankName: string;
  accountNumber: string;
  currency: string;
}
```

--------------------------------

### Payment Partners Response Structure

Source: https://github.com/flexcodelabs/azampay/blob/main/README.md

This is the structure of the response when requesting payment partners. It includes a success status and a list of partners.

```JS
{
  success: boolean;
  partners: Partners[];
}
```

--------------------------------

### Payment Partners

Source: https://github.com/flexcodelabs/azampay/blob/main/README.md

Retrieves a list of payment partners available through AzamPay.

```APIDOC
## Payment Partners

### Description
Retrieves a list of payment partners. This method is part of the `instance` class exported by the SDK.

### Method
`instance.paymentPartners(options)`

### Parameters
#### Request Options (`options`)
- **[RequestOptions properties]** - Type and description depend on the `RequestOptions` interface definition (not provided in source).

### Response
#### Success Response
- **[PaymentPartnersResponse properties]** - Type and description depend on the `PaymentPartnersResponse` interface definition (not provided in source).

#### Response Example
(Response structure depends on `PaymentPartnersResponse` interface)
```

--------------------------------

### Azampay SDK Response Structure

Source: https://github.com/flexcodelabs/azampay/blob/main/README.md

The response from Azampay SDK methods includes data, success status, message, code, status code, and various utility methods for different transaction types.

```JS
{
  data: { accessToken: string; expire: string };
  success: boolean;
  message: string;
  code: string | number;
  statusCode: number;
  bankCheckout: (
    payload: BankCheckout,
    options: RequestOptions
  ) => Promise<CheckoutResponse>;

  mnoCheckout: (
    payload: MnoCheckout,
    options: RequestOptions
  ) => Promise<CheckoutResponse>;

  postCheckout: (
    payload: PostCheckOut,
    options: RequestOptions
  ) => Promise<PostCheckOutInterface>;

  disburse: (
    payload: Disburse,
    options: RequestOptions
  ) => Promise<DisburseResponse>;

  transactionStatus: (
    payload: TransactionStatus,
    options: RequestOptions
  ) => Promise<TransactionStatusResponse>;

  nameLookup: (
    payload: NameLookup,
    options: RequestOptions
  ) => Promise<NameLookupResponse>;
}
```

--------------------------------

### Source or Destination Account Details

Source: https://github.com/flexcodelabs/azampay/blob/main/README.md

Defines the structure for providing source or destination account information for transactions.

```APIDOC
# Source or Destination Account Details

This payload is used to specify details for source or destination bank accounts.

## Payload
```json
{
  "countryCode": "string",
  "fullName": "string",
  "bankName": "string",
  "accountNumber": "string",
  "currency": "string"
}
```

### Properties
- **countryCode** (string) - Required - The country code for the account.
- **fullName** (string) - Required - The full name associated with the account.
- **bankName** (string) - Required - The name of the bank.
- **accountNumber** (string) - Required - The account number.
- **currency** (string) - Required - The currency of the account.
```

--------------------------------

### Post Checkout Response Structure

Source: https://github.com/flexcodelabs/azampay/blob/main/README.md

This is the expected response structure after a successful post checkout operation. It indicates the success status and provides data.

```JS
{
  data: string
  success: boolean;
  [key: string]: unknown;
}
```

--------------------------------

### mnoCheckout

Source: https://context7.com/flexcodelabs/azampay/llms.txt

Initiates a mobile money operator (MNO) checkout, deducting an amount from a mobile money account. Uses an `externalId` to identify the originating application's transaction.

```APIDOC
## mnoCheckout

### Description
Initiates a mobile money operator (MNO) checkout, deducting an amount from a mobile money account (Airtel, Tigo, Halopesa, Azampesa, or Mpesa). Uses an `externalId` (instead of `referenceId`) to identify the originating application's transaction.

### Method
POST

### Endpoint
/v1/mno-checkout

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **accountNumber** (string) - Required - The customer's mobile money account number.
- **amount** (string) - Required - The amount to deduct.
- **currency** (string) - Required - The currency code (e.g., 'TZS').
- **externalId** (string) - Required - A unique identifier for the transaction from the originating application (max 128 ASCII chars).
- **provider** (string) - Required - The MNO provider ('Airtel' | 'Tigo' | 'Halopesa' | 'Azampesa' | 'Mpesa').
- **additionalProperties** (object | null) - Optional - Additional JSON properties.

### Request Example
```ts
// Using getToken response
if (token.success && token.mnoCheckout) {
  const result = await token.mnoCheckout({
    accountNumber: '255712345678',
    amount: '2000',
    currency: 'TZS',
    externalId: 'order-ref-9901',
    provider: 'Tigo',
  });
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was processed successfully.
- **transactionId** (string) - The unique ID of the transaction.
- **message** (string) - A message indicating the status (e.g., 'Pending').
- **statusCode** (number) - HTTP status code.

#### Error Response
- **success** (boolean) - Always false.
- **message** (string) - Error message.
- **statusCode** (number) - HTTP status code.

### Response Example
```json
{
  "transactionId": "txn_abc",
  "message": "Pending",
  "success": true,
  "statusCode": 200
}
```

```json
{
  "success": false,
  "message": "Invalid account number",
  "statusCode": 400
}
```
```

--------------------------------

### Retrieve Payment Partners

Source: https://context7.com/flexcodelabs/azampay/llms.txt

Fetches the list of registered payment partners for the authenticated merchant, including details like logos, provider enums, and currency.

```APIDOC
## `partners` — Retrieve registered payment partners

Returns the list of payment partners registered for the authenticated merchant, including their logos, provider enum values, currency, vendor details, and unique IDs.

### Method

```ts
await token.partners();
```

### Request Example

```ts
const result = await token.partners();

if (result.success) {
  result.partners.forEach(partner => {
    console.log('Partner:', partner.partnerName);
    console.log('Provider ID:', partner.provider);  // e.g. airtel=2, tigo=3, halopesa=4
    console.log('Currency:', partner.currency);
    console.log('Logo:', partner.logoUrl);
  });
  // partners: [{ partnerName: 'Tigo', provider: 3, currency: 'TZS', ... }, ...]
}
```

### Response

#### Success Response

- **partners** (array) - List of payment partner objects.
  - **partnerName** (string) - The name of the partner.
  - **provider** (number) - The provider enum value.
  - **currency** (string) - The currency supported by the partner.
  - **logoUrl** (string) - The URL of the partner's logo.
```

--------------------------------

### MNO Checkout

Source: https://github.com/flexcodelabs/azampay/blob/main/README.md

Initiates a Mobile Network Operator (MNO) checkout process through AzamPay.

```APIDOC
## MNO Checkout

### Description
Initiates an MNO checkout with Azam Pay. This method is part of the `instance` class exported by the SDK.

### Method
`instance.mnoCheckout(payload, options)`

### Parameters
#### Request Body (`payload`)
- **[MnoCheckout properties]** - Type and description depend on the `MnoCheckout` interface definition (not provided in source).

#### Request Options (`options`)
- **[RequestOptions properties]** - Type and description depend on the `RequestOptions` interface definition (not provided in source).

### Response
#### Success Response
- **[CheckoutResponse properties]** - Type and description depend on the `CheckoutResponse` interface definition (not provided in source).

#### Response Example
(Response structure depends on `CheckoutResponse` interface)
```

--------------------------------

### Initiate Mobile Money Operator (MNO) Checkout

Source: https://context7.com/flexcodelabs/azampay/llms.txt

Deduct an amount from a mobile money account using `mnoCheckout`. This method uses an `externalId` to identify the originating application's transaction.

```typescript
import azampay from 'azampay';

const token = await azampay.getToken({
  env: 'SANDBOX',
  appName: 'MyShopApp',
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  apiKey: 'your-api-key',
});

if (token.success && token.mnoCheckout) {
  const result = await token.mnoCheckout({
    accountNumber: '255712345678',
    amount: '2000',
    currency: 'TZS',
    externalId: 'order-ref-9901',       // max 128 ASCII chars
    provider: 'Tigo',                   // 'Airtel' | 'Tigo' | 'Halopesa' | 'Azampesa' | 'Mpesa'
    additionalProperties: null,
  });

  if (result.success) {
    console.log('Transaction ID:', result.transactionId);
    // { transactionId: 'txn_abc', message: 'Pending', success: true, statusCode: 200 }
  } else {
    console.error('MNO checkout failed:', result.message);
  }
}
```

--------------------------------

### Azam Pay Bank Checkout Response Structure

Source: https://github.com/flexcodelabs/azampay/blob/main/README.md

The expected response structure for a successful bank checkout transaction. Always check the `success` property to determine the outcome.

```json
{
  "transactionId": string,
  "message": string,
  "succcess": true
}
```

--------------------------------

### MNO Checkout

Source: https://github.com/flexcodelabs/azampay/blob/main/README.md

Initiates a mobile network operator (MNO) checkout process. This method is used to charge a specified amount from a given account via a mobile network operator.

```APIDOC
## MNO Checkout

### Description
Initiates a mobile network operator (MNO) checkout process. This method is used to charge a specified amount from a given account via a mobile network operator.

### Method
POST (inferred from checkout operation)

### Endpoint
/checkout/mno (inferred)

### Parameters
#### Request Body
- **amount** (String) - Required - The amount to be charged from the account.
- **currencyCode** (String) - Required - The code of the currency for the transaction.
- **accountNumber** (String) - Required - The account number or MSISDN from which the amount will be deducted.
- **provider** (String) - Required - Enum: Airtel | Tigo | Halopesa | Azampesa | Mpesa. The mobile network operator.
- **externalId** (String) - Required - An ID belonging to the calling application. Maximum length is 128 ASCII characters.
- **additionalProperties** (Object) - Optional - Additional JSON data that the calling application can provide.

### Request Example
```json
{
  "accountNumber": "string",
  "amount": "string",
  "currencyCode": "string",
  "provider": "Airtel" | "Tigo" | "Halopesa" | "Azampesa" | "Mpesa",
  "externalId": "string",
  "additionalProperties": {}
}
```

### Response
#### Success Response (200)
- **data** (string) - Contains the status of the transaction.
- **message** (string) - A human-readable message describing the response.
- **success** (boolean) - Indicates whether the request was successful.
- **statusCode** (number) - The status code of the response.

#### Response Example
```json
{
  "data": "Transaction successful",
  "message": "Checkout completed successfully",
  "success": true,
  "statusCode": 200
}
```
```