Kojoforex Pay SDK (kojoforexpay)

Official JavaScript / TypeScript client for integrating Kojoforex Pay into your applications.

Kojoforex Pay provides a unified payment API across multiple providers (Stripe, Pallapay, Binance Pay), handling payments, subscriptions, and webhooks with a consistent interface.

✨ Features

• ✅ Unified payments API
• ✅ Subscription management
• ✅ Multi-provider support
• ✅ Secure webhook verification
• ✅ Typed TypeScript interfaces
• ✅ Server-side only (secure by design)

📦 Installation

npm install kojoforexpay
# or
pnpm add kojoforexpay
# or
yarn add kojoforexpay

⚠️ Runtime Requirements (IMPORTANT)

• Node.js ≥ 18
• Server-side only
• ❌ Do NOT use in browsers
• ❌ Do NOT use in Edge runtimes

For Next.js webhook routes, always specify:

export const runtime = "nodejs";

🔑 Authentication

You will receive:

• API Key → for creating payments & subscriptions
• Webhook Secret → for verifying incoming webhooks

Store both securely in environment variables.

KOJOFOREX_PAY_API_KEY=your_api_key
KOJOFOREX_WEBHOOK_SECRET=your_webhook_secret

🧠 Mental Model

Your App
   ↓
Kojoforex Pay SDK
   ↓
Kojoforex Pay API
   ↓
Payment Providers (Stripe, Pallapay, Binance Pay)

• You never talk to providers directly
• You always trust webhooks for final state
• Checkout URLs are temporary

🚀 Basic Usage

Create a client

import { KojoforexPayClient } from "kojoforexpay";

const kp = new KojoforexPayClient({
  apiKey: process.env.KOJOFOREX_PAY_API_KEY!,
});

💳 Creating a Payment

const payment = await kp.createPayment({
  amount: 200,
  currency: "USD",
  provider: "stripe",
  title: "Mnetorship Session 101",
  description: "Access to Mentorship Session 101",
  customer: {
    email: "[email protected]",
    name: "Abdul Shakur",
  },
  metadata: {
    order_id: "ORD-1234",
    user_id: "UID-1234",
  },
  success_callback_url: "https://yourapp.com/payment/success",
  cancel_callback_url: "https://yourapp.com/payment/cancel",
});

// Redirect user to checkout
redirect(payment.checkout_url!);

⚠️ Important

• checkout_url is not final confirmation
• Always wait for the webhook before granting access

🏦 Getting Payment Options

You can fetch the list of configured and enabled payment providers automatically:

const optionsResponse = await kp.getPaymentOptions();

console.log(optionsResponse.options);
// Returns an array of available payment methods with details:
// [{
//   id: "stripe",
//   name: "Stripe",
//   description: "Credit & Debit Cards, Bank Transfers",
//   methods: ["Visa", "Mastercard", "Apple Pay", "Google Pay", "Wire"],
//   currencies: ["USD"],
//   accept_subscription_payments: true,
//   logo_url: "https://..."
// }]

🔁 Creating a Subscription

const subscription = await kp.createSubscription({
  amount: 50,
  currency: "USD",
  provider: "stripe",
  interval: "month",
  title: "Pro Subscription",
  description: "Monthly Pro Plan",
  customer: {
    email: "[email protected]",
    name: "Abdul Shakur",
  },
  metadata: {
    user_id: "UID-1234",
  },
  success_callback_url: "https://yourapp.com/subscription/success",
  cancel_callback_url: "https://yourapp.com/subscription/cancel",
});

redirect(subscription.checkout_url!);

🔄 Managing Subscriptions

Cancel a subscription

await kp.cancelSubscription({
  subscription_id: "SUB_1234",
});

Change subscription pricing

await kp.changeSubscription({
  subscription_id: "SUB_1234",
  amount: 30,
  currency: "USD",
  interval: "month",
});

Update subscription plan definition

await kp.updateSubscriptionPlan({
  name: "Pro Plus",
  amount: 30,
  currency: "USD",
  interval: "month",
});

🔔 Webhook Handling (CRITICAL)

Webhooks are the source of truth for payment & subscription state.

Step 1: Create a webhook-only client

import { KojoforexPayClient } from "kojoforexpay";

const kp = new KojoforexPayClient({
  forWebhook: true,
  webhookSecret: process.env.KOJOFOREX_WEBHOOK_SECRET!,
});

Step 2: Verify webhook signature (Next.js example)

export const runtime = "nodejs";

export async function POST(req: Request) {
  const result = await kp.verifyWebhookSignature(req, "payment");

  if (result instanceof Response) {
    return result; // invalid signature
  }

  // result is now strongly typed
  if (result.event === "payment.success") {
    // grant access
  }

  return new Response("OK", { status: 200 });
}

🧬 Webhook Event Types

Payment events

type WebhookEvent =
  | "payment.success"
  | "payment.failed"
  | "subscription.success"
  | "subscription.failed"
  | "dispute.won"
  | "dispute.lost";

Payment webhook payload

{
  type: "payment",
  payment_id: string,
  provider: "stripe" | "pallapay" | "binacepay",
  event: WebhookEvent,
  status: PaymentStatus,
  amount: number,
  currency: string,
  payment_method: string,
  metadata: Record<string, unknown>
}

Subscription webhook payload

{
  type: "subscription",
  subscription_id: string,
  provider: Provider,
  event: WebhookEvent,
  status: PaymentStatus,
  subscription_end_date?: number,
  metadata: Record<string, unknown>
}

🔐 Security Best Practices

• ✅ Use webhooks for final confirmation
• ❌ Never trust redirect URLs
• ❌ Never expose API keys to the client
• ❌ Do not use this SDK in the browser

❗ Common Mistakes

| Mistake | Why it’s bad | | ------------------------------- | ------------------------ | | Granting access on redirect | Redirects can be spoofed | | Using Edge runtime | Crypto APIs won’t work | | Exposing API keys | Critical security risk |

📄 TypeScript Support

The SDK is fully typed and exports:

• PaymentStatus
• WebhookEventPayload<T>
• Strongly-typed request & response objects

📌 Supported Providers

• Stripe
• Pallapay
• Binance Pay

(Provider routing is handled automatically by Kojoforex Pay.)

🏁 Summary

Kojoforex Pay SDK gives you:

• One API
• Multiple providers
• Secure webhooks
• Clean abstractions
• Production-ready payments

🧩 Support

If you encounter issues:

• Verify environment variables
• Ensure Node runtime
• Check webhook signature handling

Welcome to Kojoforex Pay 🚀 You’re building on a solid, scalable payments foundation.