oxapay-sdk

TypeScript SDK for the OxaPay merchant API. It wraps REST calls with typed requests and responses, consistent error types, and ESM-first exports.

Requirements

• Node.js 18 or newer (uses the global fetch API)
• TypeScript 5.x recommended when consuming from TS projects

Installation

npm install oxapay-sdk

The package is ESM-only ("type": "module"). Use import syntax in your application.

Quick start

import { Oxapay } from "oxapay-sdk";

const oxapay = new Oxapay({
  merchantApiKey: process.env.OXAPAY_MERCHANT_API_KEY!,
});

const invoice = await oxapay.payment.generateInvoice({
  amount: 49.99,
  currency: "USD",
  orderId: "shop-order-123",
  description: "Cart checkout",
});

console.log(invoice.data.paymentUrl);
console.log(invoice.data.trackId);

Client configuration

Create a single Oxapay instance (or one per integration) with the API keys you need. Different features use different keys:

| Key | Used for | | --- | --- | | merchantApiKey | Payment APIs: invoices, white-label, static addresses, payment history, accepted currencies | | payoutApiKey | Payout create / get / list | | generalApiKey | Swap APIs and account balance |

You can pass only the keys you use. If you call an endpoint without the required key, the client throws OxapayError before the HTTP request.

Options

| Option | Description | | --- | --- | | merchantApiKey | Merchant API key from the OxaPay dashboard | | payoutApiKey | Payout API key | | generalApiKey | General API key (swap + balance) | | baseUrl | API base URL (default: https://api.oxapay.com/v1) | | fetch | Custom fetch implementation (optional; defaults to globalThis.fetch) |

import { Oxapay, OXAPAY_DEFAULT_BASE_URL } from "oxapay-sdk";

const oxapay = new Oxapay({
  merchantApiKey: "...",
  baseUrl: OXAPAY_DEFAULT_BASE_URL,
});

console.log(oxapay.getBaseUrl());

API surface

The Oxapay class exposes namespaced resources:

payment (merchant key)

| Method | Description | | --- | --- | | generateInvoice | Create a hosted payment / invoice | | generateWhiteLabel | White-label payment with address and QR data | | generateStaticAddress | Create a static deposit address | | revokeStaticAddress | Revoke a static address | | listStaticAddresses | Paginated list of static addresses | | getPayment | Payment details by trackId | | listPayments | Paginated payment history | | getAcceptedCurrencies | Currencies available for payment |

payout (payout key)

| Method | Description | | --- | --- | | create | Create a payout | | get | Payout details by trackId | | list | Paginated payout history |

swap (general key)

| Method | Description | | --- | --- | | swap | Execute a swap | | listSwaps | Paginated swap history | | getPairs | Available swap pairs | | calculate | Quote toAmount / rate for an amount | | rate | Exchange rate between two currencies | | getAccountBalance | Account balances (optional currency filter) |

common (no key)

Public endpoints; requests use auth: "none" internally (no API key headers).

| Method | Description | | --- | --- | | getPrices | Market prices | | getCurrencies | Currency metadata and networks | | getFiats | Fiat reference data | | getNetworks | Network list | | getSystemStatus | Service monitor / status |

Deprecated: invoices

oxapay.invoices is a legacy alias that mirrors payment APIs. Prefer oxapay.payment and payment.generateInvoice instead of invoices.generate.

Responses

Successful API payloads are wrapped in an envelope type OxapayResponseEnvelope<T>:

type OxapayResponseEnvelope<T> = {
  data: T;
  message?: string;
  error?: { type?: string; key?: string; message?: string } | null;
  status?: number;
  version?: string;
};

List endpoints return data with list and meta (page, lastPage, total) where applicable. See PaginatedData in the exported types.

Errors

| Type | When | | --- | --- | | OxapayError | Missing API key, network failure, invalid JSON, mapper validation failures | | OxapayApiError | Non-OK HTTP response (extends OxapayError). Inspect httpStatus and body |

import { Oxapay, OxapayApiError, OxapayError } from "oxapay-sdk";

try {
  await oxapay.payment.getPayment("unknown-id");
} catch (err) {
  if (err instanceof OxapayApiError) {
    console.error(err.httpStatus, err.body);
  } else if (err instanceof OxapayError) {
    console.error(err.message);
  }
  throw err;
}

Advanced: low-level client

For custom integrations you can use OxapayClient directly. It sends JSON bodies, sets the correct header (merchant_api_key, payout_api_key, or general_api_key), and defaults auth mode to merchant.

import { OxapayClient } from "oxapay-sdk";

const client = new OxapayClient({ merchantApiKey: "..." });
const raw = await client.request<unknown>("GET", "/payment/some-path", { auth: "merchant" });

Building from source

npm install
npm run build

Output is written to dist/. The published package includes only dist (see "files" in package.json).

Exported types

The package re-exports request/response types for invoices, payments, payouts, swap, and public data (see src/index.ts on GitHub). Import what you need for stronger typing in your app:

import type { GenerateInvoiceParams, CreatePayoutParams } from "oxapay-sdk";

License

MIT