Android SDK
The Android SDK provides UI components and methods that allow you to accept payments in your Android app.
Before you begin
Version 1.0.0 changes how you launch the payment sheet and requires compileSdk 37. If you're upgrading from a 0.0.x or 0.1.x release, follow the Android SDK 1.0.0 upgrade guide.
Introduction
The Android SDK is a collection of methods and interfaces that allow you to build a secure and convenient payment flow for your Android app. Integration is a two-step process:
- Initiate the transaction on the server
- Complete it on the SDK
Project requirements
The Paystack Android SDK supports Android 6.0 (API level 23) or later. We don't support OS versions below Android 6.0. Before using the SDK, you need to ensure your app meets the following requirements:
- Android 6.0 (API level 23) or later
compileSdk37 or later- Java 11 or later
- AndroidX
Installation
To use the SDK, add the paystack-ui dependency to the dependencies block of your app-level build file:
Latest dependency version
You should check Maven Central to get the latest version before installation.
- build.gradle
1dependencies {2 implementation 'com.paystack.android:paystack-ui:1.0.0'3}
paystack-ui includes paystack-core, so you don't need to add it separately. Ensure you sync the project to download the SDK into your project. After installation, you have access to the UI components and methods to accept payments in your Android app.
Paystack builder
The Paystack class holds your public key and SDK settings. You create it with a builder and pass it to the PaymentSheet each time you launch a payment. It's part of the core library:
- Kotlin
- Java
1import com.paystack.android.core.Paystack
The table below shows the methods available in the Paystack class:
| Method | Description |
|---|---|
setPublicKey("public-key") | This method is used to set the public key. Without a public key, you
can't complete a transaction: build() throws an exception if you don't set one. |
setLoggingEnabled(boolean) | Pass true to turn on debug logs. Logging is off by default. |
- Kotlin
- Java
1private val paystack = Paystack.builder()2 .setPublicKey("pk_domain_xxxxxxxx")3 .setLoggingEnabled(true)4 .build()5
The Paystack object holds no global state. You can create it at any point before you launch a payment, for example after you fetch your public key from your server.
Initialize transaction
The SDK requires an access_code to display the UI component that accepts payment. To get the access_code, make a POST request to the Initialize TransactionAPI endpoint from your server:
1curl https://api.paystack.co/transaction/initialize2-H "Authorization: Bearer YOUR_SECRET_KEY"3-H "Content-Type: application/json"5 "amount": "500000"6 }'7-X POST
1{2 "status": true,3 "message": "Authorization URL created",4 "data": {5 "authorization_url": "https://checkout.paystack.com/nkdks46nymizns7",6 "access_code": "nkdks46nymizns7",7 "reference": "nms6uvr1pl"8 }9}
On a successful initialization of the transaction, you get a response that contains an access_code. You need to return this access_code back to your mobile app.
Secret key safeguarding
Don't make an API request to the Initialize Transaction endpoint directly on your mobile app because it requires your secret key. Your secret key should only be used on your server where stronger security measures can be put in place.
Payment sheet
The PaymentSheet is the UI component that contains the payment form and the available payment channels. It blocks screenshots and screen recording while it's open. It's part of the UI library, which you import as shown below:
- Kotlin
- Java
1import com.paystack.android.ui.paymentsheet.PaymentSheet
Initialize PaymentSheet in the onCreate method of your Activity or Fragment. The constructor takes two arguments:
| Arguments | Example | Description |
|---|---|---|
| Activity | this | This is the reference to your Activity or Fragment. |
| Callback | paymentResult | This is the method that handles all post-payment processes. Its argument is a PaymentSheetResult. |
- Kotlin
- Java
1private lateinit var paymentSheet: PaymentSheet23override fun onCreate(savedInstanceState: Bundle?) {4 super.onCreate(savedInstanceState)5 setContentView(R.layout.activity_main)67 // library initialization code snippets and others go here89 paymentSheet = PaymentSheet(this, ::paymentComplete)1011 // more snippet12}
The PaymentSheet comes with a launch method that lets you trigger the display of the component. The launch method takes your Paystack object and the access_code from a previously initialized transaction.
- Kotlin
- Java
1fun makePayment() {2 // Pass access_code from transaction initialize call on the server3 paymentSheet.launch(paystack, "ACCESS_CODE")4}5
Jetpack Compose
In a composable, create the sheet with rememberPaymentSheet. It takes the callback and returns a PaymentSheet that lives as long as the composable:
- Kotlin
1@Composable2fun CheckoutScreen(paystack: Paystack, accessCode: String) {3 val paymentSheet = rememberPaymentSheet { result -> paymentComplete(result) }45 Button(onClick = { paymentSheet.launch(paystack, accessCode) }) {6 Text("Pay")7 }8}9
Payment sheet configuration
To change how the payment sheet looks or who it's shown to, pass a PaymentSheetConfig as the third argument to launch. The configuration applies to that payment only:
| Method | Description |
|---|---|
setThemeMode(ThemeMode) | Sets the sheet's appearance. The default, SYSTEM, follows the light or dark setting of the activity that launches the sheet. Use LIGHT or DARK if your app switches themes only inside Compose, because the SDK can't detect that. |
setDisplayAudience(DisplayAudience) | Specifies who holds the device. The default, CUSTOMER_FACING, is for customers paying on their own phone. Use MERCHANT_FACING when the merchant shows the screen to the customer, such as in a point-of-sale app. See display audience. |
- Kotlin
- Java
1val sheetConfig = PaymentSheetConfig.builder()2 .setThemeMode(PaymentSheetConfig.ThemeMode.DARK)3 .setDisplayAudience(PaymentSheetConfig.DisplayAudience.MERCHANT_FACING)4 .build()56paymentSheet.launch(paystack, "ACCESS_CODE", sheetConfig)7
Payment sheet result
The PaymentSheetResult exposes the different states of a transaction. It's the argument type for the PaymentSheet callback:
- Kotlin
- Java
1import com.paystack.android.ui.paymentsheet.PaymentSheetResult23private fun paymentComplete(paymentSheetResult: PaymentSheetResult) {45}
The states that PaymentSheetResult exposes are:
| State | Description |
|---|---|
Completed | The customer completed the payment process. This result contains paymentCompletionDetails, which includes the transaction reference. Use the reference to verify the transaction status and amount on your server before providing value. |
Cancelled | The customer closed the payment sheet. This includes closing the sheet after it shows an error that Paystack returned, for example when the access code is invalid or the transaction has no channel the SDK supports. The payment can still complete after the customer closes the sheet, for example a bank transfer that Paystack confirms later, so confirm the final status with your webhook. |
Failed | The payment sheet hit an error it can't recover from, such as a network failure or a card charge that timed out. The sheet shows an error message and closes itself after 2 seconds. This result contains an error, the underlying Throwable for your logs. It may also contain a reference. If it does, verify the transaction on your server, because the payment may still complete. |
- Kotlin
- Java
1private fun paymentComplete(paymentSheetResult: PaymentSheetResult) {2 val message = when (paymentSheetResult) {3 PaymentSheetResult.Cancelled -> "Cancelled"4 is PaymentSheetResult.Failed -> {5 Log.e("Something went wrong", paymentSheetResult.error.message.orEmpty(), paymentSheetResult.error)6 // If there's a reference, verify the transaction on your server. The payment may still complete.7 paymentSheetResult.reference?.let { Log.d("Payment reference", it) }8 paymentSheetResult.error.message ?: "Failed"9 }1011 is PaymentSheetResult.Completed -> {12 // Verify the transaction on your server with this reference before giving value13 Log.d("Payment successful", paymentSheetResult.paymentCompletionDetails.reference)14 "Successful"15 }16 }1718 Toast.makeText(this, "Payment $message", Toast.LENGTH_SHORT).show()19}
Payment channels
The payment sheet shows a payment channel when all three of these are true:
- You enabled the channel on your integration.
- The channel supports the transaction's currency.
- The SDK supports the channel.
If only one channel qualifies, the sheet opens it immediately. Otherwise, the customer chooses from a list. To limit the channels for a transaction, pass the channels parameter when you initialize the transactionAPI.
The sheet handles each channel's payment flow for you, then calls your callback with a PaymentSheetResult.
| Country | Currency | Payment channels |
|---|---|---|
| Nigeria | NGN | Card, Pay with Transfer, and Zap |
| Ghana | GHS | Card and mobile money (MTN, AirtelTigo, and Telecel) |
| Kenya | KES | Card, mobile money (M-PESA and Airtel Money), and Pesalink |
| Côte d'Ivoire | XOF | Card |
| South Africa | ZAR | Card, Capitec Pay, Scan to Pay, and SnapScan |
When a channel attempt fails, for example a declined card or an expired session, the sheet shows the reason and lets the customer try again or choose another channel. Your callback isn't called until the customer completes the payment or closes the sheet, or the sheet hits an unexpected error.
Google Pay
Google Pay appears as a button on the card screen when it's enabled on your integration and the customer's device can use it. It runs on the card channel, so leave Card enabled alongside it. You activate it on the Dashboard as described in activating Google Pay.
To offer Google Pay, add this entry inside the <application> element of your app's AndroidManifest.xml:
- AndroidManifest.xml
1<application>2 <!-- other application elements -->34 <meta-data5 android:name="com.google.android.gms.wallet.api.enabled"6 android:value="true" />7</application>8
If the entry is missing, the SDK hides Google Pay. With logging enabled, it also logs a warning. If a Google Pay payment fails, the sheet shows an error and the customer can pay with a card instead.
Google approval required
Google must approve your app before you can accept live Google Pay payments in it. Until then, Google Pay only works for test transactions, where the SDK uses Google's test environment and doesn't charge real cards.
To request approval, register your app on the Google Pay & Wallet Console:
- Sign in to the Google Pay & Wallet Console and complete your business profile.
- Go to Google Pay API > Integrations > Integrate with your Android app, then select your app. The console only lists apps published on Google Play under the Google Account you signed in with.
- Select Gateway as the integration type. Paystack is your payment gateway, so you don't need the PCI DSS compliance that a Direct integration requires.
- Test Google Pay in your app with a test transaction and take screenshots of the flow. Upload them, then click Submit for approval. Google's integration checklist lists the screenshots it needs.
After Google approves your app, you can accept live Google Pay payments from a build signed with your release key. For live transactions, the SDK uses Google's production environment. A debug-signed build can't make live Google Pay payments. For the full process, see Google's guide to publishing your integration.
Display audience
Zap works differently depending on who holds the device. Set the audience with setDisplayAudience in the payment sheet configuration:
| Channel | CUSTOMER_FACING (default) | MERCHANT_FACING |
|---|---|---|
| Zap | Open Zap app button | QR code to scan with Zap |