SDK

Both SDKs are auto-generated from the HexPay OpenAPI spec and provide full type safety.

Installation

pip install hexpay

Pin to a specific version for production:

pip install "hexpay==X.Y.Z"

npm install @hexpay/sdk
# or
pnpm add @hexpay/sdk
# or
yarn add @hexpay/sdk

Pin to a specific version for production:

npm install @hexpay/[email protected]

Requires Node.js ≥ 18. Ships dual ESM + CommonJS with TypeScript types included.

Quickstart

import os
import uuid

from hexpay import AuthenticatedClient
from hexpay.api.payments import create_payment
from hexpay.models import CreatePaymentRequest

client = AuthenticatedClient(
    base_url="https://api.hexpay.io",
    token=os.environ["HEXPAY_TOKEN"],
)

payment = create_payment.sync(
    client=client,
    body=CreatePaymentRequest(amount="100.00", currency="USD"),
    x_idempotency_key=str(uuid.uuid4()),
)

print(payment.id, payment.checkout_url)

import { randomUUID } from 'node:crypto';
import { createPayment } from '@hexpay/sdk';
import { client } from '@hexpay/sdk/client';

client.setConfig({
  auth: () => process.env.HEXPAY_TOKEN!,
});

const { data, error } = await createPayment({
  body: {
    amount: '100.00',
    currency: 'USD',
    order_id: 'order-2026-00123',
  },
  headers: {
    'X-Idempotency-Key': randomUUID(),
  },
});

if (error) {
  console.error('Payment creation failed:', error);
  process.exit(1);
}

console.log('Created payment', data.id, '→', data.checkoutURL);

POST requests (createPayment, cancelPayment) accept an optional X-Idempotency-Key header with a UUID v4. The server deduplicates requests within a 24-hour window — a transient network failure cannot turn a retry into a duplicate payment.

We strongly recommend always sending an idempotency key. Without it, a network timeout on a payment creation leaves you unable to tell whether the payment was created or not — and retrying blindly may charge the customer twice.

Two rules:

Generate a fresh key for each new logical operation.
Reuse the same key when retrying a failed request. Generating a new UUID inside a retry loop defeats the purpose entirely.

import uuid

idempotency_key = str(uuid.uuid4())  # generate once, before any retry loop

payment = create_payment.sync(
    client=client,
    body=CreatePaymentRequest(amount="100.00", currency="USD"),
    x_idempotency_key=idempotency_key,
)

import { randomUUID } from 'node:crypto';

const idempotencyKey = randomUUID(); // generate once, before any retry loop

const { data, error } = await createPayment({
  body: { amount: '100.00', currency: 'USD' },
  headers: { 'X-Idempotency-Key': idempotencyKey },
});

Async

Every endpoint has both sync and asyncio entry points:

import asyncio
from hexpay.api.payments import list_payments

async def main():
    page = await list_payments.asyncio(client=client, limit=20)
    for p in page.payments:
        print(p.id, p.status)

asyncio.run(main())

Every SDK function returns a Promise<{ data, error, response }>. Always check error before using data:

import { getPayment } from '@hexpay/sdk';

const { data, error, response } = await getPayment({
  path: { paymentID: 'abc-123' },
});

if (error) {
  console.error(response.status, error);
  return;
}

console.log(data.status);

Available Operations

Operation	Description
`createPayment`	Create a new payment (customer-choice or preselected method)
`getPayment`	Fetch full payment details by ID
`getPaymentStatus`	Lightweight status check
`listPayments`	Paginate through payments with cursor-based pagination
`cancelPayment`	Cancel a payment in `created` or `pending` status
`listPaymentMethods`	List all coin/chain combinations enabled for the store

For request parameters and response schemas, see the API Reference.

SDK

hexpay on PyPI

@hexpay/sdk on npm

Installation

Quickstart

Authentication

Idempotency

Async

Available Operations

On this page