Svelte

@wajub/svelte wraps @wajub/js in Svelte syntax: a provider that loads the runtime once, five field components, and four helpers built on stores. The payment API itself does not change, so the behaviour of every option is documented on Hosted checkout and Payment fields. This page covers what is specific to Svelte.

Install

@wajub/js is a peer dependency, not a bundled one, so it goes on the same line. The package is ESM only and ships its components as source, under a svelte export condition: your project's own Svelte compiles them, so the same package serves Svelte 4 and Svelte 5.

npm install @wajub/svelte @wajub/js

The components are written without runes, which both versions compile: Svelte 5 compiles them in legacy mode, file by file. A Svelte 5 project that forces runes on every file stops its build at Cannot use export let in runes mode, so force them on your own files only, as npx sv create does.

compilerOptions: {
  runes: ({ filename }) =>
    filename.split(/[/\\]/).includes('node_modules') ? undefined : true,
},

In a component written with runes, listen to the field components with on:ready and on:instance as below: they dispatch Svelte events, not callback props.

The provider

WajubProvider calls loadWajub() from @wajub/js/pure and puts the runtime in Svelte context. One provider covers a whole subtree, so it belongs at the layout level rather than around each component.

<script lang="ts">
  import { WajubProvider } from '@wajub/svelte';
</script>

<WajubProvider>
  <slot />
</WajubProvider>

Stores and helpers

Everything reactive here is a Svelte store, so read it with $ in the template.

<script lang="ts">
  import { useWajubOptional } from '@wajub/svelte';

  export let sessionId: string;
  const runtime = useWajubOptional();
</script>

<button
  disabled={!$runtime}
  on:click={() => $runtime?.wajub.open({ sessionId, onSuccess: onUpgraded })}
>
  Upgrade plan
</button>

The store is what makes this button work: it holds null when the component is created, because the provider only starts loading once it is mounted, and it fills when the runtime arrives. Read it with $, like every other store on this page.

useWajubContext() returns the same { runtime, loading, error } stores if you would rather build your own helper on top. It is an alias of getWajubContext(), and setWajubContext() is what the provider itself calls.

CheckoutEmbed

The hosted checkout inside your own layout. Every EmbeddedConfig option is a prop, and so is every callback.

<script lang="ts">
  import { CheckoutEmbed } from '@wajub/svelte';

  export let sessionId: string;
</script>

{#key sessionId}
  <CheckoutEmbed
    {sessionId}
    layout="tabs"
    minHeight={480}
    onSuccess={() => (window.location.href = '/order/complete')}
    onError={(error) => console.error(error.code, error.message)}
  />
{/key}

Wrapping in {#key sessionId} is what rebuilds the embed for a second session, and keeping the instance from onReady is what lets you restyle it without rebuilding.

<script lang="ts">
  import type { CheckoutInstance } from '@wajub/js';
  import { CheckoutEmbed } from '@wajub/svelte';

  export let sessionId: string;
  export let dark = false;

  let checkout: CheckoutInstance | null = null;

  $: checkout?.update({ appearance: { colorScheme: dark ? 'dark' : 'light' } });
</script>

{#key sessionId}
  <CheckoutEmbed {sessionId} onReady={(instance) => (checkout = instance)} />
{/key}

Payment fields

Five components render one field group each: CardComponent, MobileMoneyComponent, WalletComponent, PaymentComponent and AddressComponent. They share the props of ComponentConfig, and each one is ComponentEmbed with its type already set. Use ComponentEmbed directly when the choice is made at runtime.

<script lang="ts">
  import type { ComponentInstance } from '@wajub/js';
  import { AddressComponent, PaymentComponent, useConfirmPayment } from '@wajub/svelte';

  export let sessionId: string;

  const { confirm, isConfirming } = useConfirmPayment(sessionId);
  let field: ComponentInstance | null = null;
</script>

<AddressComponent {sessionId} addressMode="shipping" />
<PaymentComponent
  {sessionId}
  collectAddress="shipping"
  collectName
  on:instance={(event) => (field = event.detail)}
/>
<button disabled={$isConfirming || !field} on:click={() => field && confirm(field)}>
  {$isConfirming ? 'Processing…' : 'Pay now'}
</button>

useConfirmPayment guards against a double submission, so a second click while $isConfirming is true is ignored. It resolves with { status } and rejects with a WajubError, including confirmation_timeout after 60 seconds.

Types

Every helper is fully typed, and so is everything @wajub/js exports. From 1.6.0 the components are too: each one ships a declaration generated from its props, read by your editor and by svelte-check in Svelte 4 and Svelte 5 alike.

import type { AppearanceConfig, CheckoutLayout } from '@wajub/js';

const appearance: AppearanceConfig = { primaryColor: '#0f172a', labels: 'floating' };
const layout: CheckoutLayout = 'tabs';

SvelteKit

The session is created on your server. Nothing in this package needs a secret key, and nothing should ever receive one.

import { json } from '@sveltejs/kit';
import { WAJUB_API_KEY } from '$env/static/private';
import { Wajub } from '@wajub/node';
import type { RequestHandler } from './$types';

const wajub = new Wajub({ secretKey: WAJUB_API_KEY });

export const POST: RequestHandler = async ({ request }) => {
  const { cartId } = await request.json();

  const payment = await wajub.payments.create(
    {
      amount: 25000,
      currency: 'XAF',
      description: `Cart ${cartId}`,
      customer: { email: '[email protected]' },
      metadata: { cart_id: cartId },
    },
    { idempotencyKey: `cart-${cartId}` },
  );

  return json({ sessionId: payment.authorization_token });
};

Two more things SvelteKit asks for:

• Turn off server rendering on checkout routes with export const ssr = false in +page.ts, or mount the embed inside an {#if browser} block. The runtime needs a window.
• Put WajubProvider in +layout.svelte so a navigation inside the checkout flow does not reload the runtime.

What the package exports

The package declares two types: WajubContextValue and, from 1.6.0, WajubRuntimeStore, which is what useWajubOptional() returns.