Application Programming Interface (API) for Android

4.1 Environtment

Android Version : 6.0 and above.

4.2 Programming Guide: Request Cashlez Application from Merchant Application

4.2.1 Android

Intent Request From Merchant App to Cashlez via Intent

czPackageName: com.cashlez.android.garuda.allinone or com.cashlez.android.garuda

Normal Payment
Split Payment

Intent intent = getPackageManager().getLaunchIntentForPackage(czPackageName); 
if (intent != null) { 
    intent.addCategory("android.intent.category.LAUNCHER"); 
    intent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK | Intent.FLAG_ACTIVITY_MULTIPLE_TASK); 
    intent.putExtra(CzConstant.MERCHANT_NAME, [String]); 
    intent.putExtra(CzConstant.AMOUNT, [String]); 
    intent.putExtra(CzConstant.DESCRIPTION, [String]); 
    intent.putExtra(CzConstant.TRANSACTION_TYPE, [String]); 
    intent.putExtra(CzConstant.PAYMENT_NAME, [String]); 
    intent.putExtra(CzConstant.MERCHANT_TRANSACTION_ID, [string]); 
    intent.putExtra(CzConstant.EMAIL, [String]); 
    intent.putExtra(CzConstant.NO_HANDPHONE, [String]); 
    intent.putExtra(CzConstant.PRODUCT_IMAGE, [String]); 
    intent.putExtra(CzConstant.SECRETKEY, [String]); 
    intent.putExtra(CzConstant.MOBILEUSER_ID, [String]); 
    intent.putExtra(CzConstant.AGGREGATOR_ID, [String]); 
    intent.putExtra(CzConstant.AUTOBACKPREF, [String]); 
    intent.putExtra(CzConstant.AUTO_PRINT, [String]); 
    intent.putExtra(CzConstant.AUTO_REDIRECT, [String]); 
    intent.putExtra(CzConstant.REDIRECT_TIME, [String]); 
    intent.putExtra(CzConstant.DISABLE_PRINT_BUTTON, [String]); 
    startActivity(intent); 
} else { 
    //TODO: Handle Application Not Installed 
}

Intent intent = getPackageManager().getLaunchIntentForPackage(czPackageName);
if (intent != null) {
    intent.addCategory("android.intent.category.LAUNCHER");
    intent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK | Intent.FLAG_ACTIVITY_MULTIPLE_TASK);
    intent.putExtra(CzConstant.MERCHANT_NAME, [String]);
    intent.putExtra(CzConstant.AMOUNT, [String]);
    intent.putExtra(CzConstant.DESCRIPTION, [String]);
    intent.putExtra(CzConstant.TRANSACTION_TYPE, [String]);
    intent.putExtra(CzConstant.MERCHANT_TRANSACTION_ID, [String]);
    intent.putExtra(CzConstant.SECRETKEY, [String]);
    intent.putExtra(CzConstant.MOBILEUSER_ID, [String]);
    intent.putExtra(CzConstant.AGGREGATOR_ID,[String]);
    intent.putExtra(CzConstant.AUTOBACKPREF, [String]);
    intent.putExtra(CzConstant.AUTO_PRINT, [String]);
    intent.putExtra(CzConstant.AUTO_REDIRECT, [String]);
    intent.putExtra(CzConstant.REDIRECT_TIME, [String]);
    intent.putExtra(CzConstant.DISABLE_PRINT_BUTTON, [String]);
    startActivity(intent);
} else {
    //TODO: Handle Application Not Installed
}

4.2.2 Android Input

