API DocumentationAPI Reference
API Documentation

Mobile SDKs FAQs

Answers to the most common questions about the payabl. Mobile SDKs for Android and iOS. For the full integration path, start with the Quick Start.

General

What are the Mobile SDKs?

The payabl. Mobile SDKs let you accept payments natively in your Android and iOS apps — through a Hosted Payment Page covering all payment methods in one integration, or standalone integrations of Pay by Card, Google Pay / Apple Pay, and Instant Bank Transfer. The SDK handles all sensitive payment data and cryptographic operations; your app only triggers flows using session credentials from your backend.

Where do I start?

Follow the Quick Start: try the demo apps, request SDK access, set up your server, then integrate your platform — Android or iOS.

What are the main differences between the Android and iOS SDKs?

Both offer the same payment methods and the same backend integration (/mobile/init). Platform differences: Android is installed via Gradle from GitHub Packages and uses callback lambdas; iOS is installed via Xcode and uses a delegate pattern (PBLPaymentPageTapDelegate, PBLErrorDelegate). Google Pay is Android-only; Apple Pay is iOS-only.

Can I try the SDK before requesting access?

Yes — the pre-built demo apps run against the sandbox with a pre-configured demo merchant, no account or access needed: Android demo | iOS demo.

Access & setup

How do I get access to the SDK?

Email [email protected] with your merchant ID and the GitHub usernames of your developers — one request covers the SDK and demo repositories for both platforms. Full steps: SDK Access Guide.

What development tools do I need?

Android: the latest stable Android Studio; the SDK supports API 28 (Android 9.0)+. iOS: Xcode; the SDK supports iOS 17.6+. See the requirements tables on the Android SDK and iOS SDK pages.

Do I need my own server?

Yes — payment sessions are created server-to-server via /mobile/init using your merchant secret, which must never be embedded in your app. See Setup Your Server. (The demo apps skip this only because they use a payabl.-hosted demo merchant.)

Payments

Can I reuse an SDK instance or session for multiple transactions?

No. Create a new session and initialize the SDK for each payment attempt — sessions must not be reused across payments or shared between users.

How do I integrate Google Pay or Apple Pay?

Both require one-time registration beyond the code integration — Google Pay needs your Google Merchant ID configured with payabl. and production access from Google; Apple Pay needs a certificate exchange with payabl. (separately for sandbox and production). See Google Pay and Apple Pay.

Why doesn't Instant Bank Transfer return to my app?

Instant Bank Transfer redirects the customer to their bank and returns via deep link — your /mobile/init request must include the redirect URLs and app_schema, and your app must be configured to handle the return. See Instant Bank Transfer — Android | iOS.

Saved cards

How do saved cards work?

When a customer pays by card, the SDK can securely save it and offer it on their next payment. The card is tokenized, and the token is stored encrypted on the customer's device, keyed to the customer identifier you pass (userId on Android, customerId on iOS). At payment time, the token is used to retrieve the correct card — your app and server never handle or store raw card data. To enable this, pass a stable, unique customer identifier in your payment configuration — the same value every time that customer pays. See the saved-cards notes on the Hosted Payment Page and Pay by Card guides.

Why don't my customer's saved cards appear?

Two common reasons:

  • A different, empty, or changing userId/customerId was passed — the identifier must consistently identify the same customer across sessions.
  • The customer is on a different device or reinstalled the app — saved-card tokens are stored on the device, so they don't carry over to new devices or fresh installs. The customer simply saves the card again on the next payment.

Testing & troubleshooting

How do I test my integration?

Use the sandbox environment end to end — test cards, the Instant Bank Transfer bank simulator, and wallet test setup are all on the Testing page.

What should I do if I encounter issues during integration?

Work through the Error Handling & Troubleshooting guide — reproduce in the sandbox, verify configuration and environment, check logs, and compare against the demo app.

How do I report a bug or get support?

Email [email protected] with the transaction_id or session_id of the affected payment, step-by-step reproduction, your merchant ID, platform and SDK version, and logs. These details let us locate the exact transaction and resolve your issue much faster.