Android SDK Integration

Introduction

Now with this Android SDK integration you can easily use Zaakpay in your android applications and can accept payments through various payment methods such as Credit and Debit Card, Net banking, UPI intent and UPI collect, Wallet etc for seamless flow and uninterrupted payments. Follow the steps carefully in order to have a bug free integration.

👍

Have you generated the keys?

For the card transaction it is mandatory to generate the encryption keys. Please follow steps below to generate encryption and public keys:

  • Login to the Zaakpay dashboard.
  • Go to Configurations
  • Click on API keys tab under that you'll find the Encryption Keys section. Kindly refer to the screenshot below for clear understanding.
17471747

🚧

Want to check the payment flow?

Payment flow of Zaakpay LINK

Installing and Setting up SDK

Follow these steps in order to add all the dependencies that are required to setup Zaakpay payment gateway in your application.

Adding dependencies to your application

  1. Add the authToken for the repository access to your project’s gradle.properties file :
authToken=jp_nvgg9iebmirqko7uo25n0ssc9b
  1. Add the Jitpack repository url along with the authToken to your project level build.gradle file :
allprojects{
  repositories{
    maven {
    url "https://jitpack.io"
    credentials { 
      username authToken
                }
         }
    }
  }
}
  1. Add the SDK dependency to your app level build.gradle file :
implementation 'com.github.Mobikwik:Android-SDK:4.5'

Sync your gradle files after adding the dependencies and you should now be able to use the SDK in your application.

🚧

Latest Android SDK version

Android SDK version : 4.5

Initiating a payment through SDK

For initiating a payment through the SDK in your application, please undertake the following steps

  1. Create an instance of TransactionData by using TransactionDataBuilder
@Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
/***** 
 application logic 
 ****/
        TransactionData transactionDataInstance = getTransactionDataInstance();
    }

    private TransactionData getTransactionDataInstance() {
        TransactionDataBuilder transactionDataBuilder = TransactionDataBuilder()
                .withAmount(amount) // BigInteger
                .withChecksum(checksum) // String
                .withChecksumPO(checksumPO) // String
                .withCurrency("INR") // String
                .withOrderId(orderId) // String
                .withUserEmail(userEmail) // String
                .withReturnUrl(returnUrl) // Url on which the txn response will be posted (String)
                .withMerchantIconUrl(iconUrl) // Merchant Icon to be displayed in the SDK (String)
                .withMerchantName(merchantName) // String
                .withMerchantId(merchantIdentifier) // String
                .withUserPhoneNumber() //String
                .withEnvironment(Enums.Environment.STAGING); // Enum to configure the server environment 
          return transactionDataBuilder.build();
    }
  1. The TransactionData object created above should then be passed in the startPayment of the PaymentCheckout class
@Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
/***** 
 application logic 
 *****/
        TransactionData transactionDataInstance = getTransactionDataInstance();
        PaymentCheckout paymentCheckout = new PaymentCheckout(this);
        paymentCheckout.startPayment(transactionDataInstance);
    }

This will trigger the SDK flow inside your application and present a list of payment options to the user.

👍

Note

In case you face Manifest merger failed : Attribute [email protected] error while building your application with the SDK, please add tools:replace="android:theme" in the application tag inside your application’s AndroidManifest.xml file.

Checksum Calculation

The checksum and checksumPO values used here must be calculated and fetched from the merchant’s server.

The above example shows the mandatory params needed for the SDK transaction. You can check the full list of params supported by the TransactionData object here : LINK

For both integrity & data-authenticity verification before sending data to the API. We use an algorithm HMAC SHA-256 to calculate the checksum.

There are two checksums that are created in the process of transaction i:e Checksum PO and Checksum

ChecksumPO Calculation

Checksum PO string consists of merchantIdentifier and emailId. String should be created in the format as given below.

