Node.js Library

The official Payid19 Node.js library wraps the REST API in a typed client, so you can create invoices and verify payments with a few lines of code. It ships with TypeScript types, has no runtime dependencies, and every call rejects with a typed error instead of returning an error envelope. Open source on GitHub and npm.

Requirements

• Node.js 18 or newer (the library uses the built-in fetch)

Installation

npm install payid19-api-node

Setup

Create a client with the public and private keys from your Settings page:

// CommonJS
const { Payid19 } = require('payid19-api-node');

const payid19 = new Payid19(process.env.PAYID19_PUBLIC_KEY, process.env.PAYID19_PRIVATE_KEY);

// TypeScript / ESM
import { Payid19 } from 'payid19-api-node';

const payid19 = new Payid19(publicKey, privateKey);

Creating an invoice

Resolves with the hosted payment page URL — redirect your customer there. All parameters of the create_invoice endpoint are supported:

const url = await payid19.createInvoice({
    price_amount: 100,
    price_currency: 'USD',
    order_id: 42,
    email: '[email protected]',
    title: 'Order #42',
    success_url: 'https://yoursite.com/payment/success',
    cancel_url: 'https://yoursite.com/payment/cancel',
    callback_url: 'https://yoursite.com/payment/callback',
});

res.redirect(url);

Pass banned_coins as an array (e.g. ['BTC','ETH']) — the library encodes it for you.

Payment page templates

The hosted payment page comes in four designs. Pass the one you want as the template parameter; the returned URL points at that design (e.g. https://payid19.com/invoice/{alias}/paper). Omit it to keep the classic page.

import { Payid19, TEMPLATES, type Template } from 'payid19-api-node';

await payid19.createInvoice({ price_amount: 100, order_id: 42, template: 'mint' });

TEMPLATES; // readonly ['classic', 'slate', 'paper', 'mint']

In TypeScript the value is checked at compile time, so a typo fails the build rather than the API call.

Checking invoices

Fetch your invoices — for example by your own order ID — and check their status field (null = waiting, 1 = paid, 2 = refunded, 3 = underpaid):

const invoices = await payid19.getInvoices({ order_id: 42 });

Handling the payment callback

When an invoice is paid, Payid19 sends a POST request to the callback_url you set on the invoice. verifyCallback() does the documented timing-safe check of the privatekey field:

app.post('/payment/callback', (req, res) => {
    if (!payid19.verifyCallback(req.body)) {
        return res.sendStatus(403);
    }

    // payment confirmed - mark req.body.order_id as paid (keep it idempotent)

    res.sendStatus(200);
});

Coins and estimates

const coins = await payid19.getCoins();
const estimate = await payid19.getEstimate({ /* see the docs for parameters */ });

Full parameters: get_coins · get_estimate.

Withdrawals

const balance = await payid19.getBalance();
const withdraw = await payid19.createWithdraw({ /* see the docs for parameters */ });

Full parameters: get_balance · create_withdraw.

White label

With white_label: 1 the API returns a JSON coin list instead of a page URL, so you can build the checkout under your own brand. Because the response is not a URL, reach it through request():

const coins = await payid19.request('create_invoice', {
    price_amount: 100,
    order_id: 42,
    white_label: 1,
});

See the white label guide.

Error handling

Every method rejects with a Payid19Error whose code says what went wrong (api_error, http_error, invalid_json, empty_response, network_error, timeout):

import { Payid19Error } from 'payid19-api-node';

try {
    const url = await payid19.createInvoice({ price_amount: 100 });
} catch (err) {
    if (err instanceof Payid19Error) {
        console.error(err.code, err.messages);
    } else {
        throw err;
    }
}