Tools

Node.js SDK

@axiomis-pay/sdk is a small typed client for the invoices API plus webhook signature helpers. No dependencies, Node.js 18 or newer, works from TypeScript and plain JavaScript, ESM and CommonJS.

Install

npm install @axiomis-pay/sdk

Client

TypeScript

import { AxiomisPayClient } from '@axiomis-pay/sdk';

const pay = new AxiomisPayClient({
  apiKey: process.env.AXIOMISPAY_KEY!,   // axp_live_... or axp_test_...
  baseUrl: 'https://pay.axiomis.app/api',              // optional, this is the default
  timeoutMs: 15_000,                     // optional, default 15 s
});

Method	HTTP	Returns
`createInvoice(input, { idempotencyKey? })`	`POST /v1/invoices`	`Invoice`
`getInvoice(id)`	`GET /v1/invoices/:id`	`Invoice`
`listInvoicesByOrder(externalOrderId)`	`GET /v1/invoices?external_order_id=`	`Invoice[]`
`cancelInvoice(id)`	`POST /v1/invoices/:id/cancel`	`Invoice`
`listAssets()`	`GET /v1/assets`	`Asset[]`

Server-side only: the API key gives full access to your invoices. Never ship it to a browser or a mobile app.

Errors

TypeScript

import { AxiomisPayError } from '@axiomis-pay/sdk';

try {
  await pay.cancelInvoice(id);
} catch (e) {
  if (e instanceof AxiomisPayError && e.code === 'PAYMENT_IN_PROGRESS') {
    // a transfer is already on its way: wait for the webhook
  } else {
    throw e;
  }
}

AxiomisPayError has status (HTTP status), code (see error codes) and message. Network failures and timeouts throw the usual fetch errors: retry createInvoice with the same idempotency key.

Webhooks

Export	What it does
`verifyWebhook(rawBody, header, secret, { toleranceSec?, now? })`	Checks `AxiomisPay-Signature` and the 5-minute window, returns the parsed `WebhookEvent`. Throws `WebhookVerificationError` with `code`: `NO_SIGNATURE`, `BAD_SIGNATURE_HEADER`, `TIMESTAMP_OUT_OF_RANGE`, `SIGNATURE_MISMATCH`, `BAD_PAYLOAD`.
`signWebhook(secret, rawBody, timestamp?)`	Builds a valid header. Use it in your tests.
`SIGNATURE_HEADER`	`'AxiomisPay-Signature'`
`PAID_STATUSES`	`['paid', 'paid_overpaid', 'paid_late']`: statuses that mean "grant access".

rawBody must be the exact bytes we sent (Buffer or string), not a re-serialized object.

Test (Jest)

import { signWebhook } from '@axiomis-pay/sdk';

it('grants access on invoice.paid', async () => {
  const body = JSON.stringify({
    id: 'evt_test_1', type: 'invoice.paid', created: Math.floor(Date.now() / 1000), mode: 'test',
    data: { invoice: { id: 'inv_x', status: 'paid', external_order_id: '1042' } },
  });
  const res = await request(app)
    .post('/webhooks/axiomispay')
    .set('Content-Type', 'application/json')
    .set('AxiomisPay-Signature', signWebhook(process.env.AXIOMISPAY_WEBHOOK_SECRET!, body))
    .send(body);
  expect(res.status).toBe(200);
});

Types

Invoice, InvoiceStatus, InvoiceTransfer, CreateInvoiceInput, Asset, WebhookEvent, WebhookEventType, CancelReason, Mode. They mirror the JSON exactly, in snake_case.

Other languages

The API is plain HTTPS and JSON, so any HTTP client works. Signature verification in Python and PHP: Webhooks.