### Installation

Source: https://github.com/techquest/interswitch_javascript/blob/master/README.md

Instructions on how to install the Interswitch Node.js library using npm.

```APIDOC
## Installation

```bash
$ npm install interswitch
```
```

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

### Install Interswitch SDK

Source: https://github.com/techquest/interswitch_javascript/blob/master/README.md

Command to install the Interswitch Node.js library via the npm package manager.

```bash
npm install interswitch
```

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

### Sample Payment Request

Source: https://github.com/techquest/interswitch_javascript/blob/master/README.md

Example of how to initiate a payment request using the Interswitch Node.js library.

```APIDOC
## Sample Payment Request

### Description
This example demonstrates how to set up and send a payment validation request to the Interswitch API using the Node.js library.

### Method
POST

### Endpoint
api/v2/purchases/validations

### Parameters
#### Request Body
- **transactionRef** (string) - Required - A unique reference for the transaction.
- **authData** (object) - Required - Authentication data for the transaction.

### Request Example
```javascript
var Interswitch = require('interswitch')
var clientId = ""; // Get your Client ID from https://developer.interswitchng.com
var secret = ""; // Get your Client Secret from https://developer.interswitchng.com
var ENV = "SANDBOX"; // or PRODUCTION
var interswitch = new Interswitch(clientId, secret, ENV);


var id = getUniqueId();// you can use any uuid library of your choice

var paymentReqRef = "ISW-SDK-PAYMENT-" + id;
var req = { "transactionRef": paymentReqRef , "authData": authData };

var obj = {
    url: "api/v2/purchases/validations",
    method: "POST",
    requestData: req,
    httpHeaders: {"Content-Type": "application/json"}
};

//send the actual request
interswitch.send(obj,function(err, response, body){
    if(err) {
        //error handling
        console.error(err);
    }else {
        //success
        console.log(JSON.stringify(response));
    }
});
```

### Response
#### Success Response (200)
- **response** (object) - The response object from the Interswitch API.

#### Response Example
```json
{
  "status": "success",
  "data": { ... }
}
```
```

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

### GET /oauth/token

Source: https://context7.com/techquest/interswitch_javascript/llms.txt

The `getNewAccessToken()` method explicitly requests a new OAuth access token from Interswitch Passport using client credentials grant.

```APIDOC
## GET /oauth/token

### Description
Explicitly requests a new OAuth access token from Interswitch Passport using client credentials grant.

### Method
GET (Implicitly called by `getNewAccessToken()`)

### Endpoint
/oauth/token (Internal endpoint for token retrieval)

### Parameters
No direct parameters for the user. The SDK uses configured client ID and secret.

### Response
#### Success Response
- **access_token** (string) - The requested OAuth access token
- **expires_in** (integer) - The token's lifetime in seconds
- **token_type** (string) - The type of token (e.g., Bearer)

#### Response Example
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "token_type": "Bearer"
}
```
```

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

### Initialize Interswitch Client

Source: https://context7.com/techquest/interswitch_javascript/llms.txt

Demonstrates how to instantiate the Interswitch client using API credentials and environment settings. It also shows how to toggle between sandbox and production environments.

```javascript
var Interswitch = require('interswitch');
var clientId = "IKIA9614B82064D632E9B6418DF358A6A4AEA84D7218";
var secret = "XCTiBtLy1G9chAnyg0z3BcaFK4cVpwDg/GTw2EmjTZ8=";
var ENV = "SANDBOX";
var interswitch = new Interswitch(clientId, secret, ENV);
interswitch.setEnvironment("PRODUCTION");
```

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

### Initialize and Send Payment Request

Source: https://github.com/techquest/interswitch_javascript/blob/master/README.md

Demonstrates how to initialize the Interswitch client and send a payment validation request. It requires a Client ID, Client Secret, and environment configuration.

```javascript
var Interswitch = require('interswitch');
var clientId = "";
var secret = "";
var ENV = "SANDBOX";
var interswitch = new Interswitch(clientId, secret, ENV);

var id = getUniqueId();
var paymentReqRef = "ISW-SDK-PAYMENT-" + id;
var req = { "transactionRef": paymentReqRef , "authData": authData };
var obj = {
    url: "api/v2/purchases/validations",
    method: "POST",
    requestData: req,
    httpHeaders: {"Content-Type": "application/json"}
};