No.	Name	Description	Example
1.	`TRANSACTION_TYPE` com.cashlez.android.a pi.field.TRANSACTION_TYPE	MANDATORY (M) String Enumeration Currently only support (Max 30) “SALE”.	SALE
2.	`MERCHANT_NAME`	M String Alphanumeric The merchant name registered in cashlez	Pt Cwi
3.	`MERCHANT_TRANSACTION_ID` com.cashlez.android.a pi.field.MERCHANT_TRX_ID	M String Alphanumeric The [10,40] merchant transaction identifier. Unique for every transaction of a merchant	TRXID0001
4.	`AMOUNT`	M String Numeric The total Max 12 amount of sale	50000
5.	`AMOUNT_EXTRA`	FUTURE USE, String Numeric The IGNORED Max 12 amount for tip. Future use.	10000
6.	`CURRENCY_CODE`	M String ISO 4217 Currently only supports “IDR”	"IDR"
7.	`DESCRIPTION` com.cashlez.android.a pi.field.DESCRIPTION	OPTIONAL (O) String Text max. Sale or 255 purchase description.	Laptop 4 Pcs
8.	`APP_ID`	M String Alphanumeric The APP with "." ID that and "-". calls Max 20 Cashlez App. The unique name and version of the app should be there.	"MerchantApp-1.0"
9.	`EMAIL`	OPTIONAL (O) String Text max. 255 Email Address for send receipt	taslim@cashlez.com
10.	`NO_HANDPHONE`	OPTIONAL (O) String Numeric Max 12 No Handphone for send	085714666988
11.	`CASHLEZ_PACKAGE_NAME`	M String Text max. 255 The package name that calls Cashlez App. The unique name and version of the app should be there	com.cashlez .android.garuda
12.	`CASHLEZ_TRANSACTION_ID`	M (Void) String Numeric Max 20 Transaction ID for void	8008012305 0916000582
13.	`SECRETKEY`	M (LOGIN AGGREGATOR) String Text max. 255 Server Public Key + Client Private Key Request to Cashlez
14.	`MOBILEUSER_ID`	M (LOGIN AGGREGATOR) String Text max. 40 User ID for login Request to Cashlez	"OUTLETZ USER1"
15.	`AGGREGATOR_ID`	M (LOGIN AGGREGATOR) String Text max. 255 Aggregat or ID for login Request to Cashlez	"outletz"
16.	`PAYMENT_NAME`	O (OPTIONAL) String Text max.255 Payment Type selected	“`DEBIT_OR _CREDIT_CARD`”
17.	Auto Print	`com.cashlez.android.api.field.AUTO_PRINT` if Boolean true (true/false)
18.	Auto Redirect	`com.cashlez.android.api.field.AUTO_REDIRECT` if Boolean true Redirect Time is required (true/false) if false must Redirect Time must wait 10 seconds
19.	Redirect Time	`com.cashlez.andandroid.api.field.REDIRECT_TIME` Integer (only if Auto redirect active)
20.	Disable Print Button	`com.cashlez.android.api.field.DISABLE_PRINT_BUTTON` Boolean (true/false)

List of possible PAYMENT_NAME

CzConstant

public final static String AMOUNT = "com.cashlez.android.api.field.AMOUNT";
public final static String MERCHANT_NAME = "com.cashlez.android.api.field.MERCHANT_NAME";
public final static String DESCRIPTION = "com.cashlez.android.api.field.DESCRIPTION";
public final static String MERCHANT_TRANSACTION_ID = "com.cashlez.android.api.field.MERCHANT_TRX_ID";
public final static String CASHLEZ_TRANSACTION_ID = "com.cashlez.android.api.field.CASHLEZ_TRX_ID";
public final static String TRANSACTION_TYPE = "com.cashlez.android.api.field.TRANSACTION_TYPE";
public final static String PAYMENT_NAME = "com.cashlez.android.api.field.PAYMENT_NAME";
public final static String EMAIL = "com.cashlez.android.api.field.EMAIL";
public final static String NO_HANDPHONE = "com.cashlez.android.api.field.NO_HANDPHONE";
public final static String PRODUCT_IMAGE = "com.cashlez.android.api.field.PRODUCT_IMAGE";
public final static String SECRETKEY = "com.cashlez.android.api.field.SECRETKEY";
public final static String AGGREGATOR_ID = "com.cashlez.android.api.field.AGGREGATOR_ID";
public final static String MOBILEUSER_ID = "com.cashlez.android.api.field.MOBILEUSER_ID";
public final static String AUTOBACKPREF = "com.cashlez.android.api.field.AUTOBACKPREF";
public final static String AUTO_PRINT = "com.cashlez.android.api.field.AUTO_PRINT";
public final static String AUTO_REDIRECT = "com.cashlez.android.api.field.AUTO_REDIRECT";
public final static String REDIRECT_TIME = "com.cashlez.android.api.field.REDIRECT_TIME";
public final static String DISABLE_PRINT_BUTTON = "com.cashlez.android.api.field.DISABLE_PRINT_BUTTON";

public static final String ACTION_FINISH_PACKAGE = "FINISH_PACKAGE";
public static final String TRANSACTION = "com.cashlez.android.api.field.TRANSACTION";
public static final String MESSAGE = "MESSAGE";
public static final String RESULT = "RESULT";

