Install

The SDK works in any Node 18+ environment. It validates your payload locally before sending and ships full TypeScript types.

pnpm add icone-pay-sdk

Initialize a Payment

Create a client with your route API key and call initPayment. The same payload as the REST API is accepted, including paymentCurrency, allowPayOnDelivery and sellerId.

import { IconePaySDK } from "icone-pay-sdk";

const icone = new IconePaySDK(process.env.ICONEPAY_API_KEY!);

const res = await icone.initPayment({
  action: "purchase",
  referenceId: "order_1024",
  amount: 2500,
  currency: "htg",
  items: [{ name: "T-shirt", quantity: 1, unitPrice: 2500 }],
  successUrl: "https://yourstore.com/thanks",
  cancelUrl: "https://yourstore.com/cart",
});

if (res.error) throw new Error(res.message);
redirect(res.url!); // hosted checkout

Pass mode: "test" to route the request to the test endpoint while integrating.

Verify Webhooks

Use verifyWebhook to validate the X-IconePay-Signature header and get a typed event. Pass the raw request body and that route's Signing Secret.

import { verifyWebhook, WebhookVerificationError } from "icone-pay-sdk";

app.post(
  "/webhooks/iconepay",
  express.raw({ type: "application/json" }),
  (req, res) => {
    try {
      const event = verifyWebhook(
        req.body.toString("utf8"),
        req.header("X-IconePay-Signature"),
        process.env.ICONEPAY_SIGNING_SECRET!,
      );
      if (event.event === "payment.success") {
        // fulfill — use event.orderId for idempotency
      }
      res.sendStatus(200);
    } catch (err) {
      if (err instanceof WebhookVerificationError) return res.sendStatus(400);
      throw err;
    }
  },
);

Exports

Export	Description
`IconePaySDK`	Client with initPayment().
`verifyWebhook`	Verify a signature and parse the event.
`WebhookVerificationError`	Thrown when verification fails.
`initPaymentSchema`	The Zod schema, for validating separately.
`Types`	`InitPaymentParams`, `WebhookEvent`, `Currency`, …