@100pay-hq/100pay.js

100Pay SDK

A TypeScript library for integrating with the 100Pay payment platform, enabling developers to easily accept cryptocurrency payments and manage transactions.

Features

• ✅ Verify cryptocurrency payments
• ✅ Create and manage subaccounts
• ✅ Preview currency conversions
• ✅ Make authenticated API requests
• ✅ Full TypeScript support with comprehensive typing
• ✅ Secure server-to-server communication with request signing

Installation

npm install @100pay-hq/100pay.js

Or using yarn:

yarn add @100pay-hq/100pay.js

Quick Start

import { Pay100 } from '@100pay-hq/100pay.js';

// Initialize the 100Pay client
const client = new Pay100({
  publicKey: 'your_public_key',
  secretKey: 'your_secret_key' // Required for server-side operations
});

// Verify a transaction
async function verifyTransaction(transactionId) {
  try {
    const result = await client.verify(transactionId);
    
    if (result.status === 'success') {
      console.log('Transaction verified:', result.data);
      return result.data;
    } else {
      console.error('Verification failed:', result.message);
      return null;
    }
  } catch (error) {
    console.error('Error:', error.message);
    throw error;
  }
}

API Reference

Initialization

const client = new Pay100({
  publicKey: string,  // Your 100Pay public API key (required)
  secretKey?: string, // Your 100Pay secret API key (required for server-side operations)
  baseUrl?: string    // Optional custom API base URL (defaults to https://api.100pay.co)
});

Transaction Verification

// Verify a crypto payment transaction
const result = await client.verify(transactionId);

Parameters:

Parameter	Type	Description
transactionId	string	The unique ID of the transaction to verify

Returns:

interface IVerifyResponse {
  status: "success" | "error";
  data: ITransactionData | Record<string, never>;
  message?: string;
}

Example:

try {
  const result = await client.verify("tx_123456789");
  
  if (result.status === 'success') {
    // Payment is valid
    const { amount, currency, status } = result.data;
    // Process order fulfillment
  } else {
    // Payment verification failed
    console.error(result.message);
  }
} catch (error) {
  // Handle verification error
  if (error instanceof PaymentVerificationError) {
    console.error(`Payment verification failed: ${error.message}`);
  }
}

Subaccounts

Subaccounts allow you to create and manage separate accounts under your main account.

// Create a subaccount
const subaccount = await client.subaccounts.create({
  symbols: ["BTC", "ETH", "USDT"],
  networks: ["ETHEREUM", "BSC"],
  owner: {
    name: "Partner Store",
    email: "[e-mail]",
    phone: "[phone]"
  },
  metadata: {
    storeId: "store-123",
    region: "US"
  }
});

Parameters:

interface CreateSubAccountData {
  symbols: string[];            // List of supported cryptocurrencies
  networks: string[];           // List of supported blockchain networks
  owner: {
    name: string;               // Owner's name
    email: string;              // Owner's email
    phone: string;              // Owner's phone number
  };
  metadata: Record<string, unknown>; // Custom metadata for the subaccount
}

Returns:

interface CreateSubAccountResponse {
  message: string;
  accounts: Account[];
}

interface Account {
  balance: {
    available: number | null;
    locked: number | null;
  };
  accountType: string;         // e.g. "subaccount"
  walletType: string;          // e.g. "crypto"
  status: string;              // e.g. "active"
  _id: string;
  name: string;                // e.g. "Tether USDT"
  symbol: string;              // e.g. "USDT"
  decimals: string;            // e.g. "18"
  account: AccountDetails;
  contractAddress: string;
  logo: string;
  userId: string;
  appId: string;
  network: string;
  ownerId: string;
  parentWallet: string;
  __v: number;
}

interface AccountDetails {
  address: string;
  key: Key;
  network: string;
}

interface Key {
  version: number;
  id: string;
  address: string;
  crypto: Crypto;
}

interface Crypto {
  ciphertext: string;
  cipherparams: {
    iv: string;
  };
  cipher: string;
  kdf: string;
  kdfparams: {
    dklen: number;
    salt: string;
    n: number;
    r: number;
    p: number;
  };
  mac: string;
}

Example:

try {
  const result = await client.subaccounts.create({
    symbols: ["USDT", "BTC"], 
    networks: ["ETHEREUM"],
    owner: {
      name: "Merchant Store",
      email: "[e-mail]",
      phone: "[phone]"
    },
    metadata: {
      businessType: "ecommerce"
    }
  });
  
  console.log(`Created ${result.accounts.length} accounts for the subaccount`);
  // Store wallet addresses for each account
  result.accounts.forEach(account => {
    console.log(`${account.symbol} wallet: ${account.account.address}`);
  });
} catch (error) {
  console.error(`Failed to create subaccount: ${error.message}`);
}

Currency Conversion

Preview currency conversion rates and fees:

// Preview a currency conversion
const conversion = await client.conversion.preview({
  amount: 100,
  fromSymbol: "BTC",
  toSymbol: "USDT",
  appId: "your_app_id" // Optional
});

Parameters:

interface CurrencyConversionPayload {
  amount: number;      // Amount to convert
  fromSymbol: string;  // Source currency symbol
  toSymbol: string;    // Target currency symbol
  appId?: string;      // Optional application ID
}

Returns:

interface CurrencyConversionResult {
  convertedAmount: number;              // Final amount after conversion
  totalAmount: number;                  // Total amount including fees
  feeInUSD: number;                     // Fee amount in USD
  feeInToCurrency: number;              // Fee amount in target currency
  feeInfromSymbol: number;              // Fee amount in source currency
  conversionFeeInUSD: number;           // Conversion fee in USD
  conversionFeeInToCurrency: number;    // Conversion fee in target currency
  conversionFeeInfromSymbol: number;    // Conversion fee in source currency
  fromRate: number;                     // Exchange rate for source currency
  toRate: number;                       // Exchange rate for target currency
  intermediateUSDAmount: number;        // Intermediate amount in USD
}

Example:

try {
  const preview = await client.conversion.preview({
    amount: 0.5,
    fromSymbol: "BTC",
    toSymbol: "USDT"
  });
  
  console.log(`Converting 0.5 BTC to USDT:`);
  console.log(`You will receive: ${preview.convertedAmount} USDT`);
  console.log(`Exchange rate: 1 BTC = ${preview.toRate / preview.fromRate} USDT`);
  console.log(`Total fees: ${preview.feeInUSD} USD (${preview.feeInfromSymbol} BTC)`);
} catch (error) {
  console.error(`Conversion preview failed: ${error.message}`);
}

Generic API Requests

The SDK provides a generic request method for making any API call to the 100Pay API:

const response = await client.request<ResponseType>(
  method,   // 'GET', 'POST', 'PUT', or 'DELETE'
  endpoint, // API endpoint path
  data      // Request payload
);

Example:

// Get user balance
const balance = await client.request<BalanceResponse>(
  'GET',
  '/api/v1/user/balance'
);

Error Handling

The SDK provides typed error handling:

try {
  const result = await client.verify(transactionId);
  // Process result
} catch (error) {
  if (error instanceof PaymentVerificationError) {
    // Handle payment verification specific error
    console.error(`Payment verification failed: ${error.message}`);
  } else if (error instanceof Error) {
    // Handle general error
    console.error(`API error: ${error.message}`);
  }
}

Security and Authentication

This SDK implements secure authentication with 100Pay using API keys and request signing for server-to-server communications:

• Each request is signed with HMAC SHA-256 using your secret key
• Signatures include a timestamp to prevent replay attacks
• All requests include your public API key for identification

Client-side operations can use public key only, while server-side operations require both public and secret keys.

TypeScript Support

This package is built with TypeScript and includes full type definitions. The main types are exported for your convenience:

import { 
  Pay100, 
  PaymentVerificationError, 
  CreateSubAccountData,
  CurrencyConversionPayload,
  CurrencyConversionResult,
  Account,
  AccountDetails
} from '@100pay-hq/100pay.js';

Common Use Cases

Accepting Cryptocurrency Payments

• Initialize the SDK with your API keys
• When a payment is received, use the verify method to confirm the transaction
• Process the order or service based on the verification result

Creating Subaccounts for Partners or Marketplaces

const subaccount = await client.subaccounts.create({
  symbols: ["BTC", "ETH", "USDT"],
  networks: ["ETHEREUM"],
  owner: {
    name: "Partner Name",
    email: "[e-mail]",
    phone: "[phone]"
  },
  metadata: {
    partnerId: "partner-123"
  }
});

// Save the subaccount information for future use
console.log(`Created subaccount with ${subaccount.accounts.length} wallets`);
subaccount.accounts.forEach(account => {
  console.log(`${account.symbol} wallet: ${account.account.address}`);
});

Currency Conversion Preview

// Get conversion rates before executing a trade
const preview = await client.conversion.preview({
  amount: 1000,
  fromSymbol: "USDT",
  toSymbol: "BTC"
});

// Show user the conversion details
console.log(`You will receive approximately ${preview.convertedAmount} BTC`);
console.log(`Exchange rate: 1 USDT = ${preview.toRate / preview.fromRate} BTC`);
console.log(`Fee: ${preview.feeInfromSymbol} USDT (${preview.feeInUSD} USD)`);

Resources

• 100Pay Platform
• 100Developers Portal - Get your API keys here
• API Documentation

Development

Building from Source

# Clone the repository
git clone https://github.com/shop100global/100pay.js.git
cd 100pay.js

# Install dependencies
npm install

# Build the project
npm run build

Available Scripts

• npm run build - Build the TypeScript code
• npm run build:clean - Clean the dist directory and build
• npm run test - Run tests
• npm run lint - Lint the code
• npm run lint:fix - Lint and fix code

License

MIT License