Wajub Components
Browser packages that embed Wajub checkout or compose your own payment fields.
Four npm packages put Wajub's payment interface inside your own site. @wajub/js holds everything,
and the React, Vue and Svelte packages are thin wrappers over it. All four are published at 1.4.0,
ship as ES modules only, and load their runtime from https://js.wajub.com.
Four ways to take a payment
They differ on one question: who draws the pay button.
| Mode | Call | Who draws the pay button | You get |
|---|---|---|---|
| Redirect | checkout() | Wajub | The hosted page, on a Wajub URL |
| Inline embed | mount() | Wajub | The hosted page inside your own layout |
| Overlay | open() | Wajub | The same, in a modal over your page |
| Payment fields | components() | You | Individual fields you place yourself, then confirmPayment() |
The first three run the whole checkout, including coupons, shipping, OTP and 3D Secure. Payment fields give you the layout and hand back the parts Wajub must own, with the limits that come with it.
Start with the inline embed
mount() keeps the customer on your page and costs you nothing in behaviour: the checkout still
handles every method, every challenge and every edge case. Move to payment fields when the layout
itself is the requirement.
There are five field types: card, mobileMoney, wallet, payment, and address.
A session comes first
Nothing renders without a session token. There are two ways to get one, and they are not equally safe.
| Where it is created | With | Cost |
|---|---|---|
| Your server | A secret key, sk. | The amount is decided by code the customer cannot reach |
| The browser | A publishable key, pk. | One call, no backend, and the amount comes from the page |
POST /payments answers with authorization_url, authorization_token and the transaction. The
token is a tok_ value, and it is what the browser calls sessionId.
A secret key in a browser is refused and reported
Any request carrying sk. or sk_test. with an Origin or Referer header is answered 403,
and the key's owner receives an alert by email. The block is deliberate. Use pk. in the browser,
or create the session on your server and send only the token.
Packages
The core package holds the loader and the types. Everything else builds on it, and
@wajub/js is where its own behaviour is documented.
npm install @wajub/jsA framework wrapper needs the core beside it, because @wajub/js is a peer dependency rather than a
bundled one. The three expose the same surface in framework syntax: a WajubProvider, a
CheckoutEmbed, and one component per field type.
npm install @wajub/react @wajub/jsInstall, configure and every prop
Without a bundler, load the script directly. The ESM build is the same runtime with named exports.
<script src="https://js.wajub.com"></script>
<!-- or, as a module -->
<script type="module">
import { mount } from 'https://js.wajub.com/wajub.mjs';
</script>The smallest working integration
Create the session on your server, pass the token to the page, mount.
curl https://api.wajub.com/payments \
-H "Authorization: sk.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i…" \
-H "Content-Type: application/json" \
-d '{"amount": 25000, "currency": "XAF", "callback": "https://shop.example.com/return"}'Send authorization_token to the browser, and nothing else. The token is scoped to that one
payment, so it is safe there.
import { mount } from '@wajub/js';
await mount('#checkout', {
sessionId: authorizationToken,
onSuccess: () => (window.location.href = '/thanks'),
onError: (error) => showRetry(error),
});The imported helpers load the runtime themselves. If you would rather hold the runtime, loadWajub()
returns { wajub, Wajub, WajubError } and you call rt.wajub.mount(…) on it.
Everything resolves to null on the server
loadWajub() and the helpers return null when there is no window, so a server render never
throws. Importing @wajub/js still fetches the script as a side effect: for a framework that
cares, import from @wajub/js/pure and load when you choose.
Where the rest is documented
| You want to | Read |
|---|---|
| See it working end to end | Quickstart |
| Create and secure the session | Sessions and security |
| Mount, open or redirect, with every callback | Hosted checkout |
| Build your own layout around the fields | Payment fields |
| Change colours, theme and locale from the page | Appearance |
| Change the logo and the palette for every session | Branding |
| Read the full method and type listing | API reference |
| Type it correctly | TypeScript |
| Copy a whole shape | Use cases |
| Work out why nothing renders | Troubleshooting |