Developers
Build the experience. Connect the payments.
One call creates a payment. Your customer pays on the provider's hosted page, so card and bank details never reach you or us. One authoritative status tells you what happened. Webhooks are signed and retried. Every write is idempotent. Test mode behaves like production, and go-live is a key swap.
Start here
Start with an integration conversation.
- Public API documentation is not on this site yet.
- Integration guidance, the reference and access come through onboarding.
- A person replies.
Two calls
Create a payment. Verify a webhook.
Reconciled against the live API. Placeholder key and base URL; the real ones come with onboarding.
curl -X POST "$JADEPAY_BASE_URL/v1/payments" \
-H "Authorization: Bearer jp_test_your_key" \
-H "Idempotency-Key: order-10442-attempt-1" \
-H "Content-Type: application/json" \
-d '{
"amount_cents": 124000,
"currency": "ZAR",
"reference": "INV-10442",
"bank_reference": "INV10442",
"return_url": "https://your-shop.example/payments/return"
}'
# 201 { "id": "pay_...", "status": "created", "redirect_url": "https://..." }
# Send the customer to redirect_url. The provider's hosted page takes it from there.
# Same Idempotency-Key, same body: same payment back. Different body: 409.import { createHmac, timingSafeEqual } from "node:crypto";
// Headers: webhook-id, webhook-timestamp, webhook-signature ("v1,<base64>", space separated if more than one).
// Signed string: id.timestamp.rawBody with HMAC-SHA256. Use the raw body, never a re-serialised one.
export function verifyWebhook(rawBody, headers, secret) {
const id = headers["webhook-id"];
const ts = Number(headers["webhook-timestamp"]);
if (Math.abs(Date.now() / 1000 - ts) > 300) throw new Error("webhook timestamp outside tolerance");
const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
const expected = Buffer.from(createHmac("sha256", key).update(`${id}.${ts}.${rawBody}`).digest("base64"));
const ok = headers["webhook-signature"].split(" ").some((entry) => {
const [version, sig = ""] = entry.split(",");
const given = Buffer.from(sig);
return version === "v1" && given.length === expected.length && timingSafeEqual(given, expected);
});
if (!ok) throw new Error("no matching webhook signature");
return JSON.parse(rawBody);
// Dedupe on webhook-id. Then read the authoritative status with GET /v1/payments/{id} before you release anything.
}What we scope
What we scope with you.
Payment flows
Checkout, payment links and recurring collections, mapped to the journeys your customers actually take.
Data boundaries
Card and bank details stay with the provider. We define who stores what, and who is responsible for it, before the first call.
Status and reconciliation
Your references on every payment, the one status that releases goods, and the reports your finance team will reconcile against.
Security posture
Security, in architecture terms.
- Credentials never touch JadePay
- Customers pay on the provider's hosted page or on the device. Card data lives with PCI DSS certified providers, never with JadePay.
- Keys hashed, shown once
- An API key is shown once at creation and stored hashed. Lose one, rotate it.
- Every webhook signed
- Each delivery carries an id, a timestamp and an HMAC signature. Verify against the raw body, reject stale timestamps, dedupe on the id.
No badges, by design. The facts above are how the system is built, not a certificate we hold.
Bring your integration questions.
Tell us what you are building and which flows you need. A person replies. The reference and test access come through onboarding.
Talk to JadePay