angular-klasha

Angular component, directive and service for accepting Klasha payments.

⚠️ Upgrade from 0.0.x immediately — 0.0.x is completely non-functional

[email protected] cannot process a payment at all, and never warns you.

1. Its checkout script no longer exists. 0.0.x loaded https://klastatic.fra1.digitaloceanspaces.com/{test,prod}/js/klasha-integration.js. That DigitalOcean Spaces bucket has been deleted and both URLs now return NoSuchBucket. window.KlashaClient is therefore never defined and the checkout silently never opens.

2. The 9th isTestMode argument is missing. KlashaClient takes isTestMode as its 9th constructor argument, and on the current pay.js it is the only thing that selects the sandbox. 0.0.x passes eight. That matters now, because the current script serves one URL for both environments — repointing without adding the argument would send sandbox traffic to production. 1.0.0 passes it, coerced to a real boolean.

   For the avoidance of doubt about the past: while the old CDN existed, 0.0.x selected /test/js/ or /prod/js/ correctly from isTestMode, and that script was environment-specific by URL. There is no evidence historical sandbox payments reached production.

3. The customer phone number was dropped. 0.0.x set kit.phone_number; the Klasha script only ever reads kit.phone.

4. Duplicate DOM ids. 0.0.x appended a <div id="ktest"> from the service constructor on every injection, so more than one payment button meant more than one element with the same id.

5. It loaded jQuery from the Google CDN for no reason — the Klasha script does not use jQuery.

6. It also console.log'd on construction and shipped a stale vendored copy of the dead integration script inside the published package.

1.0.0 fixes all of the above: it loads the current script https://js.klasha.com/pay.js, forwards isTestMode as a real boolean 9th argument, sets kit.phone, gives every instance its own container element, and loads no jQuery.

There is no safe way to stay on 0.0.x. Upgrade.

Requirements

| | | | --- | --- | | Angular | 16, 17, 18, 19 or 20 (@angular/common and @angular/core) | | Environment | Browser. The checkout script cannot run during server-side rendering; call pay() from a browser-only code path. |

Published as Ivy partial-compilation output, so it works with both NgModule-based and standalone applications.

Install

npm install --save angular-klasha

No script tag, no jQuery and no extra setup: https://js.klasha.com/pay.js is injected lazily the first time a payment is started.

1. Configure your merchant credentials

Standalone applications

import { bootstrapApplication } from '@angular/platform-browser';
import { provideKlasha } from 'angular-klasha';

import { AppComponent } from './app/app.component';

bootstrapApplication(AppComponent, {
  providers: [
    provideKlasha({
      merchantKey: 'YOUR_MERCHANT_KEY',
      businessId: '1',
      isTestMode: true, // false (or omitted) targets the LIVE gateway
    }),
  ],
});

NgModule applications

forRoot() still works exactly as it did in 0.0.x, so existing code does not have to change:

import { NgModule } from '@angular/core';
import { AngularKlashaModule } from 'angular-klasha';

@NgModule({
  imports: [
    AngularKlashaModule.forRoot('YOUR_MERCHANT_KEY', '1', true),
    // a config object also works:
    // AngularKlashaModule.forRoot({ merchantKey: 'YOUR_MERCHANT_KEY', businessId: '1', isTestMode: true }),
  ],
})
export class AppModule {}

isTestMode here is what gets forwarded to KlashaClient as its 9th argument. Leaving it out means live payments.

2. Use the component or the directive

Both are standalone, so you can import either one directly into a standalone component — or get both by importing AngularKlashaModule.

AngularKlashaComponent

Renders a <button> that opens the Klasha checkout when clicked.

import { Component } from '@angular/core';
import { AngularKlashaComponent, KlashaOptions } from 'angular-klasha';

@Component({
  selector: 'app-checkout',
  standalone: true,
  imports: [AngularKlashaComponent],
  templateUrl: './checkout.component.html',
})
export class CheckoutComponent {
  options: KlashaOptions = this.buildOptions();

