Android Checkout SDK Integration Guide
Posted by Sam Francisco • Friday September 23, 2016 02:39 PM

The PayMaya Android SDK allows your app to accept payments from your customers using any MasterCard and Visa enabled card (credit, debit, or prepaid).

 


Contents

 

Prerequisites

Overview

Integration

Using Checkout

      Implementing PayMayaCheckoutCallback

      Initialize Environment

      Initializing the SDK

      Payload Composition

      Constructing Buyer's Information

      Constructing Items List and TotalAmount summary

      Constructing Redirect URLs

      Constructing Additional MetaData (optional)

      Constructing the Checkout Payload

      Executing the Checkout Process

Summary

 

Prerequisites

 

Compatibility

Your PayMaya Android Checkout SDK is compatible with the following:

  • JDK 7 or higher
  • Android Studio 1.3 or higher
  • Android OS version 4.1 or higher

 

API Keys

 

To use your PayMaya Android Checkout SDK, you need to have a different API key for Sandbox and Production environment.

 

  • Sandbox Environment

 

Sandbox credentials are useful for testing application integration. All transactions and money flow made in this environment are only simulated and does not reflect your production records. The following sandbox API key can be used for testing purposes:

 

Public-facing API Key: pk-iaioBC2pbY6d3BVRSebsJxghSHeJDW4n6navI7tYdrN

 

  • Production Environment

 

Upon successful integration testing, you can then request for production credentials. Upon receipt, just change your SDK initialization to use production environment to start accepting live transactions.

 

There are two (2) required fields in HTTP Basic Authentication, the username and password. API keys acts as the "username" while passwords are set to blank ("").

 

Redirect URLs

 

Redirect URLs are needed by the Checkout payment page to pass the result of the payment transaction. Redirect URLs are either app URL schemes or web site URLs.

 

  1. Successful transaction redirect URL
  2. Failed transaction redirect URL
  3. Canceled transaction redirect URL

 

Overview

 

Checkout Overview

Figure 1 - Overview of the PayMaya Checkout payment flow

 

You can easily integrate the PayMaya Checkout SDK to your Android app in three (3) easy steps:

 

  1. Add the SDK to your dependencies in your Gradle file.
  2. Implement the PayMayaCheckoutCallback interface to your class. This makes your class the callback class.
  3. Initialize the SDK by supplying your public-facing API key and callback class.

 

Integration

 

Grab the latest SDK via Gradle:
compile 'com.paymaya:sdk-android:0.8.0'

 

Your app/build.gradle file should look like the following:

apply plugin: 'com.android.application'

android {
    ...
}

dependencies {
    compile 'com.paymaya:sdk-android:0.8.0'
    // your may have other dependencies here
}

 

Using Checkout

 

The Checkout process only involves three (3) easy steps:

 

1. Implement PayMayaCheckoutCallback to your class. This class will be waiting for the result of the Checkout process after completion or cancellation.

2. Construct the payload. This consists of the buyer's information as well as the total amount and breakdown of the purchase.

3. Execute the Checkout process. This will present a view to your customer wherein they will need to enter their card details and billing information. Your customer may opt to complete or to cancel this process. Whatever the result may be, you will get the result as indicated in step 1.

 

Implementing PayMayaCheckoutCallback

As an example, we will be using our MainActivity class as the callback class:

 

public class MainActivity implements PayMayaCheckoutCallback {

    ...

    @Override
    public void onCheckoutSuccess() {}

    @Override
    public void onCheckoutFailure(String message) {}

    @Override
    public void onCheckoutCanceled() {}

    ...

}

 

Initialize Environment

We need to tell the SDK what environment we are going to use, either Sandbox or Production environment.

PayMayaConfig.setEnvironment(PayMayaConfig.ENVIRONMENT_SANDBOX);
// Use the following for Production:
// PayMayaConfig.setEnvironment(PayMayaConfig.ENVIRONMENT_PRODUCTION);

 

Initializing the SDK

Next we will be initializing the SDK inside the onCreate:

private static final String PUBLIC_FACING_API_KEY = "";
private PayMayaCheckout mPayMayaCheckout;

@Override
protected void onCreate(Bundle savedInstanceState) {
    ...

    mPayMayaCheckout = new PayMayaCheckout(PUBLIC_FACING_API_KEY, this);
}

 

Payload Composition

After we have initialized the SDK, we will be constructing the payload.

The payload is composed of the following:

  • Buyer's information
  • List of Items (with details)
  • Total Amount (serves as the summary)
  • Redirect URLs
  • Request Reference
  • Additional Metadata (if any)

 

Constructing Buyer's Information

Contact contact = new Contact("mobile number", "email");
Address address = new Address("line 1", "line 2", "city", "state", "zip code", "country code");
Buyer buyer = new Buyer("First name", "Middle name", "Last name");
buyer.setContact(contact);
buyer.setBillingAddress(address);
buyer.setShippingAddress(address);

 

Constructing Items List and TotalAmount summary

BigDecimal summaryTotal = BigDecimal.valueOf(0);
List itemsList = new ArrayList<>();
String currency = "PHP";

BigDecimal item1Amount = BigDecimal.valueOf(100);
summaryTotal.add(item1Amount);
TotalAmount totalAmount = new TotalAmount(item1Amount, currency);
int quantity = 10;
Item item1 = new Item("Item 1 name", quantity, totalAmount);
item1.setSkuCode("SKU code");
item1.setDescription("bag");
itemsList.add(item1);

BigDecimal item2Amount = BigDecimal.valueOf(200);
summaryTotal.add(item2Amount);
totalAmount = new TotalAmount(item2Amount, currency);
quantity = 20;
Item item2 = new Item("Item 1 name", quantity, totalAmount);
item2.setSkuCode("SKU code");
item2.setDescription("shoes");
itemsList.add(item2);

It will be your app's role to make sure that the TotalAmount summary matches the sum of all individual items. This is to ensure that running promotions with different requirements are met.

 

Constructing Redirect URLs

String successURL = "http://yourshop.com/success";
String failedURL = "http://yourshop.com/failed";
String canceledURL = "http://yourshop.com/canceled";

RedirectUrl redirectUrl = new RedirectUrl(successURL, failedURL, canceledURL);

 

Constructing Additional MetaData (optional)

JSONObject metadata = new JSONObject();
metadata.put("meta-key", "meta-value");

 

Constructing the Checkout Payload

String requestReference = "YourRequestReferenceCode";
Checkout checkout = new Checkout(summaryTotal, buyer, itemsList, requestReference, redirectUrl);
checkout.setMetadata(metadata);

 

Executing the Checkout Process

To start the Checkout process, simply invoke the execute method of your mPayMayaCheckout reference.

private void executeCheckout(Checkout payload) {
    mPayMayaCheckout.execute(MainActivity.this, payload);
}

 

For Sandbox environment, you must only use credit cards from the following link: Credit Cards for Sandbox Testing.

 

Once the user has completed or cancelled the purchase, the control will be passed on to your Activity's onActivityResult callback. To process the result, you will have to delegate it to onActivityResult of your mPayMayaCheckout reference.

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    mPayMayaCheckout.onActivityResult(requestCode, resultCode, data);
}

Upon successful transaction, the callback onCheckoutSuccess will be called. Failed transaction triggers the onCheckoutFailure callback. Lastly, when a transaction is canceled, the callback onCheckoutCanceled is called.

 

When using the sandbox SDK, you will be able to debug failed transactions from the Android logs. For the error codes, you can refer the PayMaya Checkout Error Codes document.

 

Summary

 

  • These docs in the SDK include an overview of usage, step-by-step integration instructions, and sample code.
  • A sample app can be downloaded for a hands-on experience.
  • Checkout API Documentation and Payments API Documentation are currently available which cover error codes and server-side integration instructions.
  • Source code documentation is also available in JavaDoc format.