DEV Community: CigalPay

Payment Links vs. API Integration: Choosing How to Accept Crypto

CigalPay — Sat, 07 Nov 2026 18:28:27 +0000

In short

Payment links need no code: create one in the dashboard with an amount and description, send it, and the customer pays.

An API integration creates the payment from your own checkout for every order and is the right choice once you sell online regularly.

Either way, use signed payment notifications to mark orders as paid automatically.

There are two ways to start taking crypto with a payment provider: share a link, or connect your checkout to its API. Both lead the customer to the same payment page. The difference is who creates the payment - you, by hand, or your system, automatically.

Payment links: no code

A payment link is a checkout page for one specific amount. In CigalPay's merchant dashboard you enter the amount in USD or EUR, a description your customer will see, and optionally the checkout language and your own order reference. You get a link and a QR code to share by email, chat or in person.

Good for: invoices, freelance and B2B work, selling on social media or marketplaces, and taking payments in person.
Keep in mind: each link's exchange rate is locked for 30 minutes from creation, so create the link when the customer is ready to pay. More in why crypto invoices expire.
Track them in the dashboard, where every link shows whether it's open, paid, partly paid or expired.

API integration: automatic, per order

With an API integration, your server creates the payment when a customer checks out, passing the order total, currency and your order reference. The customer is sent to the payment page and, once done, back to your site. It's the right choice when you have a shop with its own order system and regular volume.

Your server calls the API with the order amount, description and reference.
The API returns a checkout URL; your site redirects the customer there.
The customer picks a coin and pays.
Your server receives a signed payment notification and marks the order paid.
The customer returns to the page you set as the redirect URL.

Developers can find the API reference and SDK examples on our developers page.

Connecting payments to orders: notifications

Payment notifications (IPN) are what make either approach hands-off. When a payment's status changes - detected, confirmed, partially paid, expired - CigalPay sends a POST to your notification URL, signed with an HMAC-SHA512 signature in the x-cigalpay-sig header. Your server verifies the signature and updates the order. Don't rely on the customer's redirect back to your site; it isn't proof of payment. Our security checklist explains how to verify notifications.

Side by side

	Payment links	API integration
Setup	Minutes, no code	Developer time for one endpoint and one webhook
Who creates the payment	You, in the dashboard	Your checkout, automatically
Order matching	Your reference on the link	Your order ID passed in the API call
Best for	Invoices, social and in-person sales	Online shops with regular orders

A third option: WooCommerce and PrestaShop plugins

If your website runs on WooCommerce or PrestaShop, you get the API integration without writing it. The plugin creates the checkout for every order, checks the signed notifications and marks the order paid. You paste your Account ID and notification signing secret, and add your API key to refund orders in crypto from the order page. Download them from the developers page.

Start simple. Many merchants begin with payment links to see whether their customers want to pay in crypto, then add the API once volume grows. Nothing about the customer's payment experience changes when you switch.

FAQ

Can I reuse a payment link for several customers?

No. Each link is a single payment with a 30-minute rate lock. Create a new link for each order or customer.

Which languages does the checkout support?

CigalPay's checkout is available in English, French, Spanish and German. You can choose the language when creating a payment link.

Do I need a developer for payment links?

No. Payment links are created in the merchant dashboard without any code.

Sources

BIP 21: URI scheme for Bitcoin payments, Bitcoin Improvement Proposals
Solana Pay specification, Solana Pay
OWASP Top 10 API Security Risks - 2023, OWASP

Originally published on the CigalPay blog. Disclosure: I'm part of the CigalPay team. Questions? Ask in the comments.

How to accept crypto payments in Node.js (Express) in 5 minutes

CigalPay — Sun, 18 Oct 2026 01:22:44 +0000

Adding crypto as a payment option sounds like a lot of work: running nodes, generating addresses, watching the blockchain, handling confirmations, converting prices. With a payment gateway, it comes down to two endpoints on your server:

Create a payment and send the customer to a hosted checkout.
Receive a signed notification when the payment confirms, and mark the order as paid.

