Android SDK

SDK for Android mobile apps integration.

πŸ“˜

We'll cover

  1. Downloading the SDK
  2. Installation
    ➒ 2.1. Adding the arr file in the libs folder
    ➒ 2.2. Adding a dependencies
  3. 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
  4. Results
  5. Screenshot from PaymentActivity
  6. Try our Sample app

1. Download the SDK from: [here]

2. Installation

➒ 2.1. Adding the arr file in the libs folder

1124

➒ 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)

ParameterDescription
PAYMENT_KEYThis is the payment key you entered in 3.2
THREE_D_SECURE_ACTIVITY_TITLE
SAVE_CARD_DEFAULTThe default for whether to save a card or not
SHOW_SAVE_CARDWhether 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_COLORThe theme color(so that you can set it the same as your app)
ACCEPT_PAYMENT_REQUESTArbitrary 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)

ParameterDescription
PAYMENT_KEYThis is the payment key you entered in 3.2
THREE_D_SECURE_ACTIVITY_TITLE
TOKENYou should use your actual card token
MASKED_PAN_NUMBERCard masked Pan in case of the saved card.
SAVE_CARD_DEFAULTThe default for whether to save a card or not
SHOW_SAVE_CARDWhether 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_COLORThis 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));
            }
        }
    }
ParameterDescription
USER_CANCELEDUser canceled and did no payment request was fired
MISSING_ARGUMENTYou forgot to pass an important key-value pair in the intent's
extras
TRANSACTION_ERRORAn error occurred while handling an API's response
TRANSACTION_REJECTEDThe user attempted to pay but their transaction was rejected
TRANSACTION_REJECTED_PARSING_ISSUEThe user attempted to pay but their transaction was rejected. An error occurred while reading the returned JSON
TRANSACTION_SUCCESSFULUser finished their payment successfully
TRANSACTION_SUCCESSFUL_PARSING_ISSUEThe user finished their payment successfully. An error occurred while reading the returned JSON
TRANSACTION_SUCCESSFUL_CARD_SAVEDUser finished their payment successfully and the card was saved
USER_CANCELED_3D_SECURE_VERIFICATIONThe User canceled 3-d secure verification
USER_CANCELED_3D_SECURE_VERIFICATION_PARSING_ISSUEThe user finished their payment successfully. An error occurred while reading the returned JSON.

5. Screenshot from PaymentActivity

2552

6. Try our Sample app from [here]