### Install masspay-js-sdk with npm

Source: https://github.com/masspayio/masspay-js-sdk/blob/main/README.md

Use this command to install the SDK using npm.

```shell
npm install masspay-js-sdk
```

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

### Install and Initialize MassPay JavaScript SDK

Source: https://context7.com/masspayio/masspay-js-sdk/llms.txt

Install the SDK using npm or yarn. Initialize it with your API key and optionally set the base API URL.

```javascript
// Install via npm
// npm install masspay-js-sdk

// Install via yarn
// yarn add masspay-js-sdk

import { MasspayJsSdk, ApiError } from 'masspay-js-sdk';

// Initialize the SDK with your API key
const sdk = new MasspayJsSdk({
  AUTHORIZER_NAME_API_KEY: 'your-api-key-here',
  BASE: 'https://api.masspay.io/v1.0.0', // Optional: default API base URL
});

// SDK is now ready to use
// Access services via sdk.AccountService, sdk.UserService, etc.
```

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

### Install masspay-js-sdk with yarn

Source: https://github.com/masspayio/masspay-js-sdk/blob/main/README.md

Use this command to install the SDK using yarn.

```shell
yarn add masspay-js-sdk
```

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

### Initialize and use Masspay JS SDK

Source: https://github.com/masspayio/masspay-js-sdk/blob/main/README.md

Import the SDK, initialize it with your API key, and make a call to get account balance. Ensure to handle potential errors.

```javascript
import { MasspayJsSdk } from 'masspay-js-sdk';

const sdk = new MasspayJsSdk({
  AUTHORIZER_NAME_API_KEY: 'YOUR API KEY',
});
(async () => {
  try {
    const response = await sdk.AccountService.getAccountBalance({
      /* query parameters */
    });
    // use response data
  } catch (error) {
    // handle error
  }
})();
```

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

### GET /payout/wallet/{user_token}

Source: https://github.com/masspayio/masspay-js-sdk/blob/main/README.md

Retrieves all available wallets for a specific user.

```APIDOC
## GET /payout/wallet/{user_token}

### Description
Retrieve all available wallets for a user.

### Method
GET

### Endpoint
/payout/wallet/{user_token}

### Parameters
#### Path Parameters
- **user_token** (string) - Required - The unique token identifying the user.
```

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

### GET /payout/user/lookup

Source: https://github.com/masspayio/masspay-js-sdk/blob/main/README.md

Performs a lookup for an existing user.

```APIDOC
## GET /payout/user/lookup

### Description
Lookup an existing user.

### Method
GET

### Endpoint
/payout/user/lookup
```

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

### GET /payout/wallet/{user_token}/{wallet_token}/autopayout

Source: https://github.com/masspayio/masspay-js-sdk/blob/main/README.md

Retrieves all AutoPayout rules for a specific wallet.

```APIDOC
## GET /payout/wallet/{user_token}/{wallet_token}/autopayout

### Description
Get all AutoPayout rules.

### Method
GET

### Endpoint
/payout/wallet/{user_token}/{wallet_token}/autopayout

### Parameters
#### Path Parameters
- **user_token** (string) - Required - The unique token identifying the user.
- **wallet_token** (string) - Required - The unique token identifying the wallet.
```

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

### GET /payout/user/{user_token}

Source: https://github.com/masspayio/masspay-js-sdk/blob/main/README.md

Retrieves user details based on the provided user token.

```APIDOC
## GET /payout/user/{user_token}

### Description
Get user by user token.

### Method
GET

### Endpoint
/payout/user/{user_token}

### Parameters
#### Path Parameters
- **user_token** (string) - Required - The unique token identifying the user.
```

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

### Get MassPay Account Balance

Source: https://context7.com/masspayio/masspay-js-sdk/llms.txt

Retrieve your current available balance across different currencies. Requires the SDK to be initialized.

```javascript
import { MasspayJsSdk, ApiError } from 'masspay-js-sdk';

const sdk = new MasspayJsSdk({
  AUTHORIZER_NAME_API_KEY: 'your-api-key',
});

async function checkAccountBalance() {
  try {
    const balances = await sdk.AccountService.getAccountBalance();

    // Response: Array of balance objects
    // [
    //   {
    //     token: "balance_token_123",
    //     balance: 10000.50,
    //     currency_code: "USD"
    //   },
    //   {
    //     token: "balance_token_456",
    //     balance: 5000.00,
    //     currency_code: "EUR"
    //   }
    // ]

    balances.forEach(account => {
      console.log(`Currency: ${account.currency_code}, Balance: ${account.balance}`);
    });

    return balances;
  } catch (error) {
    if (error instanceof ApiError) {
      console.error(`API Error ${error.status}: ${error.statusText}`);
    }
    throw error;
  }
}
```

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

### SpendBackService.initiateSpendback

Source: https://context7.com/masspayio/masspay-js-sdk/llms.txt

Initiates a spendback transaction to return funds from a user's wallet back to a source. Useful for refunds or fund reversals.

