icone-pay-sdk

Official TypeScript SDK for the Icone Pay payment API — accept Moncash, cards, pay on delivery and marketplace payments, in multiple currencies, with signed webhooks.

Install

pnpm add icone-pay-sdk
# or: npm i icone-pay-sdk  /  yarn add icone-pay-sdk

Requires Node 18+ (uses the global fetch and node:crypto).

Initialize a payment

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 the customer to the hosted checkout:
return Response.redirect(res.url!);

The payload is validated locally (with Zod) before the request is sent, so invalid input returns { error: true, message } without a round-trip.

Multi-currency

Price in one currency and let the customer pay in another, converted at the day's mid-market rate. Pass paymentCurrency to fix the charge currency, or omit it to let the customer choose at checkout.

await icone.initPayment({
  action: "purchase",
  referenceId: "order_88",
  amount: 13000,
  currency: "htg",        // priced in gourdes
  paymentCurrency: "usd", // charged in USD at today's rate
  items: [{ name: "Course", quantity: 1, unitPrice: 13000 }],
  successUrl: "https://yourstore.com/thanks",
  cancelUrl: "https://yourstore.com/cart",
});

Supported currencies: htg, usd, dop, clp.

Pay on delivery

Offer cash on delivery (HTG orders only). deliveryFee controls whether the shipping fee is paid online up front or collected on delivery.

await icone.initPayment({
  action: "purchase",
  referenceId: "order_500",
  amount: 3000,
  currency: "htg",
  allowPayOnDelivery: true,
  deliveryFee: "on_delivery", // or "prepaid"
  items: [{ name: "Combo", quantity: 1, unitPrice: 3000 }],
  successUrl: "https://yourstore.com/thanks",
  cancelUrl: "https://yourstore.com/cart",
});

Retrieve a transaction

Look up a transaction by its orderId (returned at init time and in webhooks).

const res = await icone.getTransaction("V1StGXR8_Z5jdHi6B-myT");
if (!res.error) {
  console.log(res.transaction!.status, res.transaction!.paymentMethod);
}

Stripe Connect (marketplace)

Onboard sellers and route payments to their connected accounts. Create the account, send the seller to onboardingUrl, then pass the sellerId to initPayment to split a payment to them.

// 1. Onboard a seller
const acct = await icone.createConnectAccount({
  sellerId: "seller_42",
  email: "[email protected]",
});
// redirect the seller to acct.onboardingUrl

// 2. Check status (chargesEnabled must be true to receive payments)
const status = await icone.getConnectAccount("seller_42");

// 3. Take a marketplace payment for that seller
await icone.initPayment({
  action: "purchase",
  referenceId: "order_777",
  amount: 50,
  currency: "usd",
  sellerId: "seller_42",
  items: [{ name: "Handmade bag", quantity: 1, unitPrice: 50 }],
  successUrl: "https://market.com/thanks",
  cancelUrl: "https://market.com/cart",
});

// Other helpers:
await icone.createConnectAccountLink("seller_42");   // fresh onboarding/update link
await icone.getConnectDashboardLink("seller_42");    // Express dashboard login link

Verify webhooks

Every webhook is signed with your app's Signing Secret (Settings → Integration). Always verify it before trusting the payload — pass the raw request body.

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"),                 // raw body
      req.header("X-IconePay-Signature"),
      process.env.ICONEPAY_SIGNING_SECRET!,
    );

    if (event.event === "payment.success") {
      // fulfill the order — use event.orderId for idempotency
    }
    res.sendStatus(200);
  } catch (err) {
    if (err instanceof WebhookVerificationError) return res.sendStatus(400);
    throw err;
  }
});

verifyWebhook checks the HMAC-SHA256 signature and rejects replays older than 5 minutes (configurable via toleranceSeconds). The returned event is fully typed and includes both the presentment and charged amounts plus the COD split.

Test mode

Pass mode: "test" to route the request to the test endpoint (simulated payments, no real charges):

await icone.initPayment({ /* ... */, mode: "test" });

API

| Export | Description | | --- | --- | | IconePaySDK | Client: initPayment, getTransaction, createConnectAccount, getConnectAccount, createConnectAccountLink, getConnectDashboardLink. | | verifyWebhook | Verify a webhook signature and parse the event. | | WebhookVerificationError | Thrown when verification fails. | | initPaymentSchema | The Zod schema, if you want to validate separately. | | Types | InitPaymentParams, InitPaymentResponse, WebhookEvent, Currency, … |

License

MIT