react-klasha

React hooks and components for accepting payments with the Klasha payment gateway.

⚠️ Version 0.0.x is completely non-functional — upgrade to 1.0.0

Two things were wrong with 0.0.x, and both are fatal:

1. The script it loaded no longer exists. 0.0.x fetched https://klastatic.fra1.digitaloceanspaces.com/{test,prod}/js/klasha-integration.js. That bucket has been deleted; both URLs now return a 404. window.KlashaClient is therefore never defined and no payment can start at all. Klasha's current script is https://js.klasha.com/pay.js, which 1.0.0 loads.

2. isTestMode was never sent to the gateway. The Klasha client takes the test flag as its 9th constructor argument; 0.0.x stopped at 8. Inside the Klasha script the flag then read as undefined, so the base URL, the iframe and the redirect URL all took the production branch. This matters now: the current pay.js serves one URL for both environments and decides which gateway to use from that argument alone, so repointing 0.0.x at the new script without adding it would route sandbox traffic to production. 1.0.0 passes it, coerced to a real boolean.

   To be clear about the past: while the old CDN still existed, 0.0.x picked /test/js/ or /prod/js/ correctly based on isTestMode, and that old script was environment-specific by URL. There is no reason to believe your historical sandbox payments went to production, and nothing to reconcile.

1.0.0 also fixes a silently dropped phone number, duplicate DOM ids, a load race that reported "ready" before the Klasha script had run, and console.log calls that printed your merchantKey to the browser console. See Migrating from 0.0.x.

Requirements

• React 16.8 or later (17, 18 and 19 are supported)
• Node 18+ to build from source

0.0.x declared support for React 15, but the library is built on hooks and has never worked below 16.8.

Install

npm install react-klasha

yarn add react-klasha

Quick start

import {KlashaButton} from 'react-klasha';

export default function Checkout() {
  return (
    <KlashaButton
      text="Make Payment"
      className="payButton"
      merchantKey="YOUR_MERCHANT_KEY"
      businessId="YOUR_BUSINESS_ID"
      amount={1000}
      sourceCurrency="USD"
      destinationCurrency="NGN"
      tx_ref={`tx-${Date.now()}`}
      fullname="John Doe"
      email="[email protected]"
      phone="+2348143108254"
      paymentDescription="Order #1234"
      isTestMode
      callBack={(response) => console.log('payment complete', response)}
    />
  );
}

isTestMode selects the environment

There is a single script — https://js.klasha.com/pay.js — for both test and live traffic. The environment is chosen entirely by isTestMode, which this library forwards as the 9th constructor argument:

| isTestMode | Gateway used | | --- | --- | | true | Klasha test environment | | false (default) | Klasha live environment |

Use your test merchant key with isTestMode, and your live key without it.

Usage

useKlashaPayment hook

import {useKlashaPayment} from 'react-klasha';

function DonateButton() {
  const config = {
    merchantKey: 'YOUR_MERCHANT_KEY',
    businessId: 'YOUR_BUSINESS_ID',
    amount: 1000,
    sourceCurrency: 'USD',
    destinationCurrency: 'NGN',
    tx_ref: `tx-${Date.now()}`,
    fullname: 'John Doe',
    email: '[email protected]',
    phone: '+2348143108254',
    isTestMode: true,
  };

  const initializePayment = useKlashaPayment(config);
  const callBack = (response) => console.log('payment complete', response);

  return <button onClick={() => initializePayment(callBack)}>Donate</button>;
}

initializePayment throws if it is called before the Klasha script has loaded, or if the script failed to load. Gate your button on the script state:

import {useKlashaScript, useKlashaPayment} from 'react-klasha';

function PayButton({config, callBack}) {
  const [ready, failed] = useKlashaScript(config.isTestMode);
  const initializePayment = useKlashaPayment(config);

  if (failed) return <p>Payment is unavailable right now.</p>;

  return (
    <button disabled={!ready} onClick={() => initializePayment(callBack)}>
      {ready ? 'Pay' : 'Loading…'}
    </button>
  );
}

useKlashaScript returns [loaded, error]. loaded only turns true once pay.js itself has executed — never merely because a load was started.

KlashaConsumer render prop

import {KlashaConsumer} from 'react-klasha';

<KlashaConsumer {...config} callBack={callBack}>
  {({initializePayment}) => <button onClick={initializePayment}>Pay with Klasha</button>}
</KlashaConsumer>;

KlashaConsumer forwards refs. The ref is handed to the render prop:

<KlashaConsumer {...config} ref={myRef}>
  {({initializePayment, ref}) => (
    <button ref={ref} onClick={initializePayment}>
      Pay
    </button>
  )}
</KlashaConsumer>;

KlashaProvider

Wrap a subtree so nested components share one payment configuration. Nested components read initializePayment and callBack from context.

import {KlashaProvider} from 'react-klasha';

<KlashaProvider {...config} callBack={callBack}>
  <Checkout />
</KlashaProvider>;

API

Payment options

Accepted by useKlashaPayment, KlashaButton, KlashaConsumer and KlashaProvider.

| Option | Type | Required | Description | | --- | --- | --- | --- | | merchantKey | string | ✅ | Merchant API key from the Klasha dashboard | | businessId | string \| number | ✅ | Merchant business id | | amount | number | ✅ | Amount to charge | | isTestMode | boolean | | Use the Klasha test environment. Defaults to false | | sourceCurrency | string | | Currency the customer is charged in. Defaults to NGN | | destinationCurrency | string | | Currency the merchant is settled in. Defaults to NGN | | tx_ref | string | | Your unique transaction reference. Generated when omitted | | fullname | string | | Customer's full name | | email | string | | Customer's email | | phone | string | | Customer's phone number | | phone_number | string | | Deprecated alias of phone | | callbackUrl | string | | URL the gateway calls when the transaction completes | | paymentDescription | string | | Description of what is being paid for | | metadata | object | | Extra data to keep alongside the transaction | | kit | KlashaKitOptions | | Extra fields forwarded to the Klasha client | | containerId | string | | Render the checkout into a specific element. One is created per component when omitted |

The kit object

kit is passed straight to the Klasha client. The keys pay.js actually reads are businessId, currency, redirect_url, email, phone, productType, amount, sourceAmount, callBack and tx_ref.

You rarely need to set any of them — this library fills in currency, email, fullname, phone, amount, tx_ref and callBack from the top-level options and builds a fresh kit for every payment (the Klasha script mutates the object it is given, so a shared one leaks state between transactions).

const config = {
  // …payment options…
  kit: {
    productType: 'digital',
    sourceAmount: 12,
  },
};

kit.phone is the key the gateway reads. 0.0.x set only kit.phone_number, which pay.js never looks at, so the customer's phone number was silently dropped from the exchange-rate request. 1.0.0 sets both.

KlashaButton props

Everything above, plus:

| Prop | Type | Description | | --- | --- | --- | | text | string | Button label | | children | ReactNode | Used when text is absent | | className | string | CSS class | | disabled | boolean | Disable the button | | type | 'button', 'submit' or 'reset' | Defaults to 'button' | | callBack | Function | Called when the payment flow completes |

Exports

import {
  useKlashaPayment,
  useKlashaScript,
  useKlashaContainer,
  KlashaButton,
  KlashaConsumer,
  KlashaProvider,
  ensureKlashaContainer,
  removeKlashaContainer,
  getKlashaScriptUrl,
  KLASHA_SDK_URL,
} from 'react-klasha';

TypeScript types KlashaOptionsProps, KlashaKitOptions, KlashaClientConstructor, KlashaClientInstance and KlashaRenderProps are exported too.

Migrating from 0.0.x

| Change | Impact | | --- | --- | | Loads https://js.klasha.com/pay.js | The old CDN bucket was deleted and returns 404, so 0.0.x cannot start a payment at all. | | isTestMode is forwarded to the gateway | Test-mode integrations no longer hit the live environment. Use your test merchant key when isTestMode is set. | | jQuery is no longer loaded | pay.js does not need it. If you relied on this library to provide window.$, load jQuery yourself. | | useKlashaScript reports loaded only once pay.js has executed | It used to resolve on whichever of jQuery/Klasha loaded first, so loaded was frequently true while window.KlashaClient was undefined. | | Script error no longer reports loaded: true | useKlashaScript returns [false, true] on failure instead of [true, true]. | | initializePayment throws instead of silently doing nothing when the script is not ready | Gate the call on useKlashaScript, or catch the error. | | The checkout container has a unique per-component id | The hardcoded <div id="ktest"> was appended on every effect run. Pass containerId if you need a specific element. | | kit.phone is populated | The phone number used to be dropped. kit.phone_number is still set for compatibility. | | tx_ref is generated when omitted | It is interpolated into the redirect URL and must not be empty. | | console.log of the options (including merchantKey) removed | Nothing is written to the console any more. | | KlashaConsumer ref actually reaches the render prop | It was always undefined before. | | Peer range is now react@^16.8 \|\| ^17 \|\| ^18 \|\| ^19 | React 15 was never actually supported. | | react-dom peer dependency removed | The library never imported it. | | Build output is dist/index.cjs + dist/index.mjs with an exports map | Deep imports into dist/ are no longer supported. |

Development

npm install
npm run typecheck
npm test
npm run build

Documentation

See the Klasha documentation for the full list of options and for how to verify a transaction server-side.

Always verify a payment on your server before fulfilling an order. Never trust the browser callback alone.

Contributing

1. Fork it
2. Create your feature branch: git checkout -b feature-name
3. Commit your changes: git commit -am 'Some commit message'
4. Push to the branch: git push origin feature-name
5. Submit a pull request 😉

How can I thank you?

Star the repo, and share it! Don't forget to follow me on twitter.

Thanks! Adekanbi Dansteve.

License

MIT — see LICENSE.md.