```APIDOC
## POST /spendback/initiate

### Description
Initiates a spendback transaction to return funds from a user's wallet back to a source. Useful for refunds or fund reversals.

### Method
POST

### Endpoint
/spendback/initiate

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **userToken** (string) - Required - The token of the user initiating the spendback.
- **idempotencyKey** (string) - Required - A unique key to ensure the request is processed only once.
- **spendback** (object) - Required - Details of the spendback transaction.
  - **client_spendback_id** (string) - Required - A unique identifier for the spendback transaction from the client's perspective.
  - **source_token** (string) - Required - The token of the wallet from which funds will be returned.
  - **source_currency_code** (string) - Required - The currency code of the source wallet (e.g., 'USD').
  - **amount** (number) - Required - The amount of funds to be returned.
  - **notes** (string) - Optional - Additional notes for the transaction.

### Request Example
```json
{
  "userToken": "user_token_xyz",
  "idempotencyKey": "idempotency-key-spendback-123",
  "spendback": {
    "client_spendback_id": "spendback-1678886400000",
    "source_token": "wallet_token_abc123",
    "source_currency_code": "USD",
    "amount": 100.00,
    "notes": "Refund for order #12345"
  }
}
```

### Response
#### Success Response (200)
- **spendback_token** (string) - The unique token for the initiated spendback transaction.
- **client_spendback_id** (string) - The client-provided identifier for the spendback transaction.
- **status** (string) - The current status of the spendback transaction (e.g., 'COMPLETED', 'PENDING').
- **amount** (number) - The amount of the spendback transaction.

#### Response Example
```json
{
  "spendback_token": "sb_xyz789",
  "client_spendback_id": "spendback-1678886400000",
  "status": "COMPLETED",
  "amount": 100.00
}
```

#### Error Handling
- **ApiError** - Thrown if the API request fails. The error object contains a `body` with details.

```

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

### GET /payout/user/history

Source: https://github.com/masspayio/masspay-js-sdk/blob/main/README.md

Retrieves the transaction history for all users.

```APIDOC
## GET /payout/user/history

### Description
All Users' Transactions history.

### Method
GET

### Endpoint
/payout/user/history
```

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

### Initiate Spendback Transaction

Source: https://context7.com/masspayio/masspay-js-sdk/llms.txt

Use this to return funds from a user's wallet to a source. Requires a valid user token and idempotency key.

```javascript
import { MasspayJsSdk, ApiError, SpendBackTxn } from 'masspay-js-sdk';

const sdk = new MasspayJsSdk({
  AUTHORIZER_NAME_API_KEY: 'your-api-key',
});

async function processSpendback(userToken: string) {
  const spendback: SpendBackTxn = {
    client_spendback_id: 'spendback-' + Date.now(),
    source_token: 'wallet_token_abc123',
    source_currency_code: 'USD',
    amount: 100.00,
    notes: 'Refund for order #12345'
  };

  try {
    const result = await sdk.SpendBackService.initiateSpendback(
      userToken,
      'idempotency-key-spendback-123',
      spendback
    );

    // Response: SpendBackTxnResp
    // {
    //   spendback_token: "sb_xyz789",
    //   client_spendback_id: "spendback-1234567890",
    //   status: "COMPLETED",
    //   amount: 100.00,
    //   ...
    // }

    console.log(`Spendback completed: ${result.spendback_token}`);
    console.log(`Amount returned: ${result.amount}`);

    return result;
  } catch (error) {
    if (error instanceof ApiError) {
      console.error(`Spendback failed: ${error.body}`);
    }
    throw error;
  }
}
```

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

### GET /payout/user/{user_token}/history

Source: https://github.com/masspayio/masspay-js-sdk/blob/main/README.md

Retrieves the transaction history for a specific user.

```APIDOC
## GET /payout/user/{user_token}/history

### Description
Transactions history.

### Method
GET

### Endpoint
/payout/user/{user_token}/history

### Parameters
#### Path Parameters
- **user_token** (string) - Required - The unique token identifying the user.
```

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

### PayoutService.initiatePayout

Source: https://context7.com/masspayio/masspay-js-sdk/llms.txt

Initiates a payout transaction from your account to a user. Requires the funding source token, destination token, and destination currency. Returns payout details with a payout_token for tracking.

```APIDOC
## POST /payouts

### Description
Initiates a payout transaction from your account to a user.

### Method
POST

### Endpoint
/payouts

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **client_transfer_id** (string) - Required - Unique identifier for the transfer.
- **source_currency_code** (string) - Required - Currency code of the source account (e.g., USD).
- **destination_currency_code** (string) - Required - Currency code of the destination account (e.g., MXN).
- **source_token** (string) - Required - Token representing the funding source.
- **destination_token** (string) - Required - Token representing the payout destination.
- **destination_amount** (integer) - Required - Amount to be sent in the destination currency.
- **attr_set_token** (string) - Required - Token for the attribute set.
- **metadata** (string) - Optional - Additional information about the payout.

### Request Example
```json
{
  "client_transfer_id": "payout-1678886400000",
  "source_currency_code": "USD",
  "destination_currency_code": "MXN",
  "source_token": "source_token_abc123",
  "destination_token": "dest_token_xyz789",
  "destination_amount": 10000,
  "attr_set_token": "attr_set_123",
  "metadata": "Payment for services"
}
```

### Response
#### Success Response (200)
- **payout_token** (string) - Unique token for the initiated payout.
- **client_transfer_id** (string) - The client-provided transfer ID.
- **status** (string) - The current status of the payout (e.g., PENDING).
- **source_amount** (number) - The amount debited from the source account.
- **destination_amount** (integer) - The amount to be received in the destination currency.
- **source_currency_code** (string) - Currency code of the source.
- **destination_currency_code** (string) - Currency code of the destination.
- **exchange_rate** (number) - The exchange rate applied.
- **fee** (number) - The transaction fee.

#### Response Example
```json
{
  "payout_token": "payout_abc123",
  "client_transfer_id": "payout-1678886400000",
  "status": "PENDING",
  "source_amount": 550.00,
  "destination_amount": 10000,
  "source_currency_code": "USD",
  "destination_currency_code": "MXN",
  "exchange_rate": 18.18,
  "fee": 5.00
}
```
```

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

