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:

  1. Initiate the transaction on the server
  2. 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
  • compileSdk 37 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.

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:

1import com.paystack.android.core.Paystack

The table below shows the methods available in the Paystack class:

MethodDescription
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.
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:

Show Response
1curl https://api.paystack.co/transaction/initialize
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ "email": "[email protected]",
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:

1import com.paystack.android.ui.paymentsheet.PaymentSheet

Initialize PaymentSheet in the onCreate method of your Activity or Fragment. The constructor takes two arguments:

ArgumentsExampleDescription
ActivitythisThis is the reference to your Activity or Fragment.
CallbackpaymentResultThis is the method that handles all post-payment processes. Its argument is a PaymentSheetResult.
1private lateinit var paymentSheet: PaymentSheet
2
3override fun onCreate(savedInstanceState: Bundle?) {
4 super.onCreate(savedInstanceState)
5 setContentView(R.layout.activity_main)
6
7 // library initialization code snippets and others go here
8
9 paymentSheet = PaymentSheet(this, ::paymentComplete)
10
11 // more snippet
12}

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.

1fun makePayment() {
2 // Pass access_code from transaction initialize call on the server
3 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:

1@Composable
2fun CheckoutScreen(paystack: Paystack, accessCode: String) {
3 val paymentSheet = rememberPaymentSheet { result -> paymentComplete(result) }
4
5 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:

MethodDescription
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.
1val sheetConfig = PaymentSheetConfig.builder()
2 .setThemeMode(PaymentSheetConfig.ThemeMode.DARK)
3 .setDisplayAudience(PaymentSheetConfig.DisplayAudience.MERCHANT_FACING)
4 .build()
5
6paymentSheet.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:

1import com.paystack.android.ui.paymentsheet.PaymentSheetResult
2
3private fun paymentComplete(paymentSheetResult: PaymentSheetResult) {
4
5}

The states that PaymentSheetResult exposes are:

StateDescription
CompletedThe 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.
CancelledThe 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.
FailedThe 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.
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 }
10
11 is PaymentSheetResult.Completed -> {
12 // Verify the transaction on your server with this reference before giving value
13 Log.d("Payment successful", paymentSheetResult.paymentCompletionDetails.reference)
14 "Successful"
15 }
16 }
17
18 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:

  1. You enabled the channel on your integration.
  2. The channel supports the transaction's currency.
  3. 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.

CountryCurrencyPayment channels
NigeriaNGNCard, Pay with Transfer, and Zap
GhanaGHSCard and mobile money (MTN, AirtelTigo, and Telecel)
KenyaKESCard, mobile money (M-PESA and Airtel Money), and Pesalink
Côte d'IvoireXOFCard
South AfricaZARCard, 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:

1<application>
2 <!-- other application elements -->
3
4 <meta-data
5 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:

  1. Sign in to the Google Pay & Wallet Console and complete your business profile.
  2. 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.
  3. 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.
  4. 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:

ChannelCUSTOMER_FACING (default)MERCHANT_FACING
ZapOpen Zap app buttonQR code to scan with Zap