Payscribe hosted checkout

The canvas reads a public session token from ?token=btn_... and calls only the public Button Checkout endpoints. Merchant secret keys must never be exposed here.

Configure the canvas before checkout.js loads when the API is hosted elsewhere:

<script>
  window.PAYSCRIBE_CHECKOUT_CONFIG = {
    apiBaseUrl: "https://sandbox.payscribe.ng/api/v1"
  };
</script>

Merchant button snippet

Add a container and the framework-agnostic script to the merchant page. Only a pk_test_… or pk_live_… publishable key belongs in browser code.

<div id="payscribe-button"></div>
<script src="https://checkout.payscribe.co/widget.js"></script>
<script>
  PayscribeCheckout.renderButton({
    container: "#payscribe-button",
    publicKey: "pk_live_REPLACE_ME",
    amount: 100,
    currency: "NGN",
    reference: () => `airtime_${Date.now()}`,
    service: "airtime",
    customer: {
      name: "Ada Lovelace",
      email: "[email protected]",
      phone: "08012345678"
    },
    metadata: {
      network: "mtn",
      recipient: "08012345678"
    },
    label: "Buy airtime",
    onSuccess(result) { console.log(result); },
    onError(error) { console.error(error); },
    onClose() {}
  });
</script>

On click, the SDK creates a short-lived session using the publishable key and opens canvas_url in a secure modal. A new unique reference must be generated for each attempt.

If the merchant already creates sessions on their backend, they can open an existing token directly:

PayscribeCheckout.open({ sessionToken: "btn_abc123" });

Or install the same launcher from npm:

npm install @payscribe/checkout-js

import PayscribeCheckout from "@payscribe/checkout-js";

React / Vite

Create the session through your own backend, then open the returned public token from a component:

import { useEffect } from "react";
import PayscribeCheckout from "@payscribe/checkout-js";

export function PayButton() {
  useEffect(() => () => PayscribeCheckout.destroy(), []);

  async function pay() {
    const response = await fetch("/api/checkout-session", { method: "POST" });
    if (!response.ok) throw new Error("Unable to create checkout session");
    const session = await response.json();

    PayscribeCheckout.open({
      sessionToken: session.token,
      canvasUrl: session.canvas_url,
      onSuccess: (result) => console.log(result),
      onError: (error) => console.error(error),
    });
  }

  return <button onClick={pay}>Pay with Payscribe</button>;
}

The same default import works in Vue, Svelte, and vanilla Vite applications. In SSR frameworks, dynamically import the package in a client component or browser-only handler.

The widget verifies both the iframe window and canvas origin before accepting messages. The canvas targets the stored session origin, or the parent origin derived from its referrer.

The canvas defaults to the same sandbox API base as @payscribe/sdk. Override apiBaseUrl with https://api.payscribe.ng/api/v1 for production.

The customer flow loads and reviews the initialized session, then calls button/transfer/init. Service validation is available as a separate backend operation but is not called by the hosted payment path.

For local browser testing against production routes that do not yet return CORS headers, set PAYSCRIBE_SECRET_KEY in the repository .env, run node hosted-checkout/dev-server.mjs, and add environment=proxy to the checkout URL. The proxy supplies authentication server-side and is intended only for local development. Never put the secret key in checkout.js or browser configuration.