Paystack Android
This is a library for easy integration of Paystack with your Android application. Use this library in your Android app so we shoulder the burden of PCI compliance by helping you avoid the need to send card data directly to your server. Instead, this library sends credit card data directly to our servers.
Summarized flow
-
Collect user's card details
-
Initialize the transaction
- App prompts your backend to initialize a transaction
- Your backend returns
access_codewe return when it calls the Initialize Transaction endpoint - App provides the
access_codeand card details to our SDK'schargeCardfunction viaChargeobject
-
SDK prompts user for PIN, OTP or Bank authentication as required
-
Once successful, we'll send an event to your webhook URL and call
onSuccesscallback. You should give value via webhook.
Requirements
- Android SDKv16 (Android 4.1 "Jelly Bean") - This is the first SDK version that includes
TLSv1.2which is required by our servers. Native app support for user devices older than API 16 will not be available.
Installation
Android Studio (using Gradle)
You do not need to clone this repository or download the files. The latest build is available on Maven Central Add the following lines to your app's build.gradle:
dependencies {
implementation 'co.paystack.android:paystack:3.1.3'
}
From version
3.0.18, the Pinpad library comes as part of this library and does not need to be explicitly included in your dependencies.
You should also add Java 8 support in your build.gradle:
android {
// ... Other configuration code
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
// For kotlin codebases, include
kotlinOptions {
jvmTarget = "1.8"
}
}
Eclipse
To use this library with Eclipse, you need to:
- Clone the repository.
- Import the paystack folder into your Eclipse project
- In your project settings, add the paystack project under the Libraries section of the Android category.
Usage
0) Prepare for use
To prepare for use, you must ensure that your app has internet permissions by making sure the uses-permission line below is present in the AndroidManifest.xml.
<uses-permission android:name="android.permission.INTERNET" />
1) Initialize SDK
To use the Paystack Android SDK, you need to first initialize it using the PaystackSdk class.
public class App extends Application{
@Override
public void onCreate() {
super.onCreate();
PaystackSdk.initialize(getApplicationContext());
}
}
Make sure to call this method in the onCreate method of your Fragment or Activity or Application.
2) Set your Public Key
Before you can charge a card with the PaystackSdk class, you need to set your public key. The library provides two approaches:
a) Add the following lines to the <application></application> tag of your AndroidManifest.xml
<meta-data
android:name="co.paystack.android.PublicKey"
android:value="pk_your_public_key"/>
You can obtain your public key from your Paystack dashboard.
b) Set the public key by code
This can be done anytime in your code. Just be sure to initialize before calling chargeCard.
class Bootstrap {
public static void setPaystackKey(String publicKey) {
PaystackSdk.setPublicKey(publicKey);
}
}
3) Collect and validate card details
At this time, we expect you to provide fields on your activity that collect the card details. Our Card class allows you collect and verify these. The library provides validation methods to validate the fields of the card.
card.validNumber
This method helps to perform a check if the card number is valid.
card.validCVC
Method that checks if the card security code is valid.
card.validExpiryDate
Method checks if the expiry date (combination of year and month) is valid.
card.isValid
Method to check if the card is valid. Always do this check, before charging the card.
card.getType
This method returns an estimate of the string representation of the card type.
public class MainActivity extends AppCompatActivity {
// This sets up the card and check for validity
// This is a test card from paystack
String cardNumber = "4084084084084081";
int expiryMonth = 11; //any month in the future
int expiryYear = 18; // any year in the future. '2018' would work also!
String cvv = "408"; // cvv of the test card
Card card = new Card(cardNumber, expiryMonth, expiryYear, cvv);
if (card.isValid()) {
// charge card
} else {
//do something
}
}
4) Charge Card
Charging with the PaystackSdk is quite straightforward.
Parameters for the chargeCard function
-
Activity - The first argument to the
PaystackSdk.chargeCardis the calling Activity object. Always give an Activity that will stay open till the end of the transaction. The currently open Activity is just fine. -
Charge - This object allows you provide information about the transaction to be made. Before calling
chargeCard, you should do acharge.setCard(card). The charge can then be used in either of 2 ways- Resume an initialized transaction: If employing this flow, you would send all required parameters for the transaction from your backend to the Paystack API via the
transaction/initializecall - documented here. The response of the call includes anaccess_code. This can be used to charge the card by doingcharge.setAccessCode({value from backend}). Once an access code is set, the only other parameter relevant to the transaction is the card. Others will be ignored. - Initiate a fresh transaction on Paystack: Using the functions:
setCurrency,setPlan,setSubaccount,setTransactionCharge,setAmount,setEmail,setReference,setBearer,putMetadata,putCustomField, you can set up a fresh transaction directly from the SDK. Documentation for these parameters are same as fortransaction/initialize.
- Resume an initialized transaction: If employing this flow, you would send all required parameters for the transaction from your backend to the Paystack API via the
-
Transaction Callback - When an error occurs or transaction concludes successfully, we will call the methods available in the callback you provided.
OnSuccesswill be called once the charge succeeds.beforeValidateis called every time the SDK needs to request user input. This function currently only allows the app know that the SDK is requesting further user input.OnErroris called if an error occurred during processing. Some Exception types that you should watch include- ExpiredAccessCodeException: This would be thrown if the access code has already been used to attempt a charge.
- ChargeException: This would be thrown if the charge failed. It would hold the message from the server.
public class MainActivity extends AppCompatActivity {
// This is the subroutine you will call after creating the charge
// adding a card and setting the access_code
public void performCharge(){
//create a Charge object
Charge charge = new Charge();
charge.setCard(card); //sets the card to charge
PaystackSdk.chargeCard(MainActivity.this, charge, new Paystack.TransactionCallback() {
@Override
public void onSuccess(Transaction transaction) {
// This is called only after transaction is deemed successful.
// Retrieve the transaction, and send its reference to your server
// for verification.
}
@Override
public void beforeValidate(Transaction transaction) {
// This is called only before requesting OTP.
// Save reference so you may send to server. If
// error occurs with OTP, you should still verify on server.
}
@Override
public void onError(Throwable error, Transaction transaction) {
//handle error here
}
});
}
}
Note that once
chargeCardis called, the SDK may prompt the user to provide their PIN, an OTP or conclude Bank Authentication. These are currently being managed entirely by the SDK. Your app will only be notified via thebeforeValidatefunction of the callback when OTP or Bank Authentication is about to start.
5) Verifying the transaction
Send the reference to your backend and verify by calling our REST API. An authorization will be returned which will let you know if its code is reusable. You can learn more about our Verify Transaction endpoint.
Below is a sample authorization object returned along with the transaction details:
{
"status": true,
"message": "Verification successful",
"data": {
"amount": 10000,
"currency": "NGN",
"transaction_date": "2017-04-06T21:28:41.000Z",
"status": "success",
"reference": "d68rbovh4a",
"domain": "live",
"metadata": {
"custom_fields": [
{
"display_name": "Started From",
"variable_name": "started_from",
"value": "sample charge card backend"
},
{
"display_name": "Requested by",
"variable_name": "requested_by",
"value": "some person"
},
{
"display_name": "Server",
"variable_name": "server",
"value": "some.herokuapp.com"
}
]
},
"gateway_response": "Approved",
"message": "Approved",
"channel": "card",
"ip_address": "41.31.21.11",
"log": null,
"fees": 150,
"authorization": {
"authorization_code": "AUTH_blahblah",
"bin": "412345",
"last4": "6789",
"exp_month": "10",
"exp_year": "2345",
"channel": "card",
"card_type": "mastercard debit",
"bank": "Some Bank",
"country_code": "NG",
"brand": "mastercard",
"reusable": true,
"signature": "SIG_IJOJidkpd0293undjd"
},
"customer": {
"id": 22421,
"first_name": "Guava",
"last_name": "Juice",
"email": "[email protected]",
"customer_code": "CUS_6t6che6w8hmt",
"phone": "",
"metadata": {},
"risk_action": "default"
},
"plan": null
}
}
To reuse the authorization gotten from charging this customer in future, you need to do 2 tests:
- In the sample JSON above, you can conclude that the transaction was successful because
data.status="success". This means the authorization is active. - Confirm that the authorization is reusable by checking
data.authorization.reusablewhich is true in this case. Once both pass, you can save the authorization code against the customer's email.
6) Charging a card authorization from your server in future
To charge an authorization saved from concluding chargeCard, you need its authorization code and the customer's email. Our Recurring Charge documentation provides more information about charging an authorization.
Testing your implementation
You can (and should) test your implementation of the Paystack Android library in your Android app. You need the details of an actual debit/credit card to do this, so we provide ##test cards## for your use instead of using your own debit/credit cards. Kindly reference our Test Payments documentation for test cards.
To try out the OTP flow, we have provided a test "verve" card:
50606 66666 66666 6666
CVV: 123
PIN: 1234
TOKEN: 123456
Remember to use all test cards only with test keys. Also note that all bank issued cards will be declined in test mode.
Building the example project
- Clone the repository.
- Import the project either using Android Studio or Eclipse
- Deploy a sample backend from PaystackJS-Sample-Backend (PHP) or Sample charge card backend (NodeJS heroku single click deploy)
- Copy the endpoints from the deployed backend to your
MainActivity.javafile. In the case ofverify, only copy up to the/before the: - Add your public key to your
MainActivity.javafile- Note that the public key must match the secret key, else none of the transactions will be attempted
- Build and run the project on your device or emulator
FAQs
Is authorization_code (https://developers.paystack.co/reference#charging-returning-customers) the same as the access_code)?
No
Where do I get an access_code?
Initialize a transaction : https://developers.paystack.co/reference#initialize-a-transaction
Where do I get an authorization_code?
Verify a successful transaction : https://developers.paystack.co/reference#verify-transaction
If I’m trying to use the Android SDK to charge someone who we’ve previously charged, can I use the authorization_code?
You don't need the SDK to charge an authorization code. It doesn't even know of its existence. Rather, use our charge endpoint: https://developers.paystack.co/reference#charge-authorization
Security
If you discover any security related issues, please email [email protected] instead of using the issue tracker.
Contact
For more enquiries and technical questions regarding the Android PaystackSdk, please post on our issue tracker: https://github.com/PaystackHQ/paystack-android/issues.
Change log
Please see CHANGELOG for more information what has changed recently.
165 Jan 4, 2023
2 Jan 20, 2022
13 Dec 31, 2022
121 Dec 2, 2022
0 Nov 9, 2021
501 Dec 30, 2022
2 Jun 2, 2022
251 Jan 2, 2023
15 Dec 8, 2022
23 Dec 27, 2022
5 Jul 15, 2022
633 Jan 7, 2023
16 Oct 13, 2022
4 Mar 30, 2022
42 Dec 17, 2022
32 Dec 15, 2022
26 Nov 10, 2022
79 Dec 22, 2022
8 Sep 16, 2022