Bobospay Checkout SDK

Secure, embeddable TypeScript checkout SDK for Bobospay. The library opens a hosted Bobospay checkout in a sandboxed iframe and communicates with the parent page using postMessage. The project builds multiple formats (ESM, UMD, IIFE, CJS) and emits TypeScript declaration files for consumers.

This README contains quick-start examples for plain HTML (CDN), npm/ESM usage, and framework examples for React and Vue.

Important: Customer is required

When creating a transaction the customer object is required in the options. You may provide:

• customer.id (if your backend already has a customer record), OR
• minimal customer details: firstname, lastname, and email.

If id is missing, the SDK validates that firstname, lastname and a valid email are present.

Installation (npm)

Install the package as a dependency in your project:

npm install @bobospay/bobospay-checkout
# or
yarn add @bobospay/bobospay-checkout

Build / Dev commands (for maintainers)

• Install dependencies:

npm install

• Local dev server (for examples / debugging):

npm run dev

• Build the library (bundles + type declarations):

npm run build

• Lint (if ESLint is configured):

npm run lint

CDN usage (plain HTML)

Host dist/bobospay.iife.js on a CDN and include it on the merchant page. The global exposed object is BobospayCheckout.

Versioned CDN URLs (recommended, lock the version to avoid surprises):

• jsDelivr (IIFE): https://cdn.jsdelivr.net/npm/@bobospay/[email protected]/dist/bobospay.iife.js
• unpkg (IIFE): https://unpkg.com/@bobospay/[email protected]/dist/bobospay.iife.js

Non-versioned (latest) URLs:

• jsDelivr (latest): https://cdn.jsdelivr.net/npm/@bobospay/bobospay-checkout/dist/bobospay.iife.js
• unpkg (latest): https://unpkg.com/@bobospay/bobospay-checkout/dist/bobospay.iife.js

Example:

<script src="https://cdn.jsdelivr.net/npm/@bobospay/[email protected]/dist/bobospay.iife.js"></script>
<script>
  const sdk = BobospayCheckout.createBobospayCheckout();
  sdk.init({ clientId: 'ci_test_xxx' }, {
    transaction: { amount: 1000, currency: 'NGN' },
    // Customer is required: provide either an id or firstname+lastname+email
    customer: { firstname: 'Jane', lastname: 'Merchant', email: '[email protected]' },
    callback: (data) => console.log('payment result', data),
    ui: { width: 420, height: 680, closeButton: true }
  });
  sdk.open();
</script>

Notes:

• Do not place secrets (client_secret) in the browser. Only the public clientId is expected here.
• The library will POST to the merchant API endpoint /v2/checkout-js to obtain a hosted checkout URL.

Usage (npm / ESM)

Import the public factory and use it directly in your JS/TS application:

import { createBobospayCheckout } from '@bobospay/bobospay-checkout'

const sdk = createBobospayCheckout()

sdk.init({ clientId: 'ci_test_xxx' }, {
  transaction: { amount: 1000, currency: 'NGN' },
  // Customer is required: provide either an id or firstname+lastname+email
  customer: { id: 'cust_123' },
  callback: (data) => console.log('payment result', data),
  ui: { width: 480, height: 720, closeButton: true }
})

await sdk.open()

React example (hooks)

A small React hook wrapper is included under src/react/useCheckout.ts as an example. You can import it or continue using the factory directly.

Example (functional component):

import React from 'react'
import { useReactCheckout } from '@bobospay/bobospay-checkout/dist/react/useCheckout' // or write your own wrapper using createBobospayCheckout

export function PayButton() {
  const { init, open } = useReactCheckout()

  React.useEffect(() => {
    init({ clientId: 'ci_test_xxx' }, {
      transaction: { amount: 1000, currency: 'NGN' },
      // Customer is required
      customer: { firstname: 'John', lastname: 'Doe', email: '[email protected]' },
      callback: (data) => {
        console.log('paid', data)
      },
      ui: { closeButton: true }
    })
  }, [init])

  return (
    <button onClick={() => open()}>
      Pay with Bobospay
    </button>
  )
}

Vue 3 example (composition API)

A minimal Vue composition wrapper is available at src/vue/useCheckout.ts. Example usage in a component:

<template>
  <button @click="open">Pay with Bobospay</button>
</template>

<script lang="ts">
import { defineComponent, onMounted } from 'vue'
import { useVueCheckout } from '@bobospay/bobospay-checkout/dist/vue/useCheckout' // or provide your own wrapper

export default defineComponent({
  setup() {
    const { init, open } = useVueCheckout()

    onMounted(() => {
      init({ clientId: 'ci_test_xxx' }, {
        transaction: { amount: 1000, currency: 'NGN' },
        // Customer is required
        customer: { id: 'cust_123' },
        callback: (data) => console.log('paid', data),
        ui: { closeButton: true }
      })
    })

    return { open }
  }
})
</script>

API contract (what the SDK does)

• The SDK sends a POST request to the merchant endpoint: ${baseUrl}/v2/checkout-js with body { transaction } and header X-Bobospay-Client-Id: <clientId>.
• The server is expected to return JSON with at least { url: '<hosted-checkout-url>' } where the url is a Bobospay-hosted checkout page.
• The SDK opens that URL inside a sandboxed iframe and listens to postMessage events coming from known checkout hosts. On successful payment the hosted page should send a message containing an object with an id field (or other agreed shape) which the SDK forwards to the merchant-provided callback.

Security notes and best practices

• Never store or send secrets (API private keys / client_secret) from client-side code.
• The SDK uses a sandboxed iframe and validates postMessage origins. Keep the list of allowed origins up to date if hosts change.
• For extra security consider server-side signing of the hosted checkout URL (short-lived tokens) and HMAC verification of messages between iframe and parent (requires support on the hosted page).
• Apply a strict CSP on merchant pages when possible.

Extending the SDK

Recommended improvements and places to extend:

• Accessibility improvements: focus trap, ARIA attributes, keyboard handling (Escape to close) and proper focus restoration.
• A small event emitter API to subscribe to lifecycle events (open/close/success/error).
• Server-side examples for creating the checkout session (POST /v2/checkout-js) and returning a signed token/URL.
• Unit tests for validation and message handling; CI (GitHub Actions) to run typecheck and build on PRs.

Contributing

Contributions are welcome. If you add features that change the public API, please update README and add tests.

License

MIT