ANDROID SDK – GETTING STARTED

​Use the eWAY Android SDK to easily accept payments in your Android application!

The eWAY Android SDK supports three styles of implementation, depending on the requirements of your app:

  • Synchronous – the app will wait for eWAY operations to complete (use this if you aren’t sure)
  • Asynchronous – the app can continue while eWAY operations complete
  • RxJava – for apps built using ReactiveX

INSTALLATION

GRADLE

Gradle is the easiest way to install the eWAY Android SDK – adding the package is a simple two-step process:

1. Add the repository to the project’s build gradle file under all projects:

1
2
3
4
repositories {
jcenter()
maven { url "http://dl.bintray.com/webactive/maven" }
}

2. Then add the dependency to the dependencies section of app’s build gradle:

1
2
3
4
dependencies {
...
compile "com.eway.payment:android-sdk:1.+"
}

Manual Install

If you don’t wish to use Gradle, you can install the package manually:

1.Download the eWAY Android SDK package from Bintray: https://bintray.com/webactive/maven/android-sdk/view#files

2.Add the package to your project’s library

PERMISSIONS

To use the eWAY Android SDK, the INTERNET permission is required. Simply add the following line to the AndroidManifest.xml file if it is not already there:

1
 

CONFIGURATION

The eWAY Android SDK requires two pieces of information to connect to eWAY, your eWAY account’s Public API Key and the endpoint.

To find your account’s Public API Key:

1.In MYeWAY (production or sandbox), go to My Account > User Security > Manage Users

2.Select the “Actions” dropdown for the Rapid API user and select “View Api Keys”

3.Select the “Pay Now Button Public API Key”, this is your Public API Key.

The Endpoint should be one of: ”Production” or “Sandbox”

These values are passed to the eWAY Android SDK using the following static properties:

1
2
RapidAPI.PublicAPIKey = "epk-XXXXX-XXXX-XXXX-XXXX-XXXXXXX1";
RapidAPI.RapidEndpoint = "Sandbox";

ENCRYPT VALUES

To secure a customer’s card data for transmission to your server for processing, you can use the encryptValues method. Once encrypted, the values can be sent to your server with any other data to be processed using eWAY’s Rapid Direct Connection API.

Once the eWAY Android SDK has been initialised, the encryptValues method can be called with a NVPair ArrayList. There are three ways of calling this, depending on your app’s design:

SYNCHRONOUS REQUEST​

1
2
3
4
ArrayList data = new ArrayList();
data.add(new NVPair("card", "444333222111"));
data.add(new NVPair("cvn", "123"));
EncryptValuesResponse encryptedResponse = RapidAPI.encryptValues(data);

The response contains the encrypted values in a NVPair ArrayList which can be fetched with getValues:

1
ArrayList encryptedValues = encryptedResponse.getValues();

ASYNCHRONOUS REQUEST

The asynchronous class should  implement RapidAPI.RapidEncryptValuesListener

1
2
3
4
5
6
7
ArrayList data = new ArrayList();

data.add(new NVPair("card", "444333222111"));

data.add(new NVPair("cvn", "123"));

RapidAPI.asycEncryptValues(values,this);

The response can be fetched with implemented methods

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
@Override
public void onResponseReceivedSuccess(EncryptItemsResponse response) {
}

@Override
public void onResponseReceivedError(String errorResponse) {
}

@Override
public void onResponseReceivedFailure(String errorFailure) {
}

@Override
public void onResponseReceivedException(EncryptItemsResponse exception) {
}

RXJAVA – RXANDROID REQUEST

The response can be fetched onNext or OnError methods

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
final ArrayList values = new ArrayList();
values.add(new NVPair("Card", cardNumber));
values.add(new NVPair("CVN", cvnNumber));
subscription = RapidAPI.rxEncryptValues(values)
.observeOn(AndroidSchedulers.mainThread())
.subscribe(new Observer() {
@Override
public void onCompleted() {
}
@Override
public void onError(Throwable e) {
}
@Override
public void onNext(EncryptItemsResponse response) {
}
});

MAKE A PAYMENT

A payment can also be made directly from the app using the eWAY Android SDK, instead of sending details to a server. Note that the result of the transaction (succeeded or failed) can still only be requested using Rapid API from a server – see Getting the Result below.

First collect the details for the payment(such as the customer’s name and card details) prepare the data for sending. All the fields available in RapidAPI’s Direct Connection can be used when submitting a transaction. The following is a simple example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
CardDetails cardDetails = new CardDetails();
cardDetails.setCVN("349");
cardDetails.setName("Kale Argula");
cardDetails.setNumber("4556761029983886");
cardDetails.setExpiryMonth("09");
cardDetails.setExpiryYear("2020");

Customer customer = new Customer();
customer.setFirstName("Kale");
customer.setLastName("Argula");
customer.setCardDetails(cardDetails);

Payment payment = new Payment();
payment.setCurrencyCode("AUD");
payment.setTotalAmount(1000);
payment.setInvoiceNumber(UUID.randomUUID().toString());
payment.setInvoiceReference(UUID.randomUUID().toString());
payment.setInvoiceDescription("Demo Transaction");

Transaction transaction = new Transaction();
transaction.setCustomer(customer);
transaction.setTransactionType(TransactionType.Purchase);
transaction.setPayment(payment);

SYNCHRONOUS REQUEST

1
final SubmitPaymentResponse response = RapidAPI.submitPayment(transaction);

ASYNCHRONOUS REQUEST

The asynchronous class should implement RapidAPI.RapidRecordingTransactionListener

1
RapidAPI.asycSubmitPayment(transaction,this);

SYNCHRONOUS REQUEST

1
subscription = RapidAPI.rxSubmitPayment(transaction);

GETTING THE RESULT

RapidAPI will then return a response object, which contains an eWAY Access Code. This can be fetched using the getSubmissionID method. The Access Code is an identifier to look up the transaction result. The transaction result cannot be retrieved with the eWAY Android SDK, instead the Access Code should be passed to a server which can use the eWAY RapidAPI Transaction Query to get the result.

SYNCHRONOUS RESPONSE

1
String submissionID = response.getSubmissionID();

ASYNCHRONOUS RESPONSE

The asynchronous class should implement RapidAPI.RapidRecordingTransactionListener

1
2
3
4
5
6
7
8
9
10
11
12
@Override
public void onResponseReceivedSuccess(SubmitPayResponse response) {
}
@Override
public void onResponseReceivedError(String errorResponse) {
}
@Override
public void onResponseReceivedFailure(String errorFailure) {
}
@Override
public void onResponseReceivedException(SubmitPayResponse exception) {
}

RXJAVA – RXANDROID RESPONSE

This response could change if there is rx operator before such as flatmap,map,concat, etc.

1
2
3
4
5
6
7
8
9
10
11
12
.observeOn(AndroidSchedulers.mainThread())
.subscribe(new Observer() {
@Override
public void onCompleted() {
}
@Override
public void onError(Throwable e) {
}
@Override
public void onNext(SubmitPayResponse response) {
}
});

In all cases, the response object also contains status and error properties. The status is set to one of “accepted” or “error”. This does not indicate whether the transaction was successful, it indicates if the SDK received a response.

If an error did occur, the errors property this will contain one or more comma separated error codes. These codes can be translated with userMessage – see Handling Errors below for more details.

HANDLING ERRORS

If a call with the eWAY Android SDK fails for some reason, an error code will be returned in the response object. Note that only SDK errors will be returned – if there was an error with the transaction (such as card declined) no error will be supplied to the SDK.

To check for a transaction or validation failure, use the Access Code to do a server side Transaction Query with eWAY’s Rapid API.

To check if an SDK error occurred, use the method appropriate for your app’s design:

SYNCHRONOUS RESPONSE

Test if the getErrors method returns null:

1
 if (response.getErrors() != null) { // handle errors

ASYNCHRONOUS RESPONSE

1
 @Override public void onResponseReceivedError(String errorResponse) { //handle errors from data } @Override public void onResponseReceivedFailure(String errorFailure) { //handle error from service } @Override public void onResponseReceivedException(SubmitPayResponse exception) { //handle error from service such as (S9001,S9002,S9003..) }

RXJAVA – RXANDROID RESPONSE

1
 @Override public void onError(Throwable e) { // handle errors }

If there is an error, it can be looked up using userMessage to return a user friendly version of the response (only English is available at this time):

SYNCHRONOUS REQUEST

Test if the getErrors method returns null:

1
2
UserMessageResponse messageResponse= RapidAPI.userMessage("EN", $error);
ArrayList messageResponse= message.getErrorMessages();

ASYNCHRONOUS REQUEST

The asynchronous class has to implement RapidAPI.RapidUserMessageListener

1
Rapid.asyncUserMessage(language,errorCodes,this)

The response can be fetched on the implemented methods:

1
2
3
4
5
6
7
8
9
@Override
public void onResponseReceivedSuccess(SubmitPayResponse response) {
}
@Override
public void onResponseReceivedError(String errorResponse) {
}
@Override
public void onResponseReceivedFailure(String errorFailure) {
}

RXJAVA – RXANDROID REQUEST

1
2
3
4
5
6
7
8
9
10
11
12
13
subscription = RapidAPI.rxUserMessage(Locale.getDefault().getLanguage(),errorCodeNumber)
.observeOn(AndroidSchedulers.mainThread())
.subscribe(new Observer() {
@Override
public void onCompleted() {
}
@Override
public void onError(Throwable e) {
}
@Override
public void onNext(UserMessageResponse userMessageResponse) {
}
});

ERROR CODES

The following error codes are specific to the eWAY Android SDK. They can be translated using the userMessage as described in the Handling Errors section.

  Error Code

  Purpose

  S9990

  Library does not have Endpoint initialised, or not initialise to a URL

  S9991

  Library does not have PublicAPI key initialised, or Key is Invalid.

  S9992

  Communication error with Rapid API.

  S9993

  Authentication error with Rapid API.

  S9994

  Internal system error communicating with Rapid API.

  S9995

  Internal SDK Error, Bad Parameters etc.

Become an eWAY merchant today.

With 24/7 support, over 250 integrations and 20+ years experience – the team at eWAY are here to provide you with the leading all-in-one payments solution.