interswitch.send(obj, function(err, response, body) {
    if(err) {
        // Handle error
    } else {
        console.log(JSON.stringify(response));
    }
});
```

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

### Process Card Purchases with Interswitch JavaScript SDK

Source: https://context7.com/techquest/interswitch_javascript/llms.txt

Initiates a card purchase transaction by sending encrypted card details and transaction information to the Interswitch purchases endpoint. Requires client ID, secret, and transaction details including card PAN, expiry date, CVV, PIN, amount, and currency. Returns transaction status and receipt.

```javascript
var Interswitch = require('interswitch');
var interswitch = new Interswitch(clientId, secret, "SANDBOX");

// Generate encrypted auth data first
var authData = interswitch.getAuthData({
    pan: "6280511000000095",
    expDate: "1909",
    cvv: "123",
    pin: "1234"
});

// Unique transaction reference
var transactionId = Date.now() + Math.floor(Math.random() * 1000);

// Purchase request payload
var purchaseRequest = {
    "customerId": "customer@email.com",    // Unique customer identifier
    "amount": "100",                        // Amount in Naira
    "transactionRef": transactionId,        // Unique transaction reference
    "currency": "NGN",                      // ISO currency code
    "authData": authData                    // Encrypted card data
};

interswitch.send({
    url: "api/v2/purchases",
    method: "POST",
    requestData: purchaseRequest,
    httpHeaders: {"Content-Type": "application/json"}
}, function(err, response, body) {
    if (err) {
        console.log("Purchase Error:", JSON.stringify(err));
        return;
    }

    var result = JSON.parse(body);
    console.log("Purchase Response:", JSON.stringify(response));
    // Expected response includes transaction status, reference, and receipt
});
```

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

### Generate Secure Data for Advanced Transactions with Interswitch JavaScript SDK

Source: https://context7.com/techquest/interswitch_javascript/llms.txt

Generates a secure data bundle containing encrypted PIN block and MAC for advanced payment operations. It takes transaction parameters like card details, amount, and mobile number as input. The output includes RSA encrypted secure payload, 3DES encrypted PIN block, and HMAC-SHA256 MAC, which can be used in requests like paycode generation.

```javascript
var Interswitch = require('interswitch');
var interswitch = new Interswitch(clientId, secret, "SANDBOX");

// Transaction parameters
var transactionOptions = {
    pan: "6280511000000095",          // Card PAN
    expDate: "1909",                  // Expiry date (YYMM)
    cvv: "123",                       // CVV
    pin: "1234",                      // PIN
    amount: "100000",                 // Amount in kobo
    mobile: "2348098674523",          // Mobile number
    ttId: 456                         // Terminal transaction ID (optional)
};

// Generate secure data bundle
var secureBundle = interswitch.getSecureData(transactionOptions);

console.log("Secure Data:", secureBundle.secureData);  // RSA encrypted secure payload
console.log("PIN Block:", secureBundle.pinBlock);      // 3DES encrypted PIN block
console.log("MAC:", secureBundle.mac);                 // HMAC-SHA256 message authentication