Cancel
Warning
Success

public final static String RES_CANCEL = "Cancel";

Description

Transaction Discontinue/Cancel

public final static String RES_WARNING = "Warning";

Description

Transaction Error

public final static String RES_SUCCESS = "Success";

Description

Payment channel transaction Success

PAYMENT_NAME Option*

public final static String = "CASH";
public final static String = "CREDIT";
public final static String = "DEBIT";
public final static String = "DEBIT_OR_CREDIT_CARD";
public final static String = "CREDIT_WITH_POINT";
public final static String = "CASHLEZ_LINK";
public final static String = "LINK_AJA";
public final static String = "MINIATM";
public final static String = "INSTALLMENT";
public final static String = "INSTALLMENT|0009|I03|PIN";
public final static String = "INSTALLMENT|0008|I06|SIGNATURE";
public final static String = "INSTALLMENT|0022|I03|PIN";
public final static String = "PREAUTH";
public final static String = "OVO";
public final static String = "GOPAY";
public final static String = "KREDIVO";
public final static String = "DANA";
public final static String = "EMONEY";
public final static String = "CARD_MOCK";
public final static String = "VA_TRANSFER";
public final static String = "SHOPEE_PAY";
public final static String = "ARTAJASA_VA";
public final static String = "PERMATA_VA";
public final static String = "BCA_VA";
public final static String = "VOSPAY";
public final static String = "GOMOBILE";
public final static String = "ATOME";
public final static String = "NOBU_QR_DYNAMIC";
public final static String = "INDODANA";
public final static String = "CASHBACK";

Direct Installment
If needed, installment can be selected directly bypassing the selection of bank and installment period selection page. This can be done by using specially formatted payment method.

Format

INSTALLMENT|<BANK CODE>|I<TENOR>|<VERIFICATION MODE>

Bank Code available

0008 - MANDIRI
0009 - BNI
0022 - CIMB

Available Verification Mode

PIN
SIGNATURE

CARD TESTING MOCKUP
As not all devices available to be used using card payment, it is possible to receive a mock up for card payment by using payment name as follows

public static final String CARD_MOCK = "CARD_MOCK";

Use the following amount for mock result

failed result (incorrect PIN, etc)
success result
Other amount -> cancel response

4.3 Programming Guide: Capture Response Data from Cashlez App

4.3.1 Android

Broadcast Receiver

To capture the response data from Cashlez app, you need to receive broadcast with action name equals finish_pkg as below;

Broadcast Receiver
@Override
public void onReceive(Context context, Intent intent) {
    if (intent.getAction().equals(CzConstant.ACTION_FINISH_PACKAGE)) {
        String result = intent.getExtras().getString(CzConstant.RESULT);
        String message = intent.getExtras().getString(CzConstant.MESSAGE);
        switch (result != null ? result : CzConstant.RES_CANCEL) {
            case CzConstant.RES_WARNING:
                receiverListener.showWarning(message);
                break;
            case CzConstant.RES_CANCEL:
                receiverListener.showCancel(message);
                break;
            case CzConstant.RES_SUCCESS:
                StringBuilder sb = new StringBuilder();
                if (intent.hasExtra(CzConstant.TRANSACTION)){
                    Bundle bundle = intent.getExtras();
                    if (bundle.get(CzConstant.TRANSACTION) instanceof ArrayList){
                        ArrayList<HashMap<String, String>> listResponse = (ArrayList<HashMap<String, String>>) bundle.get(CzConstant.TRANSACTION);
                        for (int i = 0; i < listResponse.size(); i++){
                            for (ResponseDataEnum response : ResponseDataEnum.values()) {
                                if (response.getValue() != null){
                                    sb.append("Response Tag: ").append(response.getValue()).append(", ")
                                        .append("Value: ").append(listResponse.get(i).get(response.getValue())).append("\n");
                                }
                            }
                        }
                    } else if (bundle.get(CzConstant.TRANSACTION) instanceof HashMap){
                        HashMap<String, String> responseMap = (HashMap<String, String>)intent.getSerializableExtra(CzConstant.TRANSACTION);
                        for (ResponseDataEnum response : ResponseDataEnum.values()) {
                            sb.append("Response Tag: ").append(response.getValue()).append(", ")
                                .append("Value: ").append(responseMap.get(response.getValue())).append("\n");
                        }
                    }
                }
                Log.d(TAG, sb.toString());
                //TODO: Handle Response String
                break;
        }
    }
}

