@wascash/sdk

WasCash JavaScript SDK for integrating payment checkout into web applications.

Installation

npm install @wascash/sdk

Quick Start

import WasCash from '@wascash/sdk'

const wascash = new WasCash({
  sessionId: 'checkout-session-uuid',
  clientSecret: 'your-client-secret',
  container: '#payment-container',
})

wascash
  .on('success', (payload) => {
    // payment completed
  })
  .on('failed', (payload) => {
    // payment failed
  })
  .on('cancelled', () => {
    // user cancelled
  })

await wascash.mount()

The constructor only validates config. Nothing renders until you call mount(), which validates the session against the WasCash API and injects the payment iframe into your container.

Configuration

| Option | Type | Required | Default | Description | | -------------- | ---------------------- | -------- | ------- | ----------------------------------- | | sessionId | string | Yes | - | Checkout session UUID from your API | | clientSecret | string | Yes | - | Client secret from checkout session | | container | string \| HTMLElement| Yes | - | CSS selector or DOM element | | locale | 'en' \| 'ar' | No | 'en' | UI language |

API

| Method | Returns | Description | | ------------------------------- | ------------------ | ----------------------------------------------------------------- | | mount() | Promise<void> | Validates the session and renders the payment iframe. | | on(event, callback) | this | Subscribes to a payment event. Chainable. | | off(event, callback) | this | Removes a previously registered listener. Chainable. | | destroy() | void | Tears down the iframe and all listeners. Safe to call repeatedly. | | getLocale() | WasCashLocale | Returns the resolved locale. | | getContainer() | HTMLElement | Returns the resolved container element. |

mount() can only be called once per instance. Call destroy() first to remount (e.g. to retry a fresh session).

Events

Subscribe with on(event, callback). Each callback receives an optional payload emitted from inside the iframe.

| Event | Fired when | | ----------- | ----------------------------------- | | success | Payment completed successfully. | | failed | Payment was attempted but failed. | | cancelled | The user cancelled the payment. |

In frameworks like React or Vue, call off() (or destroy()) on unmount to avoid duplicate listeners across re-renders.

function handleSuccess(payload) {
  /* ... */
}

wascash.on('success', handleSuccess)
wascash.off('success', handleSuccess) // pass the same reference

TypeScript

import WasCash, { WasCashConfig, WasCashEvent, WasCashLocale } from '@wascash/sdk'

Error Handling

The SDK throws WasCashError, which carries a machine-readable code. Both WasCashError and the ErrorCodes map are exported.

import WasCash, { WasCashError, ErrorCodes } from '@wascash/sdk'

try {
  await wascash.mount()
} catch (e) {
  if (e instanceof WasCashError && e.code === ErrorCodes.NETWORK_ERROR) {
    // show an offline / retry message
  }
}

| Code | Thrown by | Description | | ----------------------- | ------------- | ------------------------------------------ | | MISSING_SESSION_ID | constructor | sessionId is missing or not a string | | MISSING_CLIENT_SECRET | constructor | clientSecret is missing or not a string | | MISSING_CONTAINER | constructor | container is missing | | CONTAINER_NOT_FOUND | constructor | CSS selector matched no DOM element | | INVALID_LOCALE | constructor | Unsupported locale value | | ALREADY_MOUNTED | mount() | mount() was called more than once | | MOUNT_FAILED | mount() | Initialize endpoint returned an error | | NETWORK_ERROR | mount() | The WasCash API could not be reached |

mount() may also reject with a backend-provided code (e.g. SESSION_EXPIRED, INVALID_CLIENT_SECRET) surfaced through the same WasCashError.code.

Development

npm install
npm test
npm run build