### Initiate User Load Transaction with LoadService

Source: https://context7.com/masspayio/masspay-js-sdk/llms.txt

Adds funds to a user's wallet using a source token and amount. Supports idempotency keys to prevent duplicate processing and optional future scheduling.

```javascript
import { MasspayJsSdk, ApiError, LoadTxn } from 'masspay-js-sdk';

const sdk = new MasspayJsSdk({
  AUTHORIZER_NAME_API_KEY: 'your-api-key',
});

async function fundUserWallet(userToken: string) {
  const loadTransaction: LoadTxn = {
    client_load_id: 'load-' + Date.now(), // Unique ID on your system
    source_token: 'source_token_abc123',   // Funding source
    amount: 500.00,
    source_currency_code: 'USD',
    notes: 'Monthly payment',
    // time_to_process: '2024-02-01T10:00:00Z' // Optional: schedule for future
  };

  try {
    const response = await sdk.LoadService.loadUser(
      userToken,
      loadTransaction,
      'idempotency-key-123' // Prevent duplicate processing
    );

    // Response: LoadTxnResp
    // {
    //   load_token: "load_xyz789",
    //   status: "COMPLETED",
    //   amount: 500.00,
    //   ...
    // }

    console.log(`Load successful: ${response.load_token}`);
    console.log(`Status: ${response.status}`);
    console.log(`Amount loaded: ${response.amount}`);

    return response;
  } catch (error) {
    if (error instanceof ApiError) {
      console.error(`Load failed: ${error.body}`);
    }
    throw error;
  }
}
```

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

### Create a new user with UserService.createUser

Source: https://context7.com/masspayio/masspay-js-sdk/llms.txt

Creates a new user in the MassPay system. Requires specific user fields and returns a StoredUser object.

```javascript
import { MasspayJsSdk, ApiError, User, StoredUser } from 'masspay-js-sdk';

const sdk = new MasspayJsSdk({
  AUTHORIZER_NAME_API_KEY: 'your-api-key',
});

async function createNewUser() {
  const newUser: User = {
    internal_user_id: 'user-12345',
    country: 'USA',
    first_name: 'John',
    last_name: 'Doe',
    email: 'john.doe@example.com',
    address1: '123 Main Street',
    city: 'New York',
    state_province: 'NY',
    postal_code: '10001',
    mobile_number: '+1234567890',
    date_of_birth: '1990-01-15',
    language: 'en',
    notify_user: true,
    metadata: {
      group_id: 100
    }
  };

  try {
    const createdUser: StoredUser = await sdk.UserService.createUser(newUser);

    // Response:
    // {
    //   user_token: "usr_abc123xyz",
    //   status: "ACTIVE",
    //   created_on: "2024-01-15T10:30:00Z",
    //   internal_user_id: "user-12345",
    //   first_name: "John",
    //   last_name: "Doe",
    //   email: "john.doe@example.com",
    //   timezone: "America/New_York",
    //   ...
    // }

    console.log(`User created with token: ${createdUser.user_token}`);
    console.log(`Status: ${createdUser.status}`);

    return createdUser;
  } catch (error) {
    if (error instanceof ApiError) {
      console.error(`Failed to create user: ${error.body}`);
    }
    throw error;
  }
}
```

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

### GET /AccountService/getAccountBalance

Source: https://context7.com/masspayio/masspay-js-sdk/llms.txt

Retrieves the current available balance for the MassPay account across all held currencies.

```APIDOC
## GET /AccountService/getAccountBalance

### Description
Retrieves the current available balance for your MassPay account. Returns an array of balance objects containing token, balance amount, and currency code for each currency held in your account.

### Method
GET

### Response
#### Success Response (200)
- **balances** (Array) - An array of balance objects containing token, balance, and currency_code.

#### Response Example
[
  {
    "token": "balance_token_123",
    "balance": 10000.50,
    "currency_code": "USD"
  },
  {
    "token": "balance_token_456",
    "balance": 5000.00,
    "currency_code": "EUR"
  }
]
```

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

### Create Autopayout Rule with WalletService

Source: https://context7.com/masspayio/masspay-js-sdk/llms.txt

Configures a rule to automatically trigger payouts based on a percentage of incoming funds. Requires a valid user and wallet token.

