Android SDK
SDK for Android mobile apps integration.
We'll cover
- Downloading the SDK
- Installation
ā¢ 2.1. Adding the arr file in the libs folder
ā¢ 2.2. Adding a dependencies- Usage
ā¢ 3.1. import the following classes
ā¢ 3.2. insert your payment key
ā¢ 3.3. if you don't have a card token
ā¢ 3.4. if you have a card token- Results
- Screenshot from PaymentActivity
- Try our Sample app
1. Download the SDK from: [here]
2. Installation
ā¢ 2.1. Adding the arr file in the libs folder
ā¢ 2.2. Adding a dependencies
You need to add the dependency below.
dependencies {
implementation fileTree(include: ['*.jar', '*.aar'], dir: 'libs')
implementation 'androidx.appcompat:appcompat:1.2.0'
implementation 'com.google.android.material:material:1.3.0'
implementation 'androidx.constraintlayout:constraintlayout:2.0.4'
testImplementation 'junit:junit:4.+'
androidTestImplementation 'androidx.test.ext:junit:1.1.2'
androidTestImplementation 'androidx.test.espresso:espresso-core:3.3.0'
implementation 'morxander.editcard:EditCard:1.0.1'
implementation 'com.android.volley:volley:1.2.0'
}
3. Usage
The SDK has two functions to initiate the payment, one for purchase (user enters Card details) and another one for recurring payments (using a saved card token).
To start the SDK, an intent is sent with the below Extras to our PayActivity.
PAYMENT KEY
A valid payment key is required to start the payment. it's also sent with the intent Extras, which will be mentioned below.
Valid means Fresh(newly created), doesn't have pending transactions, the best to do is to create a new order for every payment key. To generate a payment key, check this link here.
ā¢ 3.1. import the following classes
// import the following
import com.paymob.acceptsdk.PayActivity;
import com.paymob.acceptsdk.PayActivityIntentKeys;
import com.paymob.acceptsdk.PayResponseKeys;
import com.paymob.acceptsdk.SaveCardResponseKeys;
import com.paymob.acceptsdk.ToastMaker;
ā¢ 3.2. insert your payment key
// insert your payment key in a paymentKey field
final String paymentKey = "";
ā¢ 3.3. if you don't have a card token
If you don't have a card token then you will need to send the following info
ā«ø Payment Key
ā«ø 3D secure
ā«ø The default to whether to save a card or not
ā«ø Whether or not to show the save card option (if you choose to hide it, then saving the card or not will be the default you set in the line above)
ā«ø The theme color(so that you can set it the same as your app)
| Parameter | Description |
|---|---|
| PAYMENT_KEY | This is the payment key you entered in 3.2 |
| THREE_D_SECURE_ACTIVITY_TITLE | |
| SAVE_CARD_DEFAULT | The default for whether to save a card or not |
| SHOW_SAVE_CARD | Whether or not to show the save card option (if you choose to hide it, then saving the card or not will be the default you set in the line above in (SAVE_CARD_DEFAULT) |
| THEME_COLOR | The theme color(so that you can set it the same as your app) |
| ACCEPT_PAYMENT_REQUEST | Arbitrary number and used only in this activity. Change it as you wish. |
Below is the first function that starts the PayActivity with no Card token. Also, it takes a boolean value to whether to display the Save Card checkbox or not.
Intent pay_intent = new Intent(this, PayActivity.class);
putNormalExtras(pay_intent);
// this key is used to save the card by deafult.
pay_intent.putExtra(PayActivityIntentKeys.SAVE_CARD_DEFAULT, false);
// this key is used to display the savecard checkbox.
pay_intent.putExtra(PayActivityIntentKeys.SHOW_SAVE_CARD, showSaveCard);
//this key is used to set the theme color(Actionbar, statusBar, button).
pay_intent.putExtra(PayActivityIntentKeys.THEME_COLOR,getResources().getColor(R.color.ThemeColor));
// this key is to wether display the Actionbar or not.
pay_intent.putExtra("ActionBar",true);
// this key is used to define the language. takes for ex ("ar", "en") as inputs.
pay_intent.putExtra("language","ar");
startActivityForResult(pay_intent, ACCEPT_PAYMENT_REQUEST);
Intent secure_intent = new Intent(this, ThreeDSecureWebViewActivty.class);
secure_intent.putExtra("ActionBar",true);
ā¢ 3.4. if you have a card token
this step depends if you have a card token or not
If you have a card token you will need to send the following information
ā Payment key
ā 3D Secure
ā Card Token
ā Masked pan number
ā The default for whether to save a card or not
ā Whether or not to show the save card option (if you choose to hide it, then saving the
card or not will be the default you set in the line above)
| Parameter | Description |
|---|---|
| PAYMENT_KEY | This is the payment key you entered in 3.2 |
| THREE_D_SECURE_ACTIVITY_TITLE | |
| TOKEN | You should use your actual card token |
| MASKED_PAN_NUMBER | Card masked Pan in case of the saved card. |
| SAVE_CARD_DEFAULT | The default for whether to save a card or not |
| SHOW_SAVE_CARD | Whether or not to show the save card option (if you choose to hide it, then saving the card or not will be the default you set in the line above in SAVE_CARD_DEFAULT) |
| THEME_COLOR | This key is used to set the theme color(Actionbar, statusBar, button). |
4. Results
Below is the function that starts the PayActivity with Card token. you will need to have the Customer's Card token ready.
Intent pay_intent = new Intent(this, PayActivity.class);
putNormalExtras(pay_intent);
// replace this with your actual card token
// this key is used to define the language. takes for ex ("ar", "en") as inputs.
pay_intent.putExtra("language","ar");
// replace this with your actual card token
pay_intent.putExtra(PayActivityIntentKeys.TOKEN, "6088c38c19705a495f1727561d4f4814b2ed7e45e9cd80c72f233253");
// card masked Pan in case of saved card.
pay_intent.putExtra(PayActivityIntentKeys.MASKED_PAN_NUMBER, "xxxx-xxxx-xxxx-1234");
// this key is used to save the card by deafult.
pay_intent.putExtra(PayActivityIntentKeys.SAVE_CARD_DEFAULT, false);
// this key is used to display the savecard checkbox.
pay_intent.putExtra(PayActivityIntentKeys.SHOW_SAVE_CARD, false);
pay_intent.putExtra("ActionBar",true);
//this key is used to set the theme color(Actionbar, statusBar, button).
pay_intent.putExtra(PayActivityIntentKeys.THEME_COLOR,getResources().getColor(R.color.ThemeColor));
// this is the customer billing data, it should be passed, when paying with a saved Card.
pay_intent.putExtra( PayActivityIntentKeys.FIRST_NAME, "Cliffo");
pay_intent.putExtra(PayActivityIntentKeys.LAST_NAME, "Nicol");
pay_intent.putExtra(PayActivityIntentKeys.BUILDING,"8028");
pay_intent.putExtra(PayActivityIntentKeys.FLOOR, "42");
pay_intent.putExtra(PayActivityIntentKeys.APARTMENT, "803");
pay_intent.putExtra(PayActivityIntentKeys.CITY, "Jask");
pay_intent.putExtra(PayActivityIntentKeys.STATE, "Uta");
pay_intent.putExtra(PayActivityIntentKeys.COUNTRY,"CR" );
pay_intent.putExtra(PayActivityIntentKeys.EMAIL, "[email protected]");
pay_intent.putExtra(PayActivityIntentKeys.PHONE_NUMBER, "+86(8)9135210487");
pay_intent.putExtra(PayActivityIntentKeys.POSTAL_CODE, "01898");
startActivityForResult(pay_intent, ACCEPT_PAYMENT_REQUEST);
}
The payment key is passed to the intent separately in both functions body or by using the below implementation
private void putNormalExtras(Intent intent) {
intent.putExtra(PayActivityIntentKeys.PAYMENT_KEY, paymentKey);
intent.putExtra(PayActivityIntentKeys.THREE_D_SECURE_ACTIVITY_TITLE, "Verification");
}
As a result of the above Activity Calls, you should be expecting the below values to be returned to the caller Activity. use these values to update your backend.
@Override
public void onActivityResult(int requestCode, int resultCode, Intent data) {
super.onActivityResult(requestCode, resultCode, data);
Bundle extras = data.getExtras();
if (requestCode == ACCEPT_PAYMENT_REQUEST) {
if (resultCode == IntentConstants.USER_CANCELED) {
// User canceled and did no payment request was fired
ToastMaker.displayShortToast(this, "User canceled!!");
} else if (resultCode == IntentConstants.MISSING_ARGUMENT) {
// You forgot to pass an important key-value pair in the intent's extras
ToastMaker.displayShortToast(this, "Missing Argument == " + extras.getString(IntentConstants.MISSING_ARGUMENT_VALUE));
} else if (resultCode == IntentConstants.TRANSACTION_ERROR) {
// An error occurred while handling an API's response
ToastMaker.displayShortToast(this, "Reason == " + extras.getString(IntentConstants.TRANSACTION_ERROR_REASON));
} else if (resultCode == IntentConstants.TRANSACTION_REJECTED) {
// User attempted to pay but their transaction was rejected
// Use the static keys declared in PayResponseKeys to extract the fields you want
ToastMaker.displayShortToast(this, extras.getString(PayResponseKeys.DATA_MESSAGE));
} else if (resultCode == IntentConstants.TRANSACTION_REJECTED_PARSING_ISSUE) {
// User attempted to pay but their transaction was rejected. An error occured while reading the returned JSON
ToastMaker.displayShortToast(this, extras.getString(IntentConstants.RAW_PAY_RESPONSE));
} else if (resultCode == IntentConstants.TRANSACTION_SUCCESSFUL) {
// User finished their payment successfully
// Use the static keys declared in PayResponseKeys to extract the fields you want
ToastMaker.displayShortToast(this, extras.getString(PayResponseKeys.DATA_MESSAGE));
} else if (resultCode == IntentConstants.TRANSACTION_SUCCESSFUL_PARSING_ISSUE) {
// User finished their payment successfully. An error occured while reading the returned JSON.
ToastMaker.displayShortToast(this, "TRANSACTION_SUCCESSFUL - Parsing Issue");
// ToastMaker.displayShortToast(this, extras.getString(IntentConstants.RAW_PAY_RESPONSE));
} else if (resultCode == IntentConstants.TRANSACTION_SUCCESSFUL_CARD_SAVED) {
// User finished their payment successfully and card was saved.
// Use the static keys declared in PayResponseKeys to extract the fields you want
// Use the static keys declared in SaveCardResponseKeys to extract the fields you want
ToastMaker.displayShortToast(this, "Token == " + extras.getString(SaveCardResponseKeys.TOKEN));
} else if (resultCode == IntentConstants.USER_CANCELED_3D_SECURE_VERIFICATION) {
ToastMaker.displayShortToast(this, "User canceled 3-d scure verification!!");
// Note that a payment process was attempted. You can extract the original returned values
// Use the static keys declared in PayResponseKeys to extract the fields you want
ToastMaker.displayShortToast(this, extras.getString(PayResponseKeys.PENDING));
} else if (resultCode == IntentConstants.USER_CANCELED_3D_SECURE_VERIFICATION_PARSING_ISSUE) {
ToastMaker.displayShortToast(this, "User canceled 3-d scure verification - Parsing Issue!!");
// Note that a payment process was attempted.
// User finished their payment successfully. An error occured while reading the returned JSON.
ToastMaker.displayShortToast(this, extras.getString(IntentConstants.RAW_PAY_RESPONSE));
}
}
}
| Parameter | Description |
|---|---|
| USER_CANCELED | User canceled and did no payment request was fired |
| MISSING_ARGUMENT | You forgot to pass an important key-value pair in the intent's extras |
| TRANSACTION_ERROR | An error occurred while handling an API's response |
| TRANSACTION_REJECTED | The user attempted to pay but their transaction was rejected |
| TRANSACTION_REJECTED_PARSING_ISSUE | The user attempted to pay but their transaction was rejected. An error occurred while reading the returned JSON |
| TRANSACTION_SUCCESSFUL | User finished their payment successfully |
| TRANSACTION_SUCCESSFUL_PARSING_ISSUE | The user finished their payment successfully. An error occurred while reading the returned JSON |
| TRANSACTION_SUCCESSFUL_CARD_SAVED | User finished their payment successfully and the card was saved |
| USER_CANCELED_3D_SECURE_VERIFICATION | The User canceled 3-d secure verification |
| USER_CANCELED_3D_SECURE_VERIFICATION_PARSING_ISSUE | The user finished their payment successfully. An error occurred while reading the returned JSON. |
5. Screenshot from PaymentActivity
6. Try our Sample app from [here]
Updated 6 months ago