ATH Móvil Android SDK

Introduction

The ATH Móvil SDK provides a simple, secure and fast checkout experience to customers paying on your Android application. After integrating our Payment Button on your app you will be able to receive instant payments from more than a million ATH Móvil users.

Prerequisites

Before you begin, please review the following prerequisites:

1. An active ATH Móvil Business account is required to continue.

• Note: To sign up, download "ATH Móvil Business" on the App Store if you have an iOS device or on the Play Store if you have an Android device.

2. Your ATH Móvil Business account needs to have a registered, verified and active ATH® card.

3. Have the public and private API keys of your Business account at hand.

• Note: You can view your API keys on the settings section of the ATH Móvil Business application for iOS or Android.

If you need help signing up, adding a card or have any other question please refer to https://athmovilbusiness.com/preguntas or contact our support team at (787) 773-5466. For technical support please complete the following form: https://forms.gle/ZSeL8DtxVNP2K2iDA.

Installation

Before we get started, let’s configure your project:

• Add the JitPack repository to your gradle.build file.

	allprojects {
		repositories {
			...
			maven { url 'https://jitpack.io' }
		}
	}

• Add the SDK and the GSON library to your application dependencies.

dependencies {
    …
    implementation 'com.github.evertec:athmovil-android-sdk:3.0.0'
	implementation 'com.google.code.gson:gson:2.8.2'
}

Usage

To integrate ATH Móvil’s Payment Button to your Android application follow these steps:

XML

Add the “Pay with ATH Móvil” button to your checkout XML view.

<com.evertecinc.athmovil.sdk.checkout.PayButton
    android:onClick="onClickPayButton"
    android:layout_width="match_parent"
    android:layout_height="60dp"
    app:theme="light"
    app:lang="en"
    />

• app:theme defines the theme of the button.

Styles	Example
default
light
dark

• app:lang defines the language of the button.

Languages	Example
default	Uses the device language.
english
espanol

---

Manifest

Configure the activity where the payment response will be sent to on your manifest.

<activity
    android:name=".Activity">
    <intent-filter>
        <!--Schema with app bundle Configuration-->
        <action android:name="appbundle.schema" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

---

Java

Configure the payment.

Add all required imports to the java file of your checkout screen.

import com.evertecinc.athmovil.sdk.checkout.OpenATHM;
import com.evertecinc.athmovil.sdk.checkout.PayButton;
import com.evertecinc.athmovil.sdk.checkout.objects.ATHMPayment;
import com.evertecinc.athmovil.sdk.checkout.objects.Items;

Create an ATHMPayment object on the main class of the file.

ATHMPayment athmPayment = new ATHMPayment(this);

Configure the payment values and execution on the onClick of the XML button that we recently created. Details of the methods used to configure the payment details are provided below.

public void onClickPayButton(View view) {
    // CallbackSchema example, this should be changed with your application CallbackSchema.
	athmPayment.setCallbackSchema("scheme"); 
    // PublicToken example, this should be changed with your public token.
	athmPayment.setPublicToken("fb1f7ae2849a07da1545a89d997d8a435a5f21ac"); 
	athmPayment.setTimeout(600);
	athmPayment.setTotal(1.00);
	athmPayment.setSubtotal(1.00);
	athmPayment.setTax(1.00);
	athmPayment.setMetadata1("metadata1 test");
	athmPayment.setMetadata2("metadata2 test");
	athmPayment.setItems(items);
	athmPayment.setBuildType("");
	OpenATHM.validateData(payment, context);
}

Method	Data Type	Required	Description
setPublicToken()	String	Yes	Determines the Business account where the payment will be sent to.
setTimeout()	Long	No	Expires the payment process if the payment hasn't been completed by the user after the provided amount of time (in seconds). Countdown starts immediately after the user presses the Payment Button. Default value is set to 600 seconds (10 mins).
setTotal()	Double	Yes	Total amount to be paid by the end user.
setSubtotal()	Double	No	Optional variable to display the payment subtotal (if applicable)
setTax()	Double	No	Optional variable to display the payment tax (if applicable).
setMetadata1()	String	No	Optional variable to attach data to the payment object.
setMetadata2()	String	No	Optional variable to attach data to the payment object.
setItems()	Array	No	Optional variable to display the items that the user is purchasing on ATH Móvil's payment screen. Items on the array are expected in the following order: (“name”, “desc”, "quantity", “price”, “metadata”)
setBuildType()	String	Yes	Identifies the application's build type. Should always be configured as an empty string.

In the request you must make sure that you are following the next rules for the payment ATHMPayment object otherwise you will receive an exception on the callback

Variable	Expeted Value
total	Positive value
subtotal	Positive value or zero
tax	Positive value or zero
metadata1	Only allows space, letters and numbers
metadata2	Only allows space, letters and numbers
publicToken	A string with characters
callbackSchema	A string with characters, avoid to use the callbackSchema of the example
timeout	Integer between 60 and 600

If you provide items in the request you must make sure that you are following the next rules for the ATHMPaymentItem object:

Variable	Expeted Value
name	Only allows space, letters and numbers
price	Positive value greater than zero
description	Only allows space, letters and numbers
quantity	Positive value greater than zero
metadata	Only allows space, letters and numbers

Note the request and items are the same objects in the response so the values and types are identical in request and response, but he response includes the following additional variables

Variable	Data Type	Description
dailyTransactionID	Int	Consecutive of the transaction, when the transaction is cancelled o expired is zero.
referenceNumber	String	Unique transaction identifier, when the transaction is cancelled o expired is an empty string.
date	Date	Transaction's date.
name	String	ATHM Customer's name, no matter the status of the transaction it always has the name.
phoneNumber	String	ATHM Customer's phone, no matter the status of the transaction it always has telephone number in format (xxx) xxx-xxxx.
email	String	ATHM Customer's email, no matter the status of the transaction it always has email.

If the data is unexpected in the response or request SDK will call the closure onPaymentException and you will get a title and a message referring to the error obtained. Then your application must handle the error depending on the case.

@Override
    public void onPaymentException(String error, String description) {
        //handle the error
    }

Handle all payment responses.

When a transaction is completed, canceled or expired a response is sent back to the URL scheme that was configured on the payment.

Implement the PaymentResponseListener on the activity of the configured scheme.

public class Activity extends AppCompatActivity
implements PaymentResponseListener, View.OnClickListener {
}

On the OnCreate method of the activity call PaymentResponse.validatePaymentResponse

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

    PaymentResponse.validatePaymentResponse(getIntent(), this);
}

Handle the payment response with using the following methods:

• Completed

@Override
public void onCompletedPayment(Date date, String referenceNumber, String dailyTransactionID,
                            String name, String phoneNumber, String email,
                            Double total, Double tax, Double subtotal,
                            String metadata1, String metadata2, ArrayList<Items> items) {
		//Handle response
}

• Cancelled

@Override
public void onCancelledPayment(Date date, String referenceNumber, String dailyTransactionID,
                            String name, String phoneNumber, String email,
                            Double total, Double tax, Double subtotal,
                            String metadata1, String metadata2, ArrayList<Items> items) {
		//Handle response
}

• Expired

@Override
public void onExpiredPayment(Date date, String referenceNumber, String dailyTransactionID,
                            String name, String phoneNumber, String email,
                            Double total, Double tax, Double subtotal,
                            String metadata1, String metadata2, ArrayList<Items> items) {
		//Handle response
}

• Exception

@Override
void onPaymentException(String error, String description){
		//Handle response
}

Testing

• You could test the integration with ATH Movil Personal Application so you can use your public token or set the public as "dummy".
• Setting public token as "dummy" ATH Movil Personal Application will simulate a payment, in that way you can test all the features such as completed, expired or cancelled payments. You need the latest version of ATH Movil Personal Application.

public void onClickPayButton(View view) {
    ...
	athmPayment.setPublicToken("dummy");
    ...
	OpenATHM.validateData(payment, context);
}

User Experience

Legal

The use of this API and any related documentation is governed by and must be used in accordance with the Terms and Conditions of Use of ATH Móvi Business ®, which may be found at: https://athmovilbusiness.com/terminos.