// Use in paycode generation request
var paycodeRequest = {
    "amount": 100000,
    "ttid": 456,
    "transactionType": "Withdrawal",
    "paymentMethodIdentifier": "payment-token-here",
    "payWithMobileChannel": "ATM",
    "tokenLifeTimeInMinutes": "100",
    "oneTimePin": "1111",
    "pinData": secureBundle.pinBlock,
    "secure": secureBundle.secureData,
    "macData": secureBundle.mac
};
```

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

### Perform Requests with Existing Access Token

Source: https://context7.com/techquest/interswitch_javascript/llms.txt

Utilizes the sendWithAccessToken() method for operations requiring a pre-existing OAuth token, such as e-wallet queries.

```javascript
var Interswitch = require('interswitch');
var interswitch = new Interswitch(clientId, secret, "SANDBOX");
var accessToken = "eyJhbGciOiJSUzI1NiJ9...";
var requestOptions = {
    url: "api/v1/ewallet/instruments",
    method: "GET",
    accessToken: accessToken
};
interswitch.sendWithAccessToken(requestOptions, function(err, response, body) {
    if (err) {
        console.log("Error:", JSON.stringify(err));
        return;
    }
    var responseBody = JSON.parse(response.body);
    if (response.statusCode === 200) {
        console.log("E-Wallet Instruments:", responseBody.paymentMethods);
    } else {
        console.log("Request failed:", response.statusCode);
    }
});
```

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

### Execute Authenticated API Requests

Source: https://context7.com/techquest/interswitch_javascript/llms.txt

Uses the send() method to perform authenticated API calls. The SDK handles OAuth token acquisition and security headers automatically.

```javascript
var Interswitch = require('interswitch');
var interswitch = new Interswitch(clientId, secret, "SANDBOX");
var requestOptions = {
    url: "api/v2/purchases/validations",
    method: "POST",
    requestData: {
        "transactionRef": "ISW-SDK-PAYMENT-12345",
        "authData": authData
    },
    httpHeaders: {
        "Content-Type": "application/json"
    }
};
interswitch.send(requestOptions, function(err, response, body) {
    if (err) {
        console.log("Error:", JSON.stringify(err));
        return;
    }
    console.log("Response:", JSON.stringify(response));
    console.log("Body:", body);
});
```

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

### Paycode Generation Workflow

Source: https://context7.com/techquest/interswitch_javascript/llms.txt

This workflow generates a paycode for ATM withdrawals using E-Wallet payment methods, combining multiple API calls with secure data generation.

```APIDOC
## POST /api/v1/pwm/subscribers/{msisdn}/tokens

### Description
Generates a paycode for ATM withdrawals using E-Wallet payment methods.

### Method
POST

### Endpoint
/api/v1/pwm/subscribers/{msisdn}/tokens

### Parameters
#### Path Parameters
- **msisdn** (string) - Required - Mobile Station International Subscriber Directory Number (phone number).

#### Headers
- **frontendpartnerid** (string) - Required - The partner ID (e.g., "WEMA").
- **Authorization** (string) - Required - Bearer token for authentication.

#### Request Body
- **amount** (integer) - Required - The transaction amount in the smallest currency unit (e.g., cents).
- **ttid** (integer) - Required - Transaction terminal ID.
- **transactionType** (string) - Required - Type of transaction (e.g., "Withdrawal").
- **paymentMethodIdentifier** (string) - Required - Token representing the e-wallet payment method.
- **payWithMobileChannel** (string) - Required - Channel for pay with mobile (e.g., "ATM").
- **tokenLifeTimeInMinutes** (string) - Required - Duration for which the paycode is valid.
- **oneTimePin** (string) - Required - A one-time PIN for the transaction.
- **pinData** (string) - Required - Encrypted PIN block.
- **secure** (string) - Required - Secure data for the transaction.
- **macData** (string) - Required - Message Authentication Code data.

### Request Example
```json
{
  "amount": 100000,
  "ttid": 123,
  "transactionType": "Withdrawal",
  "paymentMethodIdentifier": "wallet_token_abc123",
  "payWithMobileChannel": "ATM",
  "tokenLifeTimeInMinutes": "100",
  "oneTimePin": "1111",
  "pinData": "encrypted_pin_block_here",
  "secure": "secure_data_here",
  "macData": "mac_data_here"
}
```

### Response
#### Success Response (200 or 201)
- **payWithMobileToken** (string) - The generated paycode.

#### Response Example
```json
{
  "payWithMobileToken": "paycode_xyz789"
}
```
```

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

### Generate ATM Paycode via E-Wallet

Source: https://context7.com/techquest/interswitch_javascript/llms.txt

This workflow retrieves e-wallet instruments, decodes user identity, generates secure encryption bundles, and requests a paycode for cardless ATM withdrawals. It requires an OAuth access token and handles multi-step API communication.

```javascript
var jwt = require('jsonwebtoken');
var Interswitch = require('interswitch');
var interswitch = new Interswitch(clientId, secret, "SANDBOX");
var accessToken = "your-oauth-access-token";