Considering staging Credentials and email id as '[email protected]' :

  • Merchant Identifier : b19e8f103bce406cbd3476431b6b7973
  • Secret key : 0678056d96914a8583fb518caf42828a
merchantIdentifier=b19e8f103bce406cbd3476431b6b7973&[email protected]
f9ea7ead1b43f028795eed9fdedd0721b00dd660999242eee0ff10560bac4602

Checksum Calculation

Checksum string consists of parameters in the same order merchant Identifier, orderid, mode, currency, amount, Buyer's Device IP, date

Considering staging Credentials and email id as '[email protected]' :

  • Merchant Identifier : b19e8f103bce406cbd3476431b6b7973
  • Secret key : 0678056d96914a8583fb518caf42828a
'b19e8f103bce406cbd3476431b6b7973''1551264623988gjgkgf''0''INR''200''ip''date'

Register Callback Listener

Post the completion of the payment process we need to get a final transaction response from the SDK. In order to do that we will be using Register Callback Listener, you must implement the PaymentCheckout.ZaakPayPaymentListener inside your activity/fragment from which you initiated the payment.

public class PaymentActivity extends AppCompatActivity implements PaymentCheckout.ZaakPayPaymentListener {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        /* application checkout flow logic */
        TransactionData transactionDataInstance = getTransactionDataInstance();
        PaymentCheckout paymentCheckout = new PaymentCheckout(this);
        paymentCheckout.startPayment(transactionDataInstance);
    }

    @Override
    public void onPaymentSuccess(TransactionResponse response) {
// extract the checksum from the response using response.getChecksum() and verify it on your server before further processing the success response
    }

    @Override
    public void onPaymentFailure(String responseCode, String responseDescription) {
        //handle payment failure 
    }
}

Transaction Flow

After completing all the above steps you are good to go and test your integration. Below is a demo application demonstrating the Zaakpay payment integration in android.

📘

Want to test our demo application?

Link to the application : LINK

To verify the authenticity of the response received in case of payment success it is recommended to extract the checksum from the response and verify it on your server before any further processing. This helps fight against MITM attacks or network fiddling. The specifics on verifying the response checksum on the merchant server is available in next section.

Following sample response should be returned in response of return url. You will get the values of these parameters in the request parameters of return url hit.

📘

Return/Redirect URL

The return URL is the URL on which the response of the transaction will be posted. On completion of transaction Zaakpay will redirect the user to the merchant's platform.

Sample Response:

{
  "orderId": "1601294679223",
  "responseCode": "100",
  "responseDescription": "The transaction was completed successfully. ",
  "checksum": "1b6f38fca8ceb319218d806f79f7e163de595eb8b3753c976441733028f186b8",
  "amount": "100",
  "doRedirect": "false",
  "paymentMode": "UPI",
  "cardId": "NA",
  "cardScheme": "NA",
  "cardToken": "NA",
  "bank": "ICICIUPI",
  "bankid": "ICIUPI",
  "paymentMethod": "N1064",
  "cardhashid": "NA",
  "product1Description": "NA",
  "product2Description": "NA",
  "product3Description": "NA",
  "product4Description": "NA",
  "pgTransId": "ZP5b05e7c3666b8",
  "pgTransTime": "09/28/2020 17:35:54"
}

Response Checksum

If you want to validate the checksum on the above JSON response string. Please follow below required setps:

  1. Use SHA -256 algorithm to generate the correct checksum for JSON string
  2. We need to calculate on all the parameters of the JSON string
  3. Use merchant's secret key for the same
Sample Input Parameters: 

amount=100&bank=ICICIUPI&bankid=ICIUPI&cardId=NA&cardScheme=NA&cardToken=NA&cardhashid=NA&doRedirect=false&orderId=1601294679223&paymentMethod=N1064&paymentMode=UPI&responseCode=100&responseDescription=The transaction was completed successfully. &product1Description=NA&product2Description=NA&product3Description=NA&product4Description=NA&pgTransId=ZP5b05e7c3666b8&pgTransTime=09/28/2020 17:35:54&is 1b6f38fca8ceb319218d806f79f7e163de595eb8b3753c976441733028f186b8

Secret Key: Please user merchant's secret Key

Zaakpay Payment Gateway Response codes

These are the transact API response codes. For more response code, Please download Document Directly from here.

Response Code Response Description
100 The transaction was completed successfully.
101 Merchant not found. Please check your merchantIdentifier field.
102 Customer cancelled transaction.
103 Fraud Detected.
104 Customer Not Found.
105 Transaction details not matched.
106 IpAddress BlackListed.
107 Transaction Amount not in specified amount range.
108 Validation Successful.
109 Validation Failed.
110 MerchantIdentifier field missing or blank.
111 MerchantIdentifier Not Valid.
126 Date received with request was not valid.
127 ReturnUrl does not match the registered domain.
128 Order Id Already Processed with this Merchant.
129 OrderId field missing or blank.
130 OrderId received with request was not Valid.
131 ReturnUrl field missing or blank.
132 ReturnUrl received with request was not Valid
133 BuyerEmail field missing or blank.
134 BuyerEmail received with request was not Valid.
135 BuyerFirstName field missing or blank.
136 BuyerFirstName received with request was not Valid.
137 BuyerLastName field missing or blank.
138 BuyerLastName received with request was not Valid.
139 BuyerAddress field missing or blank.
140 BuyerAddress received with request was not Valid.
141 BuyerCity field missing or blank.
142 BuyerCity received with request was not Valid.
143 BuyerState field missing or blank
144 BuyerState received with request was not Valid.
145 BuyerCountry field missing or blank.
146 BuyerCountry received with request was not Valid.
147 BuyerPincode field missing or blank.
148 BuyerPinCode received with request was not Valid.
149 BuyerPhoneNumber field missing or blank.
150 BuyerPhoneNumber received with request was not Valid.
151 TxnType field missing or blank.
152 TxnType received with request was not Valid.
153 ZpPayOption field missing or blank.
154 ZpPayOption received with request was not Valid.
155 Mode field missing or blank.
156 Mode received with request was not Valid.
157 Currency field missing or blank.
158 Currency received with request was not Valid.
159 Amout field missing or blank.
160 Amount received with request was not Valid.
161 BuyerIpAddress field missing or blank.
162 BuyerIpAddress received with request was not Valid.
163 Purpose field missing or blank.
164 Purpose received with request was not Valid.
165 ProductDescription field missing or blank.
166 ProductDescription received with request was not Valid.
167 Product1Description received with request was not Valid.
168 Product2Description received with request was not Valid.
169 Product3Description received with request was not Valid.
170 Product4Description received with request was not Valid.
171 ShipToAddress received with request was not Valid.
172 ShipToCity received with request was not Valid.
173 ShipToState received with request was not Valid.
174 ShipToCountry received with request was not Valid.
175 ShipToPincode received with request was not Valid.
176 ShipToPhoneNumber received with request was not Valid.
177 ShipToFirstname received with request was not Valid.
178 ShipToLastname received with request was not Valid.
179 Date is blank.
179 Date received with request was not valid.
180 Checksum received with request is not equal to what we calculated.
181 Merchant Data Complete.
182 Merchant data not completed in our database.
183 Unfortunately, the transaction has failed.
400 The transaction was declined by the issuing bank.
401 The transaction was rejected by the acquiring bank.
402 This test transaction has been successfully completed.
403 Transaction failed because this card has been blocked by Zaakpay Payment Gateway.
404 Transaction failed due to security checks.
501 Debitorcredit is blank.
502 Bankid is blank.
503 Encrypted pan is blank.
504 Card is blank.
505 Nameoncard is blank.
506 Encrypted cvv is blank.
507 Encrypted expiry month is blank.

Did this page help you?