Mobile SDKs

Wajub's mobile SDKs let you take Mobile Money, card and wallet payments in your app, with a ready-made payment sheet. Pick the package for your platform below.

Pick your platform

The sheet offers Mobile Money, cards and one-tap wallets. Other payment methods, such as bank transfer or crypto, are not offered in it.

How a payment flows

Your server                            Your app
───────────                            ────────
POST /payments with sk.
  returns authorization_token   ──▶    present({ sessionToken })
                                         │
                                         ├─ the payer picks a method and pays
                                         ├─ approval, confirmation step or payment page
                                         └─ the sheet waits for the outcome
                                             │
                                         complete · processing · failed · cancelled
webhook payment.succeeded
  fulfils the order

The token is the only credential the app ever holds. It is scoped to one payment, it expires, and it cannot list, refund or read anything else on your account. Your secret key stays on your server.

States

Each state is a screen of the sheet, and your onStateChange callback receives its name.

SUCCESS, EXPIRED and CANCELLED are final. A payment that is already paid when the sheet opens shows the success screen, and one that has ended shows a notice and reports a load error.

Results

The call that presents the sheet resolves exactly once, when the sheet closes, with one of four results.

The call never hangs. When the screen that presented the sheet goes away, it resolves cancelled before any payment, processing once one started and complete after a success, and it does not cancel the payment. Presenting a second sheet while one is open fails with sheet_already_presented. If the system kills your app, nothing resolves: at the next launch, read the outcome on your server.

Cancelling and closing

The payer closes the sheet with its close button or a swipe.

A cancelled payment is cancelled for good, and Wajub sends the payment.cancelled webhook. With cancelOnDismiss: false, closing before paying leaves the payment open, so you can present the sheet again with the same token.

The sheet never shows a failure when it cannot be sure of the outcome: it shows "Payment in progress" and keeps waiting. Closed then, it resolves processing.

Mobile Money

One form covers every operator. The payer picks the country and the operator and types the number, formatted as they type it. The number's prefix preselects its operator, and a number that belongs to another operator is flagged before anything is sent. After Pay, the sheet asks the payer to approve the payment on their phone, or to dial a code, and waits for the outcome.

Some operators, such as Orange Money in Burkina Faso, take a payment only with a code the payer generates in the operator's menu first. On Flutter, React Native and Android, the form says so when Wajub knows it in advance; either way, after Pay the sheet shows how to get the code, the code to dial and the exact amount to enter, then takes the code. A code the operator refuses can be entered again, with the tries left when they are known; after three refusals the payer is back on the form to pay another way.

Wherever the sheet shows an amount, on Pay and on each screen, it is what the payer pays: the payment's amount, plus the Wajub fee when the payer bears it (bearer: customer). On Flutter, React Native and Android, it follows the method or operator the payer picks.

Cards

Depending on the payment, the payer pays by card in one of three places.

• Stripe's card form, inside the sheet. Built into the Flutter and Android SDKs. React Native needs the optional @stripe/stripe-react-native package, and on iOS your app provides a CardCollector built with Stripe's SDK. Each platform page shows what to add.
• A secure page of the payment provider, opened in the browser. Set returnUrl to an https universal link or app link into your app to bring the payer back. Without it, the payer comes back to your app by hand, and Continue payment reopens the page.
• Wajub's test card form, in sandbox.

In live, the card number is typed only into Stripe's form or the provider's page.

Confirmation steps

Some card payments ask the payer for one more thing after Pay. Each step has its own screen.

A wrong answer keeps the screen and shows the attempts left. A step that expires or runs out of attempts ends on the failure screen.

Appearance

The appearance option sets the sheet's look. Its keys, presets and variables are on Appearance.

• Scheme. light, dark or auto, which follows the phone.
• Presets. stripe, night, flat and none.
• Your app's theme. inherit: true picks up your app's colours; each platform page says what it reads.
• Merchant branding. What you leave unset comes from the merchant's branding in the Dashboard: logo, business name and colours. A white-label merchant hides "Secured by Wajub".
• Fonts. A fontFamily is used only if your app ships the font.
• Loading. loader is a skeleton or a spinner. readyTimeout, 15 seconds by default, is how long the sheet may load before it shows an error with Retry.

Errors

Every failure is a WajubError.

React Native writes these fields in snake_case: decline_code, correlation_id, retry_after_seconds, block_reference.

A code not listed here, a bank's own decline code for instance, can reach you too: show message. Field errors, an invalid phone number for instance, stay on the form and never reach onError.

Privacy

The four SDKs, Flutter, React Native, Android and iOS, send the same data. When the payer pays, the SDK sends Wajub what the payment needs and, for fraud prevention, basic information about the device and a random install identifier, which is not the advertising identifier. When the payer uses Stripe's card form, Stripe's SDK also collects what Stripe documents for its own fraud checks.

Declare it next to what your app collects on its own.

For the App Store privacy labels, declare it linked to the user, not used for tracking, for App Functionality, which covers processing the payment and preventing fraud.

The iOS SDK ships a privacy manifest, which Xcode includes in your app's privacy report.

For Google Play data safety, declare it collected for App functionality and Fraud prevention, security, and compliance, shared with Wajub as your payment processor, encrypted in transit.

Testing

A payment your server creates with a sandbox key puts the whole flow in sandbox, sheet included, and the sheet shows a "Test mode" badge. Nothing changes in the app. The test numbers and cards are on Test scenarios.