interswitch.sendWithAccessToken({
    url: "api/v1/ewallet/instruments",
    method: "GET",
    accessToken: accessToken
}, function(err, response, body) {
    if (err || response.statusCode !== 200) return;

    var walletData = JSON.parse(response.body);
    var paymentToken = walletData.paymentMethods[0].token;
    var decoded = jwt.decode(accessToken);
    var msisdn = decoded.mobileNo;
    var ttid = Math.floor(Math.random() * 900) + 100;
    var secureBundle = interswitch.getSecureData({
        expDate: "1909",
        cvv: "123",
        pin: "1234",
        mobile: msisdn,
        ttId: ttid
    });

    var paycodeRequest = {
        "amount": 100000,
        "ttid": ttid,
        "transactionType": "Withdrawal",
        "paymentMethodIdentifier": paymentToken,
        "payWithMobileChannel": "ATM",
        "tokenLifeTimeInMinutes": "100",
        "oneTimePin": "1111",
        "pinData": secureBundle.pinBlock,
        "secure": secureBundle.secureData,
        "macData": secureBundle.mac
    };

    interswitch.sendWithAccessToken({
        url: "api/v1/pwm/subscribers/" + msisdn + "/tokens",
        method: "POST",
        accessToken: accessToken,
        httpHeaders: {"frontendpartnerid": "WEMA"},
        requestData: paycodeRequest
    }, function(err, response, body) {
        if (err) console.log("Paycode Error:", JSON.stringify(err));
        else console.log("Paycode Generated:", JSON.parse(response.body).payWithMobileToken);
    });
});
```

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

### Generate Encrypted AuthData

Source: https://context7.com/techquest/interswitch_javascript/llms.txt

Uses getAuthData() to securely encrypt sensitive card details like PAN, PIN, and CVV using RSA encryption for safe transmission.

```javascript
var Interswitch = require('interswitch');
var interswitch = new Interswitch(clientId, secret, "SANDBOX");
var cardOptions = {
    pan: "6280511000000095",
    expDate: "1909",
    cvv: "123",
    pin: "1234"
};
var authData = interswitch.getAuthData(cardOptions);
console.log("Encrypted AuthData:", authData);
```

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

### Validate Payment Transaction with Interswitch SDK

Source: https://context7.com/techquest/interswitch_javascript/llms.txt

This snippet demonstrates how to validate a card transaction by generating encrypted authentication data and sending a POST request to the Interswitch validation endpoint. It ensures card details are valid before proceeding to the actual purchase flow.

```javascript
var Interswitch = require('interswitch');
var interswitch = new Interswitch(clientId, secret, "SANDBOX");

var authData = interswitch.getAuthData({
    pan: "6280511000000095",
    expDate: "1909",
    cvv: "123",
    pin: "1234"
});

var generateUniqueId = function() {
    var id = Date.now();
    id += (id + Math.random() * 16) % 16 | 0;
    return id;
};

var transactionRef = "ISW-SDK-PAYMENT-" + generateUniqueId();

var validationRequest = {
    "transactionRef": transactionRef,
    "authData": authData
};

interswitch.send({
    url: "api/v2/purchases/validations",
    method: "POST",
    requestData: validationRequest,
    httpHeaders: {"Content-Type": "application/json"}
}, function(err, response, body) {
    if (err) {
        console.log("Validation Error:", JSON.stringify(err));
        return;
    }
    var validationResult = JSON.parse(body);
    console.log("Validation Successful:", JSON.stringify(response));
});
```

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

### POST /api/v2/purchases

Source: https://context7.com/techquest/interswitch_javascript/llms.txt

Complete a card purchase transaction by sending encrypted card data along with transaction details to the purchases endpoint.

```APIDOC
## POST /api/v2/purchases

### Description
Complete a card purchase transaction by sending encrypted card data along with transaction details to the purchases endpoint.

### Method
POST

### Endpoint
/api/v2/purchases

### Parameters
#### Request Body
- **customerId** (string) - Required - Unique customer identifier
- **amount** (string) - Required - Amount in Naira
- **transactionRef** (string) - Required - Unique transaction reference
- **currency** (string) - Required - ISO currency code
- **authData** (object) - Required - Encrypted card data
  - **pan** (string) - Required - Card Number
  - **expDate** (string) - Required - Expiry date (YYMM)
  - **cvv** (string) - Required - CVV
  - **pin** (string) - Required - PIN

### Request Example
```json
{
  "customerId": "customer@email.com",
  "amount": "100",
  "transactionRef": "1678886400000123",
  "currency": "NGN",
  "authData": {
    "pan": "6280511000000095",
    "expDate": "1909",
    "cvv": "123",
    "pin": "1234"
  }
}
```

