Wajub Components
Browser packages that embed Wajub checkout or compose your own payment fields.
Wajub Components put Wajub's payment interface inside your own site: @wajub/js on any page, and
@wajub/react, @wajub/vue, @wajub/svelte and @wajub/angular in those frameworks. They ship as
ES modules only.
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 | Pick it when |
|---|---|---|---|---|
| Redirect | checkout() | Wajub | The hosted page, on a Wajub URL | You want the least front end code |
| Inline embed | mount() | Wajub | The hosted page inside your own layout | The checkout is the page |
| Overlay | open() | Wajub | The same, in a modal over your page | The checkout interrupts something else |
| Payment fields | components() | You | Individual fields you place yourself, then confirmPayment() | The layout itself is the requirement |
The first three run the whole checkout, including OTP and 3D Secure. Coupons and the shipping step are not available on it. 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 seven field types: card, mobileMoney, wallet, bankTransfer, crypto, payment,
and address. Each has its own component, CardComponent to CryptoComponent in React, Vue and
Svelte, <wajub-card> to <wajub-crypto> in Angular, and ComponentEmbed, <wajub-component> in
Angular, mounts any of them by its type.
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. or pk_test. | 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 what the browser calls sessionId.
A secret key in a browser is refused and reported
A secret key must never be used from a browser: it is refused with 403, and the key's owner is
emailed. The block is deliberate. Use a publishable key in the
browser, or create the session on your server and send only the token.
Packages
@wajub/js works on any page, with or without a framework.
npm install @wajub/jsA framework package needs @wajub/js installed beside it, as a peer dependency. React, Vue and
Svelte give you a WajubProvider, a CheckoutEmbed and one component per field type. Angular gives
you provideWajub(), a service, and a standalone component for the checkout and for each field
type.
npm install @wajub/react @wajub/jsInstall, configure and every prop
Without a bundler, load the script directly, or import the module build.
<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_test.xxxxxxxxxxxxxxxx…" \
-H "Content-Type: application/json" \
-d '{
"amount": 25000,
"currency": "XAF",
"email": "buyer@example.com",
"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),
});To choose when Wajub.js loads, call loadWajub() instead: it 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 loads Wajub.js as a side effect: to avoid that, import from
@wajub/js/pure and call loadWajub() 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 | Display the 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 | SDK reference |
| Type it correctly | TypeScript |
| Copy a whole shape | Use cases |
| Work out why nothing renders | Troubleshooting |