```javascript
import { MasspayJsSdk, ApiError, AutopayRule } from 'masspay-js-sdk';

const sdk = new MasspayJsSdk({
  AUTHORIZER_NAME_API_KEY: 'your-api-key',
});

async function setupAutoPayout(userToken: string, walletToken: string) {
  const autopayRule: AutopayRule = {
    destination_token: 'dest_token_abc123', // Payout destination
    percentage: 100 // Percentage of incoming funds to autopay
  };

  try {
    const rule = await sdk.WalletService.createAutopayoutRule(
      userToken,
      walletToken,
      autopayRule
    );

    // Response: AutopayoutResp
    // {
    //   token: "autopay_xyz789",
    //   destination_token: "dest_token_abc123",
    //   percentage: 100
    // }

    console.log(`Autopayout rule created: ${rule.token}`);
    console.log(`Will autopay ${rule.percentage}% to ${rule.destination_token}`);

    return rule;
  } catch (error) {
    if (error instanceof ApiError) {
      console.error(`Failed to create autopayout rule: ${error.message}`);
    }
    throw error;
  }
}
```

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

### PayoutService.getPayoutStatus

Source: https://context7.com/masspayio/masspay-js-sdk/llms.txt

Retrieves the current status of a payout transaction. Use force_status_update to get the latest status from the payout destination.

```APIDOC
## GET /payouts/{payout_token}/status

### Description
Retrieves the current status of a payout transaction.

### Method
GET

### Endpoint
/payouts/{payout_token}/status

### Parameters
#### Path Parameters
- **payout_token** (string) - Required - The token of the payout transaction to check.

#### Query Parameters
- **force_status_update** (boolean) - Optional - If true, fetches the latest status from the destination.
- **include_payer_logo** (boolean) - Optional - If true, includes the payer's logo in the response (as base64).

#### Request Body
None

### Request Example
(No request body is sent for this operation)

### Response
#### Success Response (200)
- **payout_token** (string) - The token of the payout.
- **status** (string) - The current status of the payout (e.g., COMPLETED, FAILED).
- **destination_amount** (integer) - The amount in the destination currency.
- **destination_currency_code** (string) - Currency code of the destination.

#### Response Example
```json
{
  "payout_token": "payout_abc123",
  "status": "COMPLETED",
  "destination_amount": 10000,
  "destination_currency_code": "MXN"
}
```
```

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

### CatalogService.getCheapestCountryServices

Source: https://context7.com/masspayio/masspay-js-sdk/llms.txt

Retrieves the cheapest service option from each provider for a specific country to optimize payout costs.

```APIDOC
## CatalogService.getCheapestCountryServices

### Description
Retrieves only the cheapest service option from each provider for a specific country. Useful for optimizing payout costs.

### Parameters
#### Request Body
- **country_code** (string) - Required - ISO 3166-1 alpha-3 country code
- **amount** (string) - Required - Amount to send
```

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

### Get user transaction history with UserService.getUserHistory

Source: https://context7.com/masspayio/masspay-js-sdk/llms.txt

Retrieves transaction history for a specific user, supporting pagination and filtering.

```javascript
import { MasspayJsSdk, ApiError } from 'masspay-js-sdk';

const sdk = new MasspayJsSdk({
  AUTHORIZER_NAME_API_KEY: 'your-api-key',
});

async function getUserTransactionHistory(userToken: string) {
  try {
    const history = await sdk.UserService.getUserHistory(
      userToken,
      '2024-01-01',    // start_date
      '2024-12-31',    // end_date
      'payout',        // type: 'payout' | 'load' | 'spendback'
      undefined,       // wallet_token (optional)
      undefined,       // idempotency_key
      50,              // number_of_records (default: 10)
      1,               // page (default: 1)
      false            // show_all_clients
    );

    // Response: Array of TxnHistoryResp objects
    history.forEach(txn => {
      console.log(`Transaction: ${txn.payout_token}`);
      console.log(`Amount: ${txn.destination_amount} ${txn.destination_currency_code}`);
      console.log(`Status: ${txn.status}`);
    });

    return history;
  } catch (error) {
    if (error instanceof ApiError) {
      console.error(`Error fetching history: ${error.message}`);
    }
    throw error;
  }
}
```

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

### Retrieve User Wallets with WalletService

Source: https://context7.com/masspayio/masspay-js-sdk/llms.txt

Fetches all wallets associated with a specific user token. Returns balance and currency information for each wallet.

```javascript
import { MasspayJsSdk, ApiError } from 'masspay-js-sdk';

const sdk = new MasspayJsSdk({
  AUTHORIZER_NAME_API_KEY: 'your-api-key',
});

async function getUserWallets(userToken: string) {
  try {
    const wallets = await sdk.WalletService.getWallet(userToken);

    // Response: Array of WalletTxnResp
    // [
    //   {
    //     user_token: "usr_abc123",
    //     wallet_token: "wlt_xyz789",
    //     balance: 500.00,
    //     currency_code: "USD",
    //     ...
    //   }
    // ]

    console.log(`User has ${wallets.length} wallet(s)`);
    wallets.forEach(wallet => {
      console.log(`Wallet: ${wallet.wallet_token}`);
      console.log(`Balance: ${wallet.balance} ${wallet.currency_code}`);
    });

    return wallets;
  } catch (error) {
    if (error instanceof ApiError) {
      console.error(`Error: ${error.message}`);
    }
    throw error;
  }
}
```

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

### WalletService.getWallet

Source: https://context7.com/masspayio/masspay-js-sdk/llms.txt

Retrieves all available wallets for a user, including balance information and currency details.

