Charisol PaymentsAdmin sign in

Connect your product to Charisol Payments

One Paystack webhook for every Charisol product. Tag your charges and receive your own events here.

Integrating a product with Charisol Payments

You need three things: tag your charges, name your plans with your prefix, and receive events at one address. Nothing else about how you use Paystack changes.

1. Tag every charge you start

When you create a Paystack transaction (POST /transaction/initialize) with Charisol's shared key, put your product id in metadata:

await fetch("https://api.paystack.co/transaction/initialize", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PAYSTACK_SECRET_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    email, amount, currency, reference, callback_url,
    plan,                                        // only for subscriptions
    metadata: { product: "maildrip", ...yourOwnMetadata },   // <- the tag
  }),
});

Paystack sends metadata back on that charge's events, which is how the router knows whose event it is. Use the exact product id from the registry (the admin screen lists them); an id that is not registered is held, never forwarded.

2. Name your plans with your prefix

Subscription renewals are created by Paystack and carry none of your metadata. The router learns each plan from your first tagged payment and also falls back to the plan name, so name plans "<Prefix> ..." (Maildrip: Maildrip Pro monthly ...). Plans created before this existed keep working once any tagged payment for them has been seen, or if their name starts with your prefix.

3. Receive events

The router POSTs to the address registered for your product, with the exact body and the original x-paystack-signature Paystack sent, plus:

Header Meaning
x-charisol-product your product id
x-charisol-event-id unique per Paystack event: use it so a retry never applies twice
x-charisol-timestamp unix seconds
x-charisol-signature HMAC-SHA256 of <timestamp>.<raw body> with your forwarding secret

Verify, and answer 2xx quickly (do the real work after answering). A non-2xx or a timeout is retried (1m, 5m, 15m, 1h, 3h, 6h, 12h); a 4xx other than 408/429 is not retried. Events can arrive more than once and out of order.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyPaystack(rawBody: string, signature: string | undefined, secretKey: string): boolean {
  if (!signature) return false;
  const expected = createHmac("sha512", secretKey).update(rawBody).digest("hex");
  const a = Buffer.from(expected), b = Buffer.from(signature);
  return a.length === b.length && timingSafeEqual(a, b);
}

export function verifyRouter(rawBody: string, timestamp: string, signature: string, forwardingSecret: string, now = Date.now()): boolean {
  if (Math.abs(Math.floor(now / 1000) - Number(timestamp)) > 300) return false;
  const expected = createHmac("sha256", forwardingSecret).update(`${timestamp}.${rawBody}`).digest("hex");
  return expected === signature;
}

Use the raw request body (before any JSON parsing) for both checks. Verifying Paystack's signature with the shared secret key keeps working exactly as it did when Paystack called you directly; verifying the router header is an extra check that the call came through Charisol Payments.

Also: ignore events that are not yours (an event for a plan you do not own) with a 200, never an error.

Registering

Ask an admin to add your product in the admin screen (name, https address, plan-name prefix). You are given a forwarding secret once; keep it in your secret store. Rotate it from the same screen.

Local and test mode

Paystack's test mode has its own webhook address and test keys; the router handles both and records which mode each event came from (mode in the admin screen).