Troubleshooting

Common Wajub Components integration issues and fixes.

6 min read

Symptom	Likely cause	Fix
Empty embed	Invalid or expired `sessionId`	Verify token from `POST /payments`; listen to `onLoadError`
"Embed misconfigured"	Manual checkout URL / iframe	Use `wajub.mount()` or framework `CheckoutEmbed`
No callbacks firing	SDK not loaded / SSR	Call `loadWajub()` in browser only; use `"use client"`
`complete` always false	Missing email or invalid fields	Listen to `change`; ensure `customer.email` on session
`confirmPayment` rejected (wallet)	Wallet uses native button	Do not call `confirmPayment` for `wallet` — use Apple/Google Pay UI
OTP not working	Payment-field limitation	Switch to hosted checkout
Embed height clipped	Parent `overflow: hidden`	Let `onResize` adjust height; check CSS
`sk_…` error in browser	Secret key in frontend	Use `pk_` client-side; `sk_` server-side only
CORS on createPayment	Direct API call from browser	Create session on your backend
Method unavailable	Session lacks that channel	Call `fetchSession()` before mount
Payment not confirmed	Trusting `onSuccess` only	Verify via webhook or `GET /payments/{id}`

Debug checklist

Session created with sk_… on server — token returned to client?
Container has min-height: 480px during load?
onError and onLoadError handlers implemented?
Site served over HTTPS (production)?
Using SDK — not a copied pay.wajub.com URL?

Sandbox

Use pk_test_… / sk_test_…. Sandbox checkout shows a TEST banner and developer tools.

const { environment } = Wajub.parsePublishableKey('pk_test_...');
console.log(environment); // "sandbox"

Test cards and Mobile Money numbers: Test scenarios.

Production checklist

@wajub/js or CDN script loaded client-side
Integration via mount() / components() — no manual URLs
onSuccess updates UX; webhook confirms order
onError / onLoadError handled
onBreakdown syncs cart (inline hosted)
HTTPS on merchant site and callback
Live test with small amount after sandbox

Still stuck?

Contact support@wajub.com with your session reference (not your secret key), the merchant domain, and any onLoadError message.

Edit this page on GitHub

Need help?

Contact support GitHub Discussions Service Status

Symptom

Likely cause

Fix

Empty embed

Invalid or expired sessionId

Verify token from POST /payments; listen to onLoadError

"Embed misconfigured"

Manual checkout URL / iframe

Use wajub.mount() or framework CheckoutEmbed

No callbacks firing

SDK not loaded / SSR

Call loadWajub() in browser only; use "use client"

complete always false

Missing email or invalid fields

Listen to change; ensure customer.email on session

confirmPayment rejected (wallet)

Wallet uses native button

Do not call confirmPayment for wallet — use Apple/Google Pay UI

OTP not working

Payment-field limitation

Switch to hosted checkout

Embed height clipped

Parent overflow: hidden

Let onResize adjust height; check CSS

sk_… error in browser

Secret key in frontend

Use pk_ client-side; sk_ server-side only

CORS on createPayment

Direct API call from browser

Create session on your backend

Method unavailable

Session lacks that channel

Call fetchSession() before mount

Payment not confirmed

Trusting onSuccess only

Verify via webhook or GET /payments/{id}

Production checklist

@wajub/js or CDN script loaded client-side

Integration via mount() / components() — no manual URLs

onSuccess updates UX; webhook confirms order

onError / onLoadError handled

onBreakdown syncs cart (inline hosted)

HTTPS on merchant site and callback

Live test with small amount after sandbox

Still stuck?

Contact support@wajub.com with your session reference (not your secret key), the merchant domain, and any onLoadError message.