### Response
#### Success Response (200)
- **status** (string) - Transaction status
- **transactionRef** (string) - Transaction reference
- **receipt** (string) - Transaction receipt details

#### Response Example
```json
{
  "status": "00",
  "transactionRef": "1678886400000123",
  "receipt": "Success"
}
```
```

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

### Generating Secure Data for Advanced Transactions

Source: https://context7.com/techquest/interswitch_javascript/llms.txt

The `getSecureData()` method generates secure transaction data including encrypted PIN block and MAC (Message Authentication Code) for advanced payment operations like ATM withdrawals and paycodes.

```APIDOC
## Generating Secure Data for Advanced Transactions

### Description
The `getSecureData()` method generates secure transaction data including encrypted PIN block and MAC (Message Authentication Code) for advanced payment operations like ATM withdrawals and paycodes.

### Method
`getSecureData(transactionOptions)`

### Parameters
#### Request Parameters
- **transactionOptions** (object) - Required - Transaction details for secure data generation
  - **pan** (string) - Required - Card PAN
  - **expDate** (string) - Required - Expiry date (YYMM)
  - **cvv** (string) - Required - CVV
  - **pin** (string) - Required - PIN
  - **amount** (string) - Required - Amount in kobo
  - **mobile** (string) - Required - Mobile number
  - **ttId** (number) - Optional - Terminal transaction ID

### Response
Returns an object containing:
- **secureData** (string) - RSA encrypted secure payload
- **pinBlock** (string) - 3DES encrypted PIN block
- **mac** (string) - HMAC-SHA256 message authentication code

### Example Usage in Paycode Generation
```json
{
  "amount": 100000,
  "ttid": 456,
  "transactionType": "Withdrawal",
  "paymentMethodIdentifier": "payment-token-here",
  "payWithMobileChannel": "ATM",
  "tokenLifeTimeInMinutes": "100",
  "oneTimePin": "1111",
  "pinData": "encrypted_pin_block",
  "secure": "encrypted_secure_data",
  "macData": "message_authentication_code"
}
```
```

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

### Retrieve New Access Token with Interswitch JavaScript SDK

Source: https://context7.com/techquest/interswitch_javascript/llms.txt

Explicitly requests a new OAuth access token from Interswitch Passport using the client credentials grant. This method is useful for refreshing tokens or obtaining a new one when the current one expires. It returns the access token string and the full response object.

```javascript
var Interswitch = require('interswitch');
var interswitch = new Interswitch(clientId, secret, "SANDBOX");

// Request a new access token
interswitch.getNewAccessToken(function(err, accessToken, response) {
    if (err) {
        console.log("Token Error:", JSON.stringify(err));
        return;
    }

    console.log("New Access Token:", accessToken);
    console.log("Full Response:", JSON.stringify(response));

    // Token can be stored and used with sendWithAccessToken()
    // Token expires based on Interswitch's OAuth configuration
});
```

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

### Complete Payment Validation Flow

Source: https://context7.com/techquest/interswitch_javascript/llms.txt

This endpoint validates a payment transaction before processing to ensure the card and transaction details are valid.

```APIDOC
## POST /api/v2/purchases/validations

### Description
Validates a payment transaction before processing to ensure the card and transaction details are valid.

### Method
POST

### Endpoint
/api/v2/purchases/validations

### Parameters
#### Request Body
- **transactionRef** (string) - Required - A unique reference for the transaction.
- **authData** (object) - Required - Encrypted authentication data.
  - **pan** (string) - Required - Primary Account Number (card number).
  - **expDate** (string) - Required - Expiry date in MMYY format.
  - **cvv** (string) - Required - Card Verification Value.
  - **pin** (string) - Required - Personal Identification Number.

### Request Example
```json
{
  "transactionRef": "ISW-SDK-PAYMENT-1678886400000",
  "authData": {
    "pan": "6280511000000095",
    "expDate": "1909",
    "cvv": "123",
    "pin": "1234"
  }
}
```

### Response
#### Success Response (200)
- **validationResult** (object) - The result of the validation.

#### Response Example
```json
{
  "message": "Validation Successful"
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.