```APIDOC
## WalletService.getWallet

### Description
Retrieves all available wallets for a user. Each wallet contains balance information and currency details.

### Parameters
#### Path Parameters
- **user_token** (string) - Required - The unique identifier for the user.

### Response
#### Success Response (200)
- **user_token** (string) - User identifier
- **wallet_token** (string) - Wallet identifier
- **balance** (number) - Current balance
- **currency_code** (string) - Currency code
```

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

### GET /AccountService/getAccountStatement

Source: https://context7.com/masspayio/masspay-js-sdk/llms.txt

Retrieves a certified PDF ledger statement for a specified date range, returned as a base64-encoded string.

```APIDOC
## GET /AccountService/getAccountStatement

### Description
Retrieves a certified PDF ledger statement for a specified date range. The statement is returned as a base64-encoded string. The date range cannot exceed 31 days.

### Method
GET

### Parameters
#### Query Parameters
- **start_date** (string) - Required - The start date of the statement range (YYYY-MM-DD).
- **ending_date** (string) - Required - The end date of the statement range (YYYY-MM-DD, max 31 days from start).

### Response
#### Success Response (200)
- **content** (string) - A base64-encoded string representing the PDF ledger statement.

#### Response Example
{
  "content": "base64-encoded-pdf-content"
}
```

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

### Initiate a Payout Transaction

Source: https://context7.com/masspayio/masspay-js-sdk/llms.txt

Creates a new payout transaction using funding source and destination tokens. Requires an idempotency key to prevent duplicate requests.

```javascript
import { MasspayJsSdk, ApiError, PayoutTxn } from 'masspay-js-sdk';

const sdk = new MasspayJsSdk({
  AUTHORIZER_NAME_API_KEY: 'your-api-key',
});

async function sendPayout(userToken: string) {
  const payoutRequest: PayoutTxn = {
    client_transfer_id: 'payout-' + Date.now(),
    source_currency_code: 'USD',
    destination_currency_code: 'MXN',
    source_token: 'source_token_abc123',      // Funding source
    destination_token: 'dest_token_xyz789',    // Payout destination
    destination_amount: 10000,                 // Amount in destination currency
    attr_set_token: 'attr_set_123',           // User attributes token
    metadata: 'Payment for services'
  };

  try {
    const payout = await sdk.PayoutService.initiatePayout(
      userToken,
      payoutRequest,
      undefined,              // limit (optional)
      'idempotency-key-456'   // Prevent duplicates
    );

    // Response: PayoutTxnResp or PayoutTxnCommitResp
    // {
    //   payout_token: "payout_abc123",
    //   client_transfer_id: "payout-1234567890",
    //   status: "PENDING",
    //   source_amount: 550.00,
    //   destination_amount: 10000,
    //   source_currency_code: "USD",
    //   destination_currency_code: "MXN",
    //   exchange_rate: 18.18,
    //   fee: 5.00,
    //   ...
    // }

    console.log(`Payout initiated: ${payout.payout_token}`);
    console.log(`Status: ${payout.status}`);
    console.log(`Amount: ${payout.destination_amount} ${payout.destination_currency_code}`);
    console.log(`Fee: ${payout.fee}`);

    return payout;
  } catch (error) {
    if (error instanceof ApiError) {
      console.error(`Payout failed: ${error.body}`);
    }
    throw error;
  }
}
```

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

### WalletService.createAutopayoutRule

Source: https://context7.com/masspayio/masspay-js-sdk/llms.txt

Creates an autopayout rule that automatically initiates a payout whenever the wallet receives funds, based on a specified percentage.

```APIDOC
## POST WalletService.createAutopayoutRule

### Description
Creates an autopayout rule that automatically initiates a payout whenever the wallet receives funds. Specify a percentage of incoming funds to automatically pay out.

### Parameters
#### Request Body
- **destination_token** (string) - Required - Payout destination
- **percentage** (number) - Required - Percentage of incoming funds to autopay

### Request Example
{
  "destination_token": "dest_token_abc123",
  "percentage": 100
}

### Response
#### Success Response (200)
- **token** (string) - Autopayout rule token
- **destination_token** (string) - Payout destination
- **percentage** (number) - Percentage of incoming funds

#### Response Example
{
  "token": "autopay_xyz789",
  "destination_token": "dest_token_abc123",
  "percentage": 100
}
```

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

### LoadService.loadUser

Source: https://context7.com/masspayio/masspay-js-sdk/llms.txt

Initiates a load transaction to add funds to a user's wallet, supporting immediate or scheduled future loads.

```APIDOC
## POST LoadService.loadUser

### Description
Initiates a load transaction to add funds to a user's wallet. Requires a source token and amount. Supports scheduled future loads.

### Parameters
#### Request Body
- **client_load_id** (string) - Required - Unique ID on your system
- **source_token** (string) - Required - Funding source
- **amount** (number) - Required - Amount to load
- **source_currency_code** (string) - Required - Currency code
- **notes** (string) - Optional - Transaction notes
- **time_to_process** (string) - Optional - ISO 8601 date for future scheduling

### Request Example
{
  "client_load_id": "load-1706784000000",
  "source_token": "source_token_abc123",
  "amount": 500.00,
  "source_currency_code": "USD",
  "notes": "Monthly payment"
}

### Response
#### Success Response (200)
- **load_token** (string) - Unique load transaction token
- **status** (string) - Transaction status
- **amount** (number) - Amount loaded

#### Response Example
{
  "load_token": "load_xyz789",
  "status": "COMPLETED",
  "amount": 500.00
}
```

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

### Retrieve W8/W9 Tax Interview Link

Source: https://context7.com/masspayio/masspay-js-sdk/llms.txt

Generates a URL for users to complete tax compliance interviews. Requires a return URL to redirect users after completion.

```javascript
import { MasspayJsSdk, ApiError } from 'masspay-js-sdk';

const sdk = new MasspayJsSdk({
  AUTHORIZER_NAME_API_KEY: 'your-api-key',
});

async function getTaxFormLink(userToken: string) {
  try {
    const result = await sdk.TaxService.getTaxInterviewLink(
      userToken,
      'https://yourapp.com/tax-complete' // Return URL after completion
    );

    // Response: { interview_url: "https://tax-interview.masspay.io/..." }

    console.log('Direct user to complete tax interview:');
    console.log(result.interview_url);

    return result.interview_url;
  } catch (error) {
    if (error instanceof ApiError) {
      console.error(`Error: ${error.message}`);
    }
    throw error;
  }
}
```

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

### Retrieve Country Services with CatalogService

Source: https://context7.com/masspayio/masspay-js-sdk/llms.txt

Lists service providers and their offerings for a specific country. Requires a country code and supports currency conversion parameters.

```javascript
import { MasspayJsSdk, ApiError } from 'masspay-js-sdk';

const sdk = new MasspayJsSdk({
  AUTHORIZER_NAME_API_KEY: 'your-api-key',
});

async function getServicesForCountry(countryCode: string) {
  try {
    const services = await sdk.CatalogService.getCountryServices(
      countryCode,     // country_code (ISO 3166-1 alpha-3)
      undefined,       // limit
      undefined,       // wallet_token
      undefined,       // user_token
      'USD',           // source_currency
      undefined,       // payer_name
      'MXN',           // destination_currency
      undefined,       // idempotency_key
      '500',           // amount (default: '200')
      true             // include_payer_logos (base64)
    );

    // Response: CompaniesResp with companies and their services
    console.log(`Found ${services.companies?.length} service providers`);

    services.companies?.forEach(company => {
      console.log(`\nProvider: ${company.name}`);
      company.services?.forEach(service => {
        console.log(`  - ${service.name}: Fee ${service.fee}, Rate ${service.exchange_rate}`);
      });
    });

    return services;
  } catch (error) {
    if (error instanceof ApiError) {
      console.error(`Error: ${error.message}`);
    }
    throw error;
  }
}

// Get services available in Mexico
getServicesForCountry('MEX');
```

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

### Create Business Subaccount

Source: https://context7.com/masspayio/masspay-js-sdk/llms.txt

Registers a new subaccount for managing distinct business entities. Returns a subaccount token and API key.

```javascript
import { MasspayJsSdk, ApiError, CreateSubaccountTxn } from 'masspay-js-sdk';

const sdk = new MasspayJsSdk({
  AUTHORIZER_NAME_API_KEY: 'your-api-key',
});

async function createBusinessSubaccount() {
  const subaccount: CreateSubaccountTxn = {
    company_name: 'Acme Corporation',
    company_dba: 'Acme Corp',
    incorporation_date: '2020-01-15',
    incorporation_country: 'USA',
    incorporation_state: 'DE',
    business_type: 'LLC',
    tax_id: '12-3456789',
    address1: '100 Business Ave',
    city: 'Wilmington',
    state_province: 'DE',
    postal_code: '19801',
    country: 'USA'
  };

  try {
    const result = await sdk.SubaccountService.createSubaccount(subaccount);

    // Response:
    // {
    //   subaccount_token: "sub_abc123xyz",
    //   api_key: "sk_live_xxx..."
    // }

    console.log(`Subaccount created: ${result.subaccount_token}`);
    console.log(`API Key: ${result.api_key}`);

    return result;
  } catch (error) {
    if (error instanceof ApiError) {
      console.error(`Error: ${error.message}`);
    }
    throw error;
  }
}
```

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

### UserService.createUser

Source: https://context7.com/masspayio/masspay-js-sdk/llms.txt

Creates a new user in the MassPay system. Required fields include internal_user_id, country, first_name, last_name, and email. Returns a StoredUser object with the generated user_token.

```APIDOC
## POST /users

### Description
Creates a new user in the MassPay system.

### Method
POST

### Endpoint
/users

### Parameters
#### Request Body
- **internal_user_id** (string) - Required - Unique identifier for the user within your system.
- **country** (string) - Required - The user's country code (e.g., 'USA').
- **first_name** (string) - Required - The user's first name.
- **last_name** (string) - Required - The user's last name.
- **email** (string) - Required - The user's email address.
- **address1** (string) - Optional - The user's primary address line.
- **city** (string) - Optional - The user's city.
- **state_province** (string) - Optional - The user's state or province.
- **postal_code** (string) - Optional - The user's postal code.
- **mobile_number** (string) - Optional - The user's mobile phone number.
- **date_of_birth** (string) - Optional - The user's date of birth in YYYY-MM-DD format.
- **language** (string) - Optional - The user's preferred language code (e.g., 'en').
- **notify_user** (boolean) - Optional - Whether to notify the user upon creation.
- **metadata** (object) - Optional - Custom key-value pairs for additional user information.

### Request Example
```json
{
  "internal_user_id": "user-12345",
  "country": "USA",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "address1": "123 Main Street",
  "city": "New York",
  "state_province": "NY",
  "postal_code": "10001",
  "mobile_number": "+1234567890",
  "date_of_birth": "1990-01-15",
  "language": "en",
  "notify_user": true,
  "metadata": {
    "group_id": 100
  }
}
```

### Response
#### Success Response (200)
- **user_token** (string) - The unique token for the created user.
- **status** (string) - The current status of the user (e.g., 'ACTIVE').
- **created_on** (string) - The timestamp when the user was created.
- **internal_user_id** (string) - The internal user ID provided.
- **first_name** (string) - The user's first name.
- **last_name** (string) - The user's last name.
- **email** (string) - The user's email address.
- **timezone** (string) - The user's timezone.

#### Response Example
```json
{
  "user_token": "usr_abc123xyz",
  "status": "ACTIVE",
  "created_on": "2024-01-15T10:30:00Z",
  "internal_user_id": "user-12345",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "timezone": "America/New_York"
}
```
```

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

### Initiate KYC Verification Sessions

Source: https://context7.com/masspayio/masspay-js-sdk/llms.txt

Retrieves session URLs for Veriff or Au10tix identity verification services to redirect users.

```javascript
import { MasspayJsSdk, ApiError } from 'masspay-js-sdk';

const sdk = new MasspayJsSdk({
  AUTHORIZER_NAME_API_KEY: 'your-api-key',
});

async function initiateKycVerification(userToken: string) {
  try {
    const session = await sdk.KycService.getUserUserTokenKycVeriff(userToken);

    // Response: { session_url: "https://veriff.com/session/abc123..." }

    console.log('Redirect user to KYC verification:');
    console.log(session.session_url);

    // You can use this URL with Veriff SDKs or redirect the user
    return session.session_url;
  } catch (error) {
    if (error instanceof ApiError) {
      console.error(`KYC initialization failed: ${error.message}`);
    }
    throw error;
  }
}

// Alternative: Get Au10tix session
async function initiateAu10tixKyc(userToken: string) {
  try {
    const session = await sdk.KycService.getUserUserTokenKycAu10Tix(userToken);
    console.log('Au10tix session URL:', session.session_url);
    return session.session_url;
  } catch (error) {
    throw error;
  }
}
```

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

### CatalogService.getCountryServices

Source: https://context7.com/masspayio/masspay-js-sdk/llms.txt

Retrieves a list of companies and their service offerings for a specific country, including pricing based on a specified amount.

```APIDOC
## CatalogService.getCountryServices

### Description
Retrieves a list of companies and their service offerings for a specific country. Includes pricing information based on the specified amount.

### Parameters
#### Request Body
- **country_code** (string) - Required - ISO 3166-1 alpha-3 country code
- **limit** (number) - Optional - Result limit
- **wallet_token** (string) - Optional - Wallet identifier
- **user_token** (string) - Optional - User identifier
- **source_currency** (string) - Optional - Currency to send from
- **payer_name** (string) - Optional - Payer name
- **destination_currency** (string) - Optional - Currency to receive
- **idempotency_key** (string) - Optional - Unique key for request
- **amount** (string) - Optional - Amount to transfer
- **include_payer_logos** (boolean) - Optional - Include base64 logos
```

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

### PayoutService.commitPayoutTxn

Source: https://context7.com/masspayio/masspay-js-sdk/llms.txt

Commits a previously created payout transaction. Use this after initiatePayout to finalize and execute the payout.

```APIDOC
## POST /payouts/{payout_token}/commit

### Description
Commits a previously created payout transaction to finalize and execute it.

### Method
POST

### Endpoint
/payouts/{payout_token}/commit

### Parameters
#### Path Parameters
- **payout_token** (string) - Required - The token of the payout transaction to commit.

#### Query Parameters
None

#### Request Body
None

### Request Example
(No request body is sent for this operation)

### Response
#### Success Response (200)
- **payout_token** (string) - The token of the committed payout.
- **payout_status** (string) - The status of the payout after commitment (e.g., COMMITTED).
- **pickup_code** (string) - Optional - A code for picking up the payout if applicable.
- **errors** (array) - A list of errors encountered during commitment.

#### Response Example
```json
{
  "payout_token": "payout_abc123",
  "payout_status": "COMMITTED",
  "pickup_code": "1234567890",
  "errors": []
}
```
```

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

### Retrieve User Tax Reports

Source: https://context7.com/masspayio/masspay-js-sdk/llms.txt

Fetches annual balances for tax reporting, supporting filtering by amount threshold and tax year.

```javascript
import { MasspayJsSdk, ApiError } from 'masspay-js-sdk';

const sdk = new MasspayJsSdk({
  AUTHORIZER_NAME_API_KEY: 'your-api-key',
});

async function getTaxReport(taxYear: number = 2023) {
  try {
    const taxUsers = await sdk.TaxService.getTaxUsers(
      600,      // amount_threshold: Only show users with balance > $600
      taxYear   // tax_year: defaults to previous year if not specified
    );

    // Response: Array of TaxYearUserResp
    console.log(`Tax report for ${taxYear}:`);
    console.log(`Users meeting threshold: ${taxUsers.length}`);

    taxUsers.forEach(user => {
      console.log(`User: ${user.user_token}`);
      console.log(`  Total: ${user.total_amount}`);
    });

    return taxUsers;
  } catch (error) {
    if (error instanceof ApiError) {
      console.error(`Error: ${error.message}`);
    }
    throw error;
  }
}
```

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

### Store User Attributes with AttributeService

Source: https://context7.com/masspayio/masspay-js-sdk/llms.txt

Associates user attributes with a specific payout destination token and currency. Requires an idempotency key for safe retries.

```javascript
import { MasspayJsSdk, ApiError, AttrTxn } from 'masspay-js-sdk';

const sdk = new MasspayJsSdk({
  AUTHORIZER_NAME_API_KEY: 'your-api-key',
});

async function storeUserAttributes(
  userToken: string,
  destinationToken: string,
  currency: string
) {
  const attributes: AttrTxn = {
    values: [
      { token: 'bank_account_number', value: '1234567890' },
      { token: 'bank_routing_number', value: '021000021' },
      { token: 'account_holder_name', value: 'John Doe' }
    ]
  };

  try {
    const result = await sdk.AttributeService.storeAttrs(
      userToken,
      destinationToken,
      currency,       // ISO 4217 currency code (e.g., 'MXN')
      attributes,
      'idempotency-key-attr-123'
    );

    // Response: { attr_set_token: "attr_set_abc123" }

    console.log(`Attributes stored with token: ${result.attr_set_token}`);
    return result;
  } catch (error) {
    if (error instanceof ApiError) {
      console.error(`Failed to store attributes: ${error.body}`);
    }
    throw error;
  }
}
```

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

### Retrieve user profile with UserService.getUserByToken

Source: https://context7.com/masspayio/masspay-js-sdk/llms.txt

Retrieves a user's profile by their user token. Supports optional idempotency keys.

```javascript
import { MasspayJsSdk, ApiError, StoredUser } from 'masspay-js-sdk';

const sdk = new MasspayJsSdk({
  AUTHORIZER_NAME_API_KEY: 'your-api-key',
});

async function getUserProfile(userToken: string) {
  try {
    const user: StoredUser = await sdk.UserService.getUserByToken(
      userToken,
      'unique-idempotency-key-123' // Optional idempotency key
    );

    console.log(`User: ${user.first_name} ${user.last_name}`);
    console.log(`Email: ${user.email}`);
    console.log(`Status: ${user.status}`);
    console.log(`Created: ${user.created_on}`);

    return user;
  } catch (error) {
    if (error instanceof ApiError && error.status === 404) {
      console.error('User not found');
    }
    throw error;
  }
}

// Usage
getUserProfile('usr_abc123xyz');
```

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

### User Service API

Source: https://github.com/masspayio/masspay-js-sdk/blob/main/README.md

Endpoints for managing user accounts.

```APIDOC
## POST /payout/user

### Description
Create a new user account.

### Method
POST

### Endpoint
/payout/user
```

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

### Retrieve User Load History with LoadService

Source: https://context7.com/masspayio/masspay-js-sdk/llms.txt

Fetches all historical and scheduled load transactions associated with a specific user token.

```javascript
import { MasspayJsSdk, ApiError } from 'masspay-js-sdk';

const sdk = new MasspayJsSdk({
  AUTHORIZER_NAME_API_KEY: 'your-api-key',
});

async function getLoadHistory(userToken: string) {
  try {
    const loads = await sdk.LoadService.getUserLoadsByToken(userToken);

    // Response: Array of Loads
    console.log(`Total loads: ${loads.length}`);

    loads.forEach(load => {
      console.log(`Load: ${load.load_token}`);
      console.log(`  Amount: ${load.amount}`);
      console.log(`  Status: ${load.status}`);
      console.log(`  Date: ${load.time_of_load}`);
    });

    return loads;
  } catch (error) {
    if (error instanceof ApiError) {
      console.error(`Error: ${error.message}`);
    }
    throw error;
  }
}
```

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

### Lookup user with UserService.userLookup

Source: https://context7.com/masspayio/masspay-js-sdk/llms.txt

Looks up an existing user by email, first name, or internal user ID.

```javascript
import { MasspayJsSdk, ApiError } from 'masspay-js-sdk';

const sdk = new MasspayJsSdk({
  AUTHORIZER_NAME_API_KEY: 'your-api-key',
});

async function findExistingUser() {
  try {
    const foundUser = await sdk.UserService.userLookup(
      'john.doe@example.com', // email
      'John',                  // first_name
      'user-12345'            // internal_user_id
    );

    // Response:
    // {
    //   user_token: "usr_abc123xyz",
    //   first_name: "John",
    //   last_name: "Doe",
    //   internal_user_id: "user-12345"
    // }

    console.log(`Found user: ${foundUser.user_token}`);
    return foundUser;
  } catch (error) {
    if (error instanceof ApiError && error.status === 404) {
      console.log('No matching user found');
      return null;
    }
    throw error;
  }
}
```