HandyPay Ecommerce Payments API

Public REST API for integrating HandyPay payments into any application. Authenticate with API keys, manage products, customers, payment sessions, subscriptions, and receive webhook notifications.

Base URL

https://api.handypay.me/api/v1

javascript

API version: 2025-01-01 — returned in the X-API-Version header on every response.

Quick Start

Get up and running in under a minute. Grab an API key, set up the client, make a request.

Get your API key

Generate keys from the Merchant Portal. All requests require a Bearer token in the Authorization header.

Authorization: Bearer hp_live_your_api_key_here

javascript

hp_test_Sandbox

hp_live_Production

Set up the API client

Create a reusable helper. Works in Next.js, React Native, and Node.js.

lib/handypay.ts

const HANDYPAY_API_URL = "https://api.handypay.me/api/v1";
const HANDYPAY_API_KEY = process.env.HANDYPAY_API_KEY!;

async function handypay<T = any>(
  endpoint: string,
  options: RequestInit = {}
): Promise<T> {
  const res = await fetch(`${HANDYPAY_API_URL}${endpoint}`, {
    ...options,
    headers: {
      Authorization: `Bearer ${HANDYPAY_API_KEY}`,
      "Content-Type": "application/json",
      ...options.headers,
    },
  });

  const json = await res.json();

  if (!json.success) {
    throw new Error(`[${json.error.code}] ${json.error.message}`);
  }

  return json.data;
}

export { handypay };

javascript

Store your key in .env as HANDYPAY_API_KEY. Never expose it client-side.

Make your first request

List your products to verify everything works.

TypeScript

const products = await handypay("/products?limit=10");
console.log(products);

javascript

cURL equivalent

cURL

curl https://api.handypay.me/api/v1/products \
  -H "Authorization: Bearer hp_test_your_api_key_here"

javascript

You should get back a JSON response with "success": true and your product data.

Rate Limits

1,000 requests per hour per API key. Exceeding the limit returns 429 with a Retry-After header.

What You Can Build

One-Time Payments

Create products and hosted checkout sessions for single purchases.

Subscriptions

Recurring billing with flexible intervals, trials, and cancellation.

Multi-Currency

Accept USD, JMD, CAD, and more across 17 countries.

Webhooks

Real-time event notifications for payment and subscription lifecycle.

Billing Intervals

Subscription products support the following recurring billing intervals.

weeklybi-weeklymonthlybi-monthlyquarterlysemi-annualannual

Next Steps

Dive into the full API reference for endpoint details, or jump straight to integration recipes for Next.js, React Native, and Express.