@bank78/checkout

Drop-in payment checkout for the web — card, bank transfer, and Pay with Bank78 — with end-to-end encrypted payloads, built-in 3DS/redirect handling, and a themeable UI.

Install one package. @bank78/core and @bank78/themes come with it automatically.

npm install @bank78/checkout
# or
yarn add @bank78/checkout
# or
pnpm add @bank78/checkout

Quick start (React)

Wrap your app (or the checkout page) in a CheckoutProvider, import the stylesheet once, and drop in a checkout component.

import { CheckoutProvider, PaymentLinkCheckout } from '@bank78/checkout';
import '@bank78/checkout/styles.css';

export function Checkout({ linkref }: { linkref: string }) {
  return (
    <CheckoutProvider
      apiBaseUrl="https://checkout.bank78.co"
      apiKey={import.meta.env.VITE_BANK78_API_KEY}
      onSuccess={(result) => console.log('paid', result)}
      onCancel={() => console.log('cancelled')}
      onError={(err) => console.error(err)}
    >
      <PaymentLinkCheckout linkref={linkref} />
    </CheckoutProvider>
  );
}

That's the whole payment-link flow — the SDK loads the link, renders the card / bank-transfer / Pay-with-Bank78 UI, and handles the charge (including 3DS redirects and app hand-offs).

Hosted checkout session

When your backend pre-creates a checkout session, render it by reference:

import { CheckoutProvider, HostedSessionCheckout } from '@bank78/checkout';
import '@bank78/checkout/styles.css';

<CheckoutProvider apiBaseUrl="https://checkout.bank78.co" apiKey={API_KEY}>
  <HostedSessionCheckout sessionReference="chk-..." />
</CheckoutProvider>;

Create the session on your server — never expose secret keys in the browser.

Embed inline

Both components take an optional inline prop to drop the full-screen wrapper and render inside your own layout:

<PaymentLinkCheckout linkref={linkref} inline />

No build step / any framework (CDN)

A standalone bundle ships React, the checkout, and the CSS in a single <script>-loadable file that exposes a global Bank78Checkout. Use it from plain HTML, Vue, Svelte — anything.

<script src="https://cdn.jsdelivr.net/npm/@bank78/checkout/dist/cdn/bank78-checkout.global.js"></script>
<div id="checkout"></div>
<script>
  const instance = Bank78Checkout.renderPaymentLink('#checkout', {
    apiBaseUrl: 'https://checkout.bank78.co',
    apiKey: 'YOUR_API_KEY',
    linkref: 'pay-...',
    inline: true,
    onSuccess: (r) => console.log('paid', r),
    onCancel: () => {},
    onError: (e) => console.error(e),
  });
  // later: instance.unmount();
</script>

For a pre-created session, use Bank78Checkout.renderSession('#checkout', { apiBaseUrl, apiKey, sessionReference, inline }). Both return { unmount() }.

Using Vue?

There's a first-class Vue 3 wrapper: @bank78/vue. Same checkout, native Vue components and events — no React in your app code.

npm install @bank78/vue vue

<script setup>
import { PaymentLinkCheckout } from '@bank78/vue';
</script>

<template>
  <PaymentLinkCheckout
    api-base-url="https://checkout.bank78.co"
    :api-key="apiKey"
    :linkref="linkref"
    @success="onSuccess"
    @cancel="onCancel"
    @error="onError"
  />
</template>

It also ships HostedSessionCheckout, Bank78PayLaunch, Bank78PayApproval, and CancellationScreen — enough to wire the full Bank78 Pay flow with your own router. See the @bank78/vue README for details.

Configuration

CheckoutProvider props:

| Prop | Type | Description | | -------------- | ------------------------- | -------------------------------------------------------- | | apiBaseUrl | string | Checkout API base URL, e.g. https://checkout.bank78.co | | apiKey | string | Your API key — sent as X-Api-Key on every request | | publicKey | string? | Optional publishable key (pk_…) | | theme | Partial<CheckoutTheme>? | Override design tokens | | onSuccess | (result) => void | Fired when a payment succeeds | | onError | (error) => void | Fired on error | | onCancel | () => void | Fired on cancellation | | onStepChange | (step) => void | Fired on each checkout step — handy for analytics |

Component props:

| Component | Props | | ----------------------- | ----------------------------- | | PaymentLinkCheckout | linkref, inline? | | HostedSessionCheckout | sessionReference, inline? |

Theming

The design system is CSS variables — override tokens, no fork and no !important wars:

<CheckoutProvider
  theme={{
    colorPrimary: '#A9FFF2',
    colorBackground: '#111111',
    colorText: '#E8E8E8',
    borderRadius: '12px',
  }}
>
  {/* ... */}
</CheckoutProvider>

Entry points

| Import | What you get | | ----------------------------- | ------------------------------------------------------------ | | @bank78/checkout | Components, hooks, and re-exported core types/utilities | | @bank78/checkout/styles.css | The stylesheet (import once) | | @bank78/checkout/headless | Logic + hooks only, no styled components — build your own UI | | @bank78/checkout/cdn | The standalone browser bundle (Bank78Checkout global) |

Good to know

• Card PIN is automatic — when the session's provider requires it (e.g. Payaza for NGN cards), the SDK shows a 4-digit PIN field and includes it in the charge. You don't wire anything.
• 3DS & redirects are first-class — the SDK sends the customer to their bank / the Bank78 app and re-checks status on return, so sessions aren't lost.
• Encrypted payloads — sensitive request bodies are encrypted in the browser (RSA-OAEP + AES-GCM) on top of TLS.
• Publishable keys only — never put a secret key in client code.

Requirements

• React >= 18 (peer dependency) — not needed for the CDN bundle.

License

MIT