In this tutorial we build both with Node.js and Express, using CigalPay (disclosure: I'm part of the team building it). It's plain HTTP, so the same flow works in any language. If your site runs on WooCommerce or PrestaShop, or you'd rather not write code, this guide compares the 3 ways to accept crypto payments on your website.

What you need: Node.js 18 or later (for the built-in fetch), and a CigalPay account. Your account ID and your notification signing secret are in the merchant dashboard, under Settings.

1. Set up the project

mkdir crypto-checkout && cd crypto-checkout
npm init -y
npm pkg set type=module
npm install express

Put your credentials in environment variables, never in the code:

export CIGALPAY_ACCOUNT_ID="your-account-id"
export CIGALPAY_IPN_SECRET="your-notification-signing-secret"
export CIGALPAY_API_KEY="your-api-key"     # only for refunds (step 5)
export PUBLIC_URL="https://your-app.com"   # where CigalPay can reach your server

2. Create a payment

When the customer clicks "Pay with crypto", your server creates a payment and redirects them to the checkout. The price is in USD or EUR; the customer chooses the coin on the checkout, and the rate is locked while they pay.

// server.js
import crypto from 'node:crypto';
import express from 'express';

const app = express();
const { CIGALPAY_ACCOUNT_ID, CIGALPAY_IPN_SECRET, PUBLIC_URL } = process.env;

// A tiny in-memory "database" for the demo.
const orders = new Map();

app.post('/checkout/:orderId', async (req, res) => {
  const orderId = req.params.orderId;
  const order = { id: orderId, amount: 49.9, currency: 'USD', status: 'pending' };
  orders.set(orderId, order);

  const response = await fetch('https://coins-api.cigalpay.com/api/pre-invoice', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      accountId: CIGALPAY_ACCOUNT_ID,
      amount: order.amount,
      currency: order.currency,              // USD or EUR
      description: `Order #${orderId}`,      // shown to the customer
      extraId: orderId,                      // your reference, sent back in the notification
      lang: 'en',                            // checkout language: en, fr, es, de
      callback: `${PUBLIC_URL}/thank-you`,   // where the customer returns
      ipn: `${PUBLIC_URL}/cigalpay/ipn`,     // where the signed notification goes
    }),
  });
  if (!response.ok) return res.status(502).send('Could not create the payment');

  const { id, chargeLink } = await response.json();
  order.checkoutId = id;                     // checked when the notification arrives
  res.redirect(303, chargeLink);
});

That's the whole integration on the "pay" side. The customer lands on the checkout, picks a coin (Bitcoin, USDT, Ethereum and many others), scans the QR code or copies the address, and pays.

3. Verify the signed notification

When the payment status changes, CigalPay sends a POST with a JSON body to your ipn URL. The x-cigalpay-sig header holds an HMAC-SHA512 signature of the body, computed with your signing secret over the JSON with its top-level keys sorted.

Never mark an order as paid from the customer's redirect to /thank-you: anyone can open that URL. Only trust the notification, and only after checking its signature.

function isSignatureValid(body, received) {
  const expected = crypto
    .createHmac('sha512', CIGALPAY_IPN_SECRET)
    .update(JSON.stringify(body, Object.keys(body).sort()))
    .digest('hex');
  return (
    typeof received === 'string' &&
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))
  );
}

app.post('/cigalpay/ipn', express.json(), (req, res) => {
  const payment = req.body;
  if (!isSignatureValid(payment, req.get('x-cigalpay-sig'))) return res.sendStatus(401);

  const order = orders.get(payment.extraId);
  if (!order) return res.sendStatus(404);

  // Anyone can create a checkout with your account ID and an order number.
  // Only trust a payment for the checkout you created, at the order's price.
  if (payment.checkoutId !== order.checkoutId) return res.sendStatus(200);
  if (payment.checkoutCurrency !== order.currency || Math.abs(Number(payment.checkoutAmount) - order.amount) > 0.01) {
    return res.sendStatus(200);
  }

  switch (payment.status) {
    case 'CONFIRMING':
      // Seen on the network, not final yet: show "payment pending", don't ship.
      order.status = 'confirming';
      break;
    case 'CONFIRMED':
    case 'FINISHED':
      // Final: fulfil the order. Notifications can arrive more than once,
      // so make this step idempotent.
      if (order.status !== 'paid') {
        order.status = 'paid';
        order.paymentId = payment.id;        // needed to refund it later
        console.log(`Order ${order.id} paid`);
      }
      break;
    case 'PARTIALLY_PAID':
    case 'EXPIRED':
    case 'FAILED':
      order.status = payment.status.toLowerCase();
      break;
  }
  res.sendStatus(200);
});

app.get('/thank-you', (_req, res) => res.send('Thanks! Your payment is being confirmed.'));

app.listen(3000, () => console.log('Listening on http://localhost:3000'));

A few details worth knowing:

Check the checkout, not just the order number. Your account ID isn't secret: it's in every checkout you create. Without the checkoutId check, someone could create their own checkout for your order number, pay $1, and get a signed notification for it. The signature proves the notification comes from CigalPay, not that it's for the checkout you made.
Constant-time comparison. crypto.timingSafeEqual avoids leaking how much of the signature matched.
Idempotency. The same status can be delivered more than once; check the current order state before acting.
CONFIRMING is not paid. The transaction is on the network but not confirmed yet. Ship only on a final status.
Other coins. If the customer paid with a coin that was converted at checkout, the notification also contains swapFromCurrency, swapFromNetwork and swapFromAmount, so you can show what they actually sent.

4. Test it end to end

Your notification URL must be reachable from the internet. Locally, a tunnel does the job:

node server.js
# in another terminal
npx localtunnel --port 3000     # or ngrok, cloudflared...

Set PUBLIC_URL to the tunnel's address, restart, then:

curl -i -X POST "$PUBLIC_URL/checkout/1042"

Open the Location URL from the response, pay a small amount (a real $1 payment is the best test), and watch your terminal: Order 1042 paid.

5. Refund an order

A crypto transfer can't be reversed, so a refund is a new payment to the customer. CigalPay asks the customer for their address and sends it; you only say which payment and how much. This call needs your API key (dashboard, Settings), on top of the account ID:

app.post('/orders/:orderId/refund', express.json(), async (req, res) => {
  const order = orders.get(req.params.orderId);
  if (!order?.paymentId) return res.sendStatus(404);   // save payment.id from the notification

  const response = await fetch('https://merchant-api.cigalpay.com/api/refunds', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'cigalpay-api-key': process.env.CIGALPAY_API_KEY },
    body: JSON.stringify({
      paymentId: order.paymentId,
      checkoutAmount: req.body.amount,         // in the order's USD / EUR, or `amount` in the coin paid
      customerEmail: req.body.email,           // gets the link to enter their address
      reason: 'Returned item',
    }),
  });
  const data = await response.json();
  if (!response.ok) return res.status(response.status).send(data.error);  // e.g. balance too low
  res.json({ refundId: data.refund.id, customerLink: data.link });
});

The refund and its network fee come out of your CigalPay balance in the coin the customer paid. checkoutAmount is converted at the payment's rate, so the customer gets back the same share of what they sent.

Prefer an SDK?

Everything above is plain HTTP so you can see what happens. In a real app, the official SDK (cigalpay-js-sdk, no dependencies, TypeScript types included) does the same in a few lines:

import CigalPay from 'cigalpay-js-sdk';

const cigalpay = new CigalPay({ accountId: process.env.CIGALPAY_ACCOUNT_ID, apiKey: process.env.CIGALPAY_API_KEY });

const { id, chargeLink } = await cigalpay.createCheckout({
  amount: 49.9, currency: 'USD', orderId: '1042', description: 'Order #1042',
  returnUrl: `${PUBLIC_URL}/thank-you`, notifyUrl: `${PUBLIC_URL}/cigalpay/ipn`,
});

CigalPay.verifyWebhook(req.body, req.get('x-cigalpay-sig'), process.env.CIGALPAY_IPN_SECRET); // true or false

await cigalpay.createRefund({ paymentId, checkoutAmount: 20, customerEmail: 'customer@example.com' });

On WooCommerce or PrestaShop, you don't need code at all: the official plugins do all of this, refunds included.

Wrapping up

The whole integration is two routes:

Route	Job
`POST /checkout/:orderId`	Create the payment with `POST /api/pre-invoice`, redirect to `chargeLink`
`POST /cigalpay/ipn`	Verify `x-cigalpay-sig` and `checkoutId`, update the order from `status` and `extraId`
`POST /orders/:orderId/refund`	Optional: refund with `POST /api/refunds` and your API key

No nodes, no wallets to run, no blockchain polling. If you'd rather not write code at all, the dashboard can also create a payment link you can send by message or show as a QR code.

Docs and API reference: cigalpay.com/developers
SDKs: Node.js and PHP, plus WooCommerce and PrestaShop plugins.
Pricing: 1% per transaction with no monthly fee, or 0.5% on the Pro plan.

Questions about confirmations, underpayments or wrong-network deposits? Ask in the comments, happy to help.