note

When QR payment (GOPAY, OVO, LinkAja, Kredivo) is cancelled, it will go to Success, to check whether transaction is really success or cancelled, approvedAmount will be null when transaction is cancelled while not null when transaction is paid.

4.3.2 Android Output

OUTPUT

No.	Name	Condition Type	Data Type	Format Description	Example
1.	`RESPONSE_CODE`	M	String Numeric	With 6 characters length `000000` for `SUCCESS` and `000001` for `HOST_REJECTED` Note: Refer to New Table: List of Available Response Code	`000000`
2.	`HOST_RESPONSE_CODE`	C	String Alphanumeric	ISO 8583 DE 39 L (C) - if Length 2 Response code transaction reached issuer.	`00`, `51`, `55`, `etc`
3.	`ERROR_MESSAGE`	C	String Alphanumeric	if error String Text Max.255 The human occurred readable error message. Currently only support English.	You have exceeded limit (defined in VAPN)
4.	`APP_ID`	M	String Alphanumeric	The Cashlez App with "." and ID, the unique "-". Max 20 name and version of the app is returned.	Cashlez App 1.0

BELOW IS ONLY APPLICABLE WHEN `RESPONSE_CODE=0000` and `ACQUIRER_RESPONSE_CODE=0`

No.	Name	Condition Type	Data Type	Format Description	Example
5.	`APPROVAL_CODE`	C	String Alphanumeric	The approval Max 8 & code from HOST.	`152359`
6.	`APPROVAL_STATUS`	M	String Alphanumeric	Approval Status Max 3 from Cashlez	`100`
7.	`CASHLEZ_TRANSACTION_ID`	C	String Alphanumeric	Cashlez Length 20 transaction identifier. Unique for every transaction.	`TXID00034`
8.	`MERCHANT_TRANSACTION_ID`	M	String Alphanumeric	The merchant [10,40] transaction identifier. Unique for every transaction of a merchant.	`000001`
9.	`BATCH_NO`	C	String Numeric	The number of the Length 6. Batch where the transaction will be settled.	`1`
10.	`APPROVED_AMOUNT`	C	String Numeric	Max The total amount 12 that is approved.	`50000`
11.	`APPROVED_AMOUNT_EXTRA`		String Numeric	String Numeric. Max 12 The amount for tip that is approved. FUTURE USE, IGNORED Future use	`10000`
12.	`APPROVED_CURRECY_CODE`	C	String	ISO 4217 Currently only support `“IDR”`	`"IDR"`
13.	`PAYMENT_TYPE`	C	String Enumeration	Payment type we call select from Max. 10 Enumeration.	`DEBIT`, `CREDIT`, `CASH`
14.	`MASKED_PAN`	C	String Numeric	Max The masked credit 19 card number.	512676** 7667
15.	`RRN`	C	String Alphanumeric	Retrieval Max 12 reference number. Acquirer reference number, the unique number of a transaction given by the acquirer bank. Usually used as reference during chargeback	`"0123456789 AB"`
16.	`TRANSACTION_DATETIME`	C	String	`DD/MM/YYYY` Transaction date `hh:mm:ss.sss` and time in 24-Hour format	`17/08/2015` `23:59:59`
17.	`ACQUIRER_BANK_NAME`	C	String	Text Max. 50 Registered bank name in Cashlez	`"Bank Cashlez"`
18.	`EMAIL`	C	String	Text Email Address for customer	test@cashlez.com
19.	`NO_HANDPHONE`	C	String	Text Phone Number for customer	`08121122334455`
20.	`LATITUDE`	M	String Text	Transaction Location	`-0.123456`
21.	`LONGITUDE`	M	String Text	Transaction Location	`12.123456`
22.	`REDEEMED_AMOUNT`	C	String Text	Amount used during the transaction for the point transaction	`12000`
23.	`REDEEMED_POINT`	C	String Text	Point Used on the transaction	`500`
24.	`BALANCE_AMOUNT`	C	String Text	Remaining point balance in Rupiah (BNI)	`6000`
25.	`BALANCE_POINT`	C	String Text	C String Text Remaining point balance in point (CIMB)	`6000`
26.	EXPIRED_DATE	M	String Text	`yyyy-MM-dd` VA Number expiry `HH:mm:ss time`	`2020-11-05` `23:59:59`
27.	VA_NUMBER	M	String Text	Test VA Number generated	`7011010057280001`