  paymentInit(): void {
    console.log('Payment initialised');
  }

  paymentDone(response: unknown): void {
    console.log('Payment done', response);
    // Build a fresh options object for the next payment: `tx_ref` must be
    // unique and the Klasha script mutates the `kit` object it is given.
    this.options = this.buildOptions();
  }

  private buildOptions(): KlashaOptions {
    return {
      merchantKey: 'YOUR_MERCHANT_KEY',
      businessId: '1',
      amount: 10000,
      email: '[email protected]',
      fullname: 'Some Customer',
      phone: '+2348000000000',
      sourceCurrency: 'NGN',
      destinationCurrency: 'NGN',
      tx_ref: `klasha-${Date.now()}`,
      paymentDescription: 'Order #1234',
      isTestMode: true,
    };
  }
}

<angular-klasha
  [klashaOptions]="options"
  [class]="'btn btn-primary'"
  (paymentInit)="paymentInit()"
  (callBack)="paymentDone($event)"
>
  Pay with Klasha
</angular-klasha>

AngularKlashaDirective

Same behaviour, applied to your own element so you keep full control of the markup:

import { Component } from '@angular/core';
import { AngularKlashaDirective } from 'angular-klasha';

@Component({
  selector: 'app-checkout',
  standalone: true,
  imports: [AngularKlashaDirective],
  templateUrl: './checkout.component.html',
})
export class CheckoutComponent { /* … same class body as above … */ }

<button
  type="button"
  angular-klasha
  [klashaOptions]="options"
  (paymentInit)="paymentInit()"
  (callBack)="paymentDone($event)"
>
  Pay with Klasha
</button>

Individual inputs instead of klashaOptions

Every field of KlashaOptions is also available as its own input:

<button
  type="button"
  angular-klasha
  [merchantKey]="'YOUR_MERCHANT_KEY'"
  [businessId]="'1'"
  [amount]="10000"
  [email]="'[email protected]'"
  [fullname]="'Some Customer'"
  [phone]="'+2348000000000'"
  [tx_ref]="txRef"
  [isTestMode]="true"
  (paymentInit)="paymentInit()"
  (callBack)="paymentDone($event)"
>
  Pay with Klasha
</button>

merchantKey, businessId and isTestMode set on the component/directive take priority over the values given to provideKlasha() / forRoot().

(callBack) is required. Without a subscriber, pay() refuses to open the checkout and returns angular-klasha: Insert a callBack output like so (callBack)='PaymentComplete($event)' to check payment status.

Options

KlashaOptions — merchantKey, businessId, amount and email are required; everything else is optional.

| Option | Type | Description | | --- | --- | --- | | merchantKey | string | Your Klasha merchant key. Falls back to the globally provided one. | | businessId | string | Your Klasha business id. Falls back to the globally provided one. | | amount | number | Amount to charge. | | email | string | Customer email address. | | fullname | string | Customer full name. | | phone | string | Customer phone number. This is the field the Klasha script reads. | | phone_number | string | Deprecated alias of phone, still accepted. | | sourceCurrency | string | Currency you price in. Defaults to NGN. | | destinationCurrency | string | Currency the customer is charged in. Defaults to NGN. | | tx_ref | string | Unique transaction reference. Generated for you when omitted. | | callbackUrl | string | URL the customer is redirected to after paying. | | paymentDescription | string | Human readable description of the payment. | | isTestMode | boolean | true = Klasha sandbox, false/omitted = live gateway. | | metadata | unknown | Free-form data kept on the instance; not sent to Klasha. | | kit | KlashaKitOptions | Advanced: extra fields merged into the payload handed to the Klasha script. |

kit

You rarely need to set kit yourself — the service builds it from the options above. It ends up containing:

| Field | Source | | --- | --- | | currency | sourceCurrency | | phone | phone (or the deprecated phone_number) | | phone_number | the same value, kept only for backwards compatibility | | email | email | | fullname | fullname | | tx_ref | tx_ref, generated when omitted | | productType | kit.productType (or the deprecated kit.paymentType) | | amount | kit.amount, defaulting to amount | | sourceAmount | kit.sourceAmount, when you supply one | | callBack | wired to the (callBack) output for you |

The Klasha script mutates the kit object it is given (it assigns businessId, currency and redirect_url onto it). angular-klasha builds a brand new kit for every payment, so never share one between payments.

Outputs

| Output | Fires | | --- | --- | | (paymentInit) | Immediately before the Klasha checkout is opened. | | (callBack) | With the Klasha response once the payment flow finishes. Required. |

The checkout container

The Klasha script renders into a container element looked up by id. Each component/directive instance gets its own id (klasha-container-1, klasha-container-2, …): the element is created on the first payment, reused on every subsequent one, and removed on destroy. 0.0.x hardcoded ktest for every instance and appended a new element each time.

If you need the id — for styling, say — read it off the instance:

@ViewChild(AngularKlashaDirective) klasha!: AngularKlashaDirective;
// this.klasha.containerId

Programmatic use

AngularKlashaService is providedIn: 'root' and can be used without the component or the directive:

import { inject } from '@angular/core';
import { AngularKlashaService } from 'angular-klasha';

const klasha = inject(AngularKlashaService);

async function pay(): Promise<void> {
  const options = klasha.getKlashaOptions({
    merchantKey: 'YOUR_MERCHANT_KEY',
    businessId: '1',
    amount: 10000,
    email: '[email protected]',
    fullname: 'Some Customer',
    phone: '+2348000000000',
    isTestMode: true,
  });
  options.kit.callBack = (response) => console.log('done', response);

  const containerId = 'my-klasha-container';
  await klasha.loadScript();
  klasha.launch(options, containerId); // creates the container if needed
}

| Member | Description | | --- | --- | | loadScript() | Injects https://js.klasha.com/pay.js once and resolves when window.KlashaClient is available. | | getKlashaOptions(options) | Resolves defaults and builds a fresh kit. | | checkInput(options) | Returns '' when the options are usable, otherwise an error message. | | launch(resolvedOptions, containerId) | Constructs KlashaClient (with all nine arguments) and calls init(). | | ensureContainer(id) / removeContainer(id) | Container lifecycle. | | makeId(length?) | Random transaction reference generator. |

Also exported: KLASHA_SCRIPT_URL, nextKlashaContainerId(), and the MERCHANT_KEY, BUSINESS_ID and IS_TEST_MODE injection tokens.

Migrating from 0.0.x

| 0.0.x | 1.0.0 | | --- | --- | | AngularKlashaModule.forRoot(key, biz, isTest) | Unchanged — still works. | | <angular-klasha> / [angular-klasha] | Unchanged; now standalone as well. | | (callBack), (paymentInit) | Unchanged. | | phone_number | Still accepted; prefer phone. | | KlashaOptions required almost every field | Only merchantKey, businessId, amount and email are required. | | tx_ref had to be supplied | Generated when omitted. | | Container was always ktest | Per-instance id, available as .containerId. | | isTestMode was ignored by the Klasha script | Forwarded as the 9th constructor argument. | | PrivateKlashaOptions | Renamed ResolvedKlashaOptions (old name kept as a deprecated alias). |

Nothing that worked before has been removed.

Testing your integration

You cannot complete a real payment without live merchant credentials. Mock window.KlashaClient and assert on the constructor arguments — argument index 8 is isTestMode:

const calls: unknown[][] = [];
(window as any).KlashaClient = function (this: any, ...args: unknown[]) {
  calls.push(args);
  this.init = () => undefined;
};

// … trigger a payment …

expect(calls[0].length).toBe(9);
expect(calls[0][8]).toBe(true);          // isTestMode
expect((calls[0][7] as any).phone).toBe('+2348000000000');

Contributing

Fork the repository and open a pull request — contributions are welcome.

How can I thank you?

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

Thanks! Dansteve Adekanbi.

License

The MIT License (MIT). Please see the License File for more information.