@internal-labs/hoodpay

Lightweight TypeScript SDK for the HoodPay API (customers, payments).

Installation

npm install @internal-labs/hoodpay

or

pnpm add @internal-labs/hoodpay

Setup

Before using the SDK, you'll need to obtain your Business ID and generate an API key from your HoodPay account.

1. Log in to your HoodPay account
2. Navigate to Settings > Developer
3. Copy your Business ID and generate a new API key, then copy it securely

⚠️ Important: Keep your API key secure and never commit it to version control.

Usage

import { HoodPayClient } from '@internal-labs/hoodpay';

const client = new HoodPayClient({
  apiKey: 'your-api-key-here',
  businessId: 'your-business-id-here',
});

// Create a payment
const payment = await client.payments.create({
  amount: 5,
  currency: 'USD',
  name: 'Subscription Test',
});

console.log(payment);

// List payments with pagination
const payments = await client.payments.list({
  searchString: 'test',
  pageSize: 10,
  pageNumber: 1,
});

console.log(payments);

// Get a single payment
const singlePayment = await client.payments.get('payment-id');
console.log(singlePayment);

// List customers
const customers = await client.customers.list({
  searchString: '[email protected]',
  pageSize: 10,
  pageNumber: 1,
});

console.log(customers);

// Get a single customer
const customer = await client.customers.get(123);
console.log(customer);

// Search for customers and payments
const searchResults = await client.search('alice');
console.log(searchResults);

// Select payment method (public endpoint, no auth required)
const selectResult = await client.livePayments.selectPaymentMethod('payment-id', 'ETHEREUM');
console.log(selectResult);

// Fill customer email (public endpoint)
const emailResult = await client.livePayments.fillCustomerEmail(
  'payment-id',
  '[email protected]',
);
console.log(emailResult);

// Cancel payment (public endpoint)
const cancelResult = await client.livePayments.cancelPayment('payment-id');
console.log(cancelResult);

API Reference

HoodPayClient

Main client class for interacting with the HoodPay API.

Constructor Options

• apiKey (string): Your HoodPay API key
• baseUrl (string, optional): API base URL (defaults to production)
• businessId (string): Your business ID

Payments

create(data: CreatePaymentRequest): Promise

Creates a new payment.

Parameters:

• data: Payment creation data
  • paymentMethods (optional): Object specifying allowed payment methods. If not provided, all available payment methods will be used.

list(options?: { searchString?: string; pageSize?: number; pageNumber?: number }): Promise

Lists payments with optional search and pagination.

Parameters:

• options.searchString: Search string for filtering
• options.pageSize: Number of payments per page
• options.pageNumber: Page number

get(paymentId: string): Promise

Gets a single payment by ID.

Parameters:

• paymentId: Payment ID

Customers

list(options?: { searchString?: string; pageSize?: number; pageNumber?: number }): Promise

Lists customers with optional search and pagination.

Parameters:

• options.searchString: Search string for filtering
• options.pageSize: Number of customers per page
• options.pageNumber: Page number

search(query: string): Promise

Searches for customers and payments matching the provided query string.

Parameters:

• query: Search query string

Returns a SearchResponse containing matching customers and payments.

Live Payments

selectPaymentMethod(paymentId: string, crypto: CryptoCode): Promise

Selects a payment method for a hosted payment page. Automatically detects whether to use XPUB (for LITECOIN/BITCOIN) or direct crypto submission.

Parameters:

• paymentId: Payment ID from the hosted page
• crypto: Crypto code (automatically handled for XPUB vs direct)

Returns a SelectPaymentMethodResponse with charge details.

fillCustomerEmail(paymentId: string, email: string): Promise<{ message: string }>

Fills the customer email for a hosted payment page.

Parameters:

• paymentId: Payment ID from the hosted page
• email: Customer email address

Returns a response with a success message.

cancelPayment(paymentId: string): Promise<{ message: string }>

Cancels a payment on the hosted page.

Parameters:

• paymentId: Payment ID from the hosted page

Returns a response with a success message.

Types

CreatePaymentRequest

• description?: string - Optional description of the payment
• amount: number - The amount of the payment
• currency: string - The currency code for the payment (ISO 4217 format, e.g. USD)
• name: string - The name associated with the payment
• redirectUrl?: string - Optional URL to redirect after payment
• notifyUrl?: string - Optional URL for payment notifications
• customerEmail?: string - Optional email of the customer
• customerIp?: string | null - Optional IP address of the customer
• customerUserAgent?: string | null - Optional user agent of the customer

Payment

• id: string - Payment ID
• name?: string - Optional name
• description?: string - Optional description
• endAmount: number - Payment amount
• prePaymentAmount?: number - Pre-payment amount
• currency: string - Currency code
• status: string - Payment status
• createdAt: string - Creation timestamp
• expiresAt?: string - Optional expiration timestamp
• timeline?: TimelineEntry[] - Optional status timeline
• customer?: Customer - Optional customer info
• paymentMethod?: string - Optional payment method
• selectedPaymentMethod?: string - Optional selected payment method
• directCryptoCharge?: HoodPayCryptoCharge - Optional crypto charge details
• hoodPayFee?: number - Optional fee
• onBehalfOfBusinessId?: number - Optional business ID
• netAmountUsd?: number - Optional net amount in USD
• customerEmail?: string - Optional customer email

CustomerStat

• id: number - Customer ID
• email: string - Customer email
• totalPayments: number - Total payments
• totalSpend: number - Total spend
• firstSeen: string - First seen timestamp
• lastPayment?: string - Optional last payment timestamp

SearchResult

• customers: SearchCustomer[] - Matching customers
• payments: Payment[] - Matching payments

SelectPaymentMethodResponse

• data.chargeId: string - Charge ID
• data.chargeCryptoAmount: string - Crypto amount to pay
• data.chargeCryptoName: string - Crypto name
• data.chargeCryptoAddress: string - Crypto address to send to
• message: string - Response message

Supported Crypto Codes

The following crypto codes are supported in paymentMethods.hoodPayCrypto:

• BITCOIN
• ETHEREUM
• LITECOIN
• BITCOIN_CASH
• ETH_USD_COIN
• ETH_TETHER
• MONERO
• ETH_BNB
• ETH_BUSD
• ETH_MATIC
• ETH_SHIBA_INU
• ETH_APE_COIN
• ETH_CRONOS
• ETH_DAI
• ETH_UNISWAP

Development

# Install dependencies
pnpm install

# Build
pnpm run build

# Run example
pnpm run example

# Lint
pnpm run lint

# Format
pnpm run format

Contributing

Contributions are welcome. Please open an issue or submit a pull request.

License

MIT