InStore Payment API Android

Version: 4.08.04

The estimated time to complete an integration with the Comercia 2.0 solution is 21 days. Our support team is fully available to assist you during this development process and ensure a successful implementation.

Introduction

InStore Payment API is a product to process payments with a single API for Comercia payments. It is easy to use, you just send a payment and receive the response.

This guide describes an Android client implementation of an AIDL that guarantees a secure IPC.

The advantages of InStore Payment API compared to the intent-based system include the fact that you don’t have to change the software and can achieve real-time interaction based on callbacks without depending on intent-filtering engines that are overly complex for a plug and play connection. Another advantage of an AIDL service compared to intent, socket or similar mechanisms is the fact that Android certifies the IPC for the AIDL service is secure.

Below is an explanation of each part of the service on the client solution side and how it can be used, with useful examples.
This service can be implemented on any device that meets the following requirements:

An Android InStore payment terminal (in-terminal mode) or an Android device (in-android-ecr mode).
The terminal is equipped with the Comercia payment app (certified and duly installed).

NOTE (1): The service installed on the Android payment terminal can also receive requests from devices with the Windows operating system (in-windows-ecr mode). For more information on how to integrate this solution into a Windows device, see the InStore Payment API Windows guide.

NOTE (2): To facilitate integration, the InStore Payment API installed on the platform or payment terminal allows you to run a payment simulation so you don’t have to depend on a real payment application and don’t need physical cards to check the full workflow.
This simulator is simply a series of screens that are shown directly in the InStore Payment API, so you don’t need an additional request. So, although by default the Comercia payment app will always be used, you can also use the simulator.
More detailed information on this choice of apps is available in each function in the ADI AIDL Payment Definition section.

Files provided

In the Welcome pack you will get the file instore-payment-api-android-XX.XX.XX-debug.zip with the following content:

instorepaymentapilib-XX.XX.XX.aar: Library the integration app must use for the various InStore Payment API functionalities.
instorepaymentapi-XX.XX.XX-debug.apk: InStore Payment API, which will receive requests from the integrator app.

You will also find the “PaymentApp” folder with the following contents:

cgp-XX.XX.XX-pre.apk: Payment app that will read the card and communicate with the Comercia servers. The version that points to the staging environment is distributed.

Other apps required for the ecosystem to work properly, such as the HAL, which depends on the terminal used, should come pre-installed or will be loaded remotely. Apart from all the elements necessary to develop a solution, the “InStorePaymentApiDemo” folder also comes with a sample project with a simple application of the InStore Payment API.

These files are provided in the welcome email. Also, they are debug versions, so they are intended for test terminals. They should not be installed on production terminals. Other packages will be provided for those terminals.

Work mode

This API can be used in two different environments:

In-Terminal: ECR software and payment app on the same terminal, for example DX8000.
In-ECR: ECR software on a separate device from the payment app, for example ECR software on an AECR C5, C9 or Raspberry Pi and the payment app on the payment device.
- The connection with the payment app is handled by instorepaymentapi-XX.XX.XX-debug.apk via WiFi/4G.
- You need the deviceID for the ECR device, which will send the request to the payment device.
- It must be paired with the payment device. See the Pairing process section of this guide.

Pairing process

If you’re working in In-ECR mode, you can pair the payment device and ECR. There are two pairing processes:

1. On the ECR, open the “InStorePaymentApi” app and you’ll see:

2. On the payment device, open the “InStorePaymentApi” app, click the “QR” button and capture the QR code on the ECR.
After a few seconds, the pairing process will be completed successfully.

3. On the ECR you will see:

1. If there is a problem with the camera that prevents you from reading the QR code, you can manually enter the ECR ID into the payment device and press the button to manually pair it:

How to use the AIDL

NOTE: First, if there is any version of the Ingenico Payment Service installed on the terminal (a project prior to InStore Payment API), it must be removed beforehand to make sure there isn’t any conflict with the new version to install.

1. Only for the In-Android-ECR mode, install “instorepaymentapi-XX.XX.XX-debug.apk” on the cash register.

2. Install “instorepaymentapi-XX.XX.XX-debug.apk” on the payment device.

NOTE: How the software is installed depends on the terminal manufacturer, as there may be different methods for each device.

3. Create and open your Android Studio project.

NOTE: As we mentioned in the previous section, there is a folder called “InStorePaymentApiDemo” in the zip file with a sample project with a simple application of the InStore Payment API.

4. Add permissions in the AndroidManifest.xml:

				
					<uses-permission android:name="com.comercia.permission.ACCESS_IN_STORE_PAYMENT_API" />

NOTE: From Android version 11, you have to expressly state which services will be linked in the Manifest, so the following must be added:

				
					<queries>
    <package android:name="com.comercia.instorepaymentapi" />
</queries>

5. To request an apiKey from Comercia, write to this email.

6. Copy the “instorepaymentapilib-XX.XX.XX.aar” provided to your <YourProject>\libs.

7. Make sure you include ‘*.aar’ in the module extensions for the application:

				
					dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])
}

8. Categorize ServiceConnection in your Activity:

				
					protected IInStorePaymentApi mInStorePaymentApi;
private ServiceConnection mServiceConnection = new ServiceConnection() {
    @Override
    public void onServiceConnected(ComponentName componentName, IBinder iBinder) {
        Log.d(TAG, "Service Connected");
        mInStorePaymentApi = IInStorePaymentApi.Stub.asInterface(iBinder);
    }
    @Override
    public void onServiceDisconnected(ComponentName componentName) {
        Log.d(TAG, "Service Disconnected");
        mInStorePaymentApi = null;
    }
};

9. Link the service to the method onCreate:

				
					@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    if (mInStorePaymentApi == null) {
        Intent intent = new Intent("InStorePaymentApi");
        intent.setPackage("com.comercia.instorepaymentapi");
        intent.putExtra("apiKey", "<your apiKey>");
        bindService(intent, mServiceConnection, Context.BIND_AUTO_CREATE);
    }
}

10. That’s it! Now you can start processing payments using the “payment” method:

				
					final Button button = findViewById(R.id.button_id);
button.setOnClickListener(new View.OnClickListener() {
    public void onClick(View v) {
        try {
            PaymentRequest request = new PaymentRequest();
            request.setPaymentApp("comercia");
            request.setAmount(125);
            mInStorePaymentApi.payment(request, callback);
        } catch (RemoteException e) {
            Log.d(TAG, "Exception: " + e.getMessage());
        }
    }
});

11. And handling transaction responses by processing the object returned in “PaymentResponse”:

				
					IInStorePaymentApiCallback.Stub callback = new IInStorePaymentApiCallback.Stub() {
    @Override
    public void onPaymentReceived(String transactionId) {
        Log.d(TAG, "transactionId: " + transactionId);
    }
    @Override
    public void onPaymentResult(PaymentResponse result) {
        Log.d(TAG, "result: " + result.getResult());
        Log.d(TAG, "status: " + result.getStatus());
    }
    @Override
    public void onPrintResult(int result) {
        Log.d(TAG, "printResult: " + result);
    }
    @Override
    public void onMerchantResponse(String response) {
        Log.d(TAG, "response: " + response);
    }
    @Override
    public void onPaymentAppConfigResponse(String response) {
        Log.d(TAG, "response: " + response);
    }
};

12. Important: Remember to unlink the InStore Payment API when you destroy the activity:

				
					@Override
protected void onDestroy() {
    super.onDestroy();
    unbindService(mServiceConnection);
}

Definition of AIDL API payment

This section has the definition of the method and description of the parameters.

Object InStorePaymentApiCallback

The following methods must be implemented:

onPaymentReceived (transactionId string) : transactionId is a UUID that identifies the transaction on cloud systems.
onPaymentResult (result of PaymentResponse): to get the result of the transaction, the interface must be implemented. See Object PaymentResponse.
onPrintResult (int result): to get the print result. See onPrintResult (int result).
onMerchantResponse (string response): response to a commercial operation (settlement, totalling, etc.). See onMerchantResponse (string response).
onPaymentAppConfigResponse (string response): response that contains the payment application settings. See onPaymentAppConfigResponse (string response).
onDeviceConfigResponse (string response): response containing device configuration. It is used to obtain the configuration of the device when is requested. See onDeviceConfigResponse (string response).

Object PaymentResponse

These are the parameters for the object PaymentResponse:

Name	Type	Description
getDeviceId	String	Token for the payment terminal device.
getTransactionType	String	Type of refund transaction. The possible values are: “SALE” “REFUND” “READCARD” “PREAUTHNEW” “PREAUTHUPDATE” “PREAUTHCONFIRM”
getAmount	Long	Returns the payment amount.
getCurrencyCode	String	Returns the currency code for the transaction (currency code compatible with ISO4217 in string format).
getTransactionNumber	String	Transaction number on the receipt. This number should be used for refunds, updates and pre-authorization confirmations, and to print a copy of the receipt.
getResult	int	Returns the result of the transaction. The possible values are: TRANSACTION_RESULT_UNKNOWN = 0; TRANSACTION_ACCEPTED = 100; TRANSACTION_NOT_ACCEPTED = 101;
getStatus	int	Returns the extended code for the result. The possible values are: // Default status code TRANSACTION_STATUS_UNKNOWN = -1; // Extended status codes accepted TRANSACTION_ACCEPTED_ONLINE = -1001; TRANSACTION_ACCEPTED_OFFLINE = -1002; CARD_READ = -1003; // Extended status codes declined TRANSACTION_DENIED_ONLINE = -1010; TRANSACTION_DENIED_OFFLINE = -1011; // Extended status codes cancelled TRANSACTION_CANCELLED_BY_USER = -1020; TRANSACTION_CANCELLED_DUE_TIMEOUT = -1021; ERR_COMMS_ECR_PAYMENTSERVER = -1022; ERR_COMMS_PAYMENTSERVER_INSTOREPAYMENTAPI = -1023; ERR_COMMS_INSTOREOPAYMENTAPI_PAYMENTAPP = -1024; // Extended status codes error CARD_ERROR = -1030; CURRENCY_ERROR = -1031; NO_MERCHANT_NUMBER_SET = -1032; NO_TERMINAL_NUMBER_SET = -1033; NO_AMOUNT_SET = -1034; NO_KEYS = -1035; NO_TRANSACTION_FOUND = -1036; UNKNOWN_PAYMENT_APP = -1037; PAYMENT_ENVIRONMENT_ERROR = -1038; PAYMENT_APP_BUSY = -1039;
getPaymentApp	String	Returns the payment app that processed the transaction.
getAdditionalData	String	Returns additional data in JSON String format. Check JSON for additional data.

JSON Additional data

Depending on the version of the payment application, you may receive additional information. This information is OPTIONAL and comes in a JSON string as follows: All the fields below are optional:

				
					"additionalData": {
    "posId": "string", // POS number
    "employeeId": "string", // Employee, seller, waiter, agent id or number
    "tableId": "string", // Table number in case of a restaurant
    "orderId": "string", // Order number
    "response": "string", // Message received from bank host
    "msgKO": "string", // Error description in case of error
    "stackTraceKO": "string", // In case of exception, the exception description
    "customerId": "string", // Customer id of a client who wants to perform tokenization
    "subscriptionId": "string", // Subscription id of a tokenized card
    "token": "string", // Token of a tokenized card
    "tokenizerCode": "string", // Result of a tokenization / tokenized transaction
    "acquirerCode": "string", // Acquirer code which finally processed the transaction
    "acquirerTerminalId": "string", // Terminal identification within processor system
    "transactionData": {
        "type": "string", // Transaction type (PAYMENT, REFUND...)
        "card": "string", // Card number for merchant receipt
        "cardClient": "string", // Card number for customer receipt
        "expiration": "string", // Expiration date in AAMM format
        "terminal": "string", // Terminal number
        "identifierRTS": "string", // Transaction identifier in Redsys systems
        "onlyCustomerReceipt": boolean, // Indicates that only customer receipt must be printer
        "isTaxFree": boolean, // Tax free could be appliet to this transaction
        "transactionDate": "string", // Transaction date in yyyy-MM-dd HH:mm:ss format
        "rateApplied": "string", // Tax type applied to this transaction (CRED, DEB)
        "state": "string", // 1: request received, 2: request in payApp, 3: transaction stated, 4: waiting
        card, 5: card detected, 6: waiting PIN, 7: PIN entered, 8: msg ready to send, 9: connected, 10: msg sent, 11:
        msg received, 12: response processed, 13: preparing answer, 14: sending answer
        "result": "string", // Transaction result (APPROVED, DENIED)
        "responseCode": "string", // Authorisation or denied code
        "authorizationNumber": "string", // Authorisation number
        "cardType": "string", // VISA, MASTERCARD, MAESTRO, AMEX, DINERS, DISCOVER, UNIONPAY, JCB
        "cardCountry": "string", //ISO-3166 numeric code
        "invoice": "string", // Invoice number
        "cardHolder": "string", // Cardholder name
        "isEmvTransaction": boolean, // Indicates that this transaction is EMV
        "resVerification": "string", // EMV Verification method
        "transactionCounter": "string", // EMV Transaction counter
        "cardSec": "string", // EMV Sequence number
        "appId": "string", // EMV application identifier
        "appLabel": "string", // EMV application label
        "isPinAuthenticated": boolean, // Transaction has been authenticated by PIN
        "isDCC": boolean, // Indicates that this transaction is DCC
        "isContactless": boolean, // Indicates that this transaction is contactless
        "capturedMode": integer // 0: MSR, 1: MANUAL, 2: CHIP, 3: WALLET, 4: CLESS, 5: SCANNER, 6: MSR
        FALLBACK, 7: MANUAL FALLBACK
        "panToken": "string", // PAN in case of mobile payment
        "resolutionType": integer, // Resolution type (0: LOCAL, 1: HOST)
        "actionCode": "string", // Action code returned by payment gateway
        "authorisingCentre": "string", // Authorising centre
        "fucId": "string", // Merchant id
        "ARC": "string", // P-55.8A EMV
        "isFallback": boolean, // Indicates that this transaction has been resolved with fallback
        "transactionReference": "string", // Transaction reference number in Base64 format
        "secureData": "string", // P-53 EMV
        "pinpadData": "string", // P-48.16 EMV
        "authenticationType": integer, // 0: NONE, 1: PIN, 2: SIGNATURE, 3: PIN AND SIGNATURE
        "clessCardBrand": "string", // Contactless card brand
        "track2": "string", // Track 2
        "track1": "string", // Track 1
        "isPrivateCard": boolean, // Indicates if the card used is privated or not
        "privateCardType": "string" // Private card type
        "transactionCurrencyCode": "string" // Transaction currency code
        "location": "string" // Transaction location
        "fucName": "string" // Merchant name
        "modifiers": { // Additional information for current transaction: DCC, donations...
            "aIDDonation": "string" // EMV application identifier for donation (eg: "A0000000031010")
            "amount": "string" // Amount for DCC transaction (eg: "64")
            "amountDonation": "string" // Donation amount (eg: "50")
            "amountnoMarkup": "string" // Amount for DCC transaction without markup (eg: "61")
            "authorizationDonation": "string" // Authorization for donation (eg: "677821")
            "cARDcountry": "string" // Country for DCC card (eg: "USA")
            "cARDlang": "string" // Language for DCC card
            "currency": "string" // Currency for DCC card (eg: "USD")
            "currencyExponent": "string" // Number of decimals for DCC card currency (eg: "2")
            "dCCType": "string" // DCC type (eg: "002")
            "destinationDonation": "string" // Donation campaign name (eg: "Campaña 1 de pruebas")
            "exchange": "string" // Exchange (eg: "60817929")
            "id": "string" // Modifier ID (eg: "MultiCurrency", "Donations")
            "idDonation": "string" // Donation ID (eg: "MkWAF38/O0i4ZVnqf3+7xw")
            "idTransactionDonation": "string" // Donation transaction ID (eg: "174144")
            "markup": "string" // Markup for DCC transaction (eg: "200")
            "merchantIdDonation": "string" // Donation merchant ID (eg: "266916725")
            "status": integer // Status for modifier: 2 = accepted (eg: 2)
            "terminalIdDonation": "string" // Donation terminal ID (eg: "00000001")
        }    
    }
}

onPrintResult (int result)

The possible values are:

PRINT_OK = 0;
PRINT_ERROR = -2000;
PRINT_CANCEL = -2001;
PRINT_NO_COPY = -2002;
PRINT_NO_PAPER = -2003;

onMerchantResponse (string response)

The response returned for “endOfDay” and “totals” in a JSON string as follows:

				
					"response": {
    "Date": "string", // Example: "13/09/2021"
    "FirstDate": "string", // Example: "13/09/21"
    "FirstOp": "string", // Example: "147864"
    "LastDate": "string", // Example: "13/09/21"
    "LastOp": "string", // Example: "147875"
    "OpsData": [{
        "Amount": "string", // Example: "12,83 €"
        "TicketTitle": "string", // Example: "VENTA"
        "Value": "string" // Example: "3"
    }],
    "OpsDonationData": [{
        "Amount": "string", // Example: "0,50 €"
        "TicketTitle": "string", // Example: "DONACIÓN"
        "Value": "string" // Example: "1"
    }],
    "OpsAcquirersData":[
    {
        "Amount": "string", // Example: "0,50 €"
        "TicketTitle": "string", // Example: "CAIXABANK"
        "Value": "string" // Example: "1"
    }],
    "Place": "string", // Example: "Barcelona"
    "Session": integer, // Example: 1
    "Store": "string", // Example: "329811087"
    "TicketHeader": "string", // Example: "Comercia Global Payments PRUEBAS"
    "Time": "string", // Example: "10:49"
    "Tpv": "string", // Example: "00000001"
    "contentTotalDonationOps": [{
        "Amount": "string", // Example: "0,50 €"
        "TicketTitle": "string", // Example: "TOTAL"
        "Value": "string"
    }],
    "contentTotalOps": [{
        "Amount": "string", // Example: "12,33 €"
        "TicketTitle": "string", // Example: "TOTAL"
        "Value": "string" // Example: "4"
    }],
    "From": "string", // Example: "Desde op"
    "OperationTicket": "string", // Example: "Op."
    "SessionTicket": "string", // Example: "Ses."
    "To": "string", // Example: "a op"
    "txtBodyMainTitle": "string", // Example: "CIERRE MANUAL"
    "txtHeaderBussines": "string", // Example: "COMERCIO"
    "txtHeaderTPV": "string", // Example: "TPV"
    "txtTotalsAmount": "string", // Example: "Importe"
    "txtTotalsDonations": "string", // Example: "DONACIONES"
    "txtTotalsOperations": "string", // Example: "OPERACIONES"
    "txtTotalsQuantity": "string" // Example: "Cantidad"
    "txtTotalsAcquirers": "string", // Example: "OPERACIONES ADQUIRENTES"
    "txtTotalsAcquirersAmount": "string", // Example: "10,50€"
    "txtTotalsAcquirersQuantity": "string" // Example: "5"
}

The response returned for “details” is a JSON string as follows:

				
					"response": {
    "Merchant": {
        "Terminal": "string", // Example: "00000001"
        "Id": "string", // Example: "329811087"
        "Location": "string", // Example: "Barcelona"
        "Name": "string" // Example: "Comercia Global Payments PRUEBAS"
    },
    "Report": {
        "Currency": "string", // Example: "€"
        "Date": "string", // Example: "13/09/2021"
        "FirstDate": "string", // Example: "20210913"
        "FirstTransaction": "string", // Example: "147864"
        "LastDate": "string", // Example: "20210913"
        "LastTransaction": "string", // Example: "147875"
        "Session": {
            "Date": "string", // Example: "20210913"
            "Number": integer // Example: 1
        },
        "Time": "string", // Example: "10:49"
        "Transactions": [{
            "AmountTicket": "string", // Example: "9,00 €"
            "CardIssuer": "string", // Example: "VISA ORO"
            "CardNumber": "string", // Example: "************4002"
            "Date": "string", // Example: "13/09/2021"
            "Id": "string", // Example: "147869"
            "OriginalTransactionDate": "string",
            "OriginalTransactionId": "string",
            "Time": "string", // Example: "10:46"
            "TypeText": "string", // Example: "VENTA"
            "DonationAmount": "string", // Example: "0,50 €"
            "DonationString": "string" // Example: "DONACIÓN"
        }]
    },
    "DateTicket": "string", // Example: "Fecha"
    "ExtractPos": "string", // Example: "EXTRACTO TPV"
    "From": "string", // Example: "Desde op"
    "MerchantTicket": "string", // Example: "COMERCIO"
    "OperationTicket": "string", // Example: "Op."
    "Original": "string", // Example: "Original"
    "Pos": "string", // Example: "TPV"
    "SessionTicket": "string", // Example: "Ses."
    "To": "string" // Example: "a op"
}

If it is impossible to process the merchant’s operation, the corresponding error code will be returned:

				
					{
"errDescription": "string", // Example: "501"
}

Some potential errors include:

501 = Not processed: the reconciliation info doesn't match
601 = Not processed, Totals not available
602 = Not processed, Detail not available
603 = Not processed, Receipt not found
604 = Not processed, ParamsSync not available
605 = Not processed, Donation not available

onPaymentAppConfigResponse (string response)

The response returned for “getPaymentAppConfig” is a JSON string as follows:

				
					"paymentAppConfig": {
    "merchantId": "string", // Example: "329811087"
    "terminalId": "string", // Example: "00000001"
}

onDeviceConfigResponse (string response)

This method informs that the “getDeviceConfig” request is completed (successfully or not) and retrieve the information of the payment app. The response returned for “getDeviceConfig” is represented in a JSON string as follows:

				
					"deviceConfig": { 
    "mode": "string", // Code that indicates the device state. 0: Produce, 1: Normal, 2: Repair, 3: Mockup, 4: Not Available, -1: Unknown. Example: "3" 
    "serialNo": "string", // Serial number that identifies the device. Example: "248GFA1243411421" 
    "iccSim": "string", // ICC SIM code that identifies the SIM card if it is present. Example: "894774828271818171" 
    "halVersion": "string", // Version code of the Hal application installed in the device. Example: "01.06.01" 
    "model": "string", // Model of the device. Example: "DX8000" 
    "manufacturerCode": "string", // String of length 5 padded to the left with space (0x20) character that indicates the manufacturer code. Example: "87" 
}

Object ICancelTransactionCallback

This object is filled with a method that let InStorePaymentApi and the payment device communicate to inform that the transaction cancelled has been completed (successfully or not).

onTransactionCancel(int result): to get the cancellation result. It is used to inform that the transaction cancellation has been completed or that an error occurred when trying to. Possible values are:

				
					RESULT_OK = 1; //transaction was cancelled correctly
RESULT_NO_TRANSACTION = 2; //there is no transaction to cancel 
RESULT_INVALID_STATE = 3; //transaction is in an state that cannot be cancelled remotely
RESULT_INVALID_TRANSACTION = 4; //transaction is not a remote transaction
RESULT_INVALID_PAYMENT_APP = 5; //payment app not allowed to cancel

Payment

Initiates a payment transaction with input parameters. This method handles all steps of the transaction, including the user interface and receipt printing. The app that calls has to handle the callback to get the transaction result.

payment (PaymentRequest paymentRequest, InStorePaymentApiCallback callback)

Parameters

These are the parameters for payments:

Name	Status	Type	Description
paymentRequest	Required	PaymentRequest Object	The parameters are as follows: setDeviceId setPaymentApp setAmount setCurrencyCode setOtherData
setDeviceId	Only required for In-ECR mode and if not paired with another payment device	String	Token for the payment terminal device. i.e: “8b1bad62eb99732a82b45e”
setPaymentApp	Required	String	Payment app name. The possible values are: “comercia” “dummy”
setAmount	Required	Long	Amount, without decimals (ISO4217). So 10.00 is 1000 and 00.01 is 1.
setCurrencyCode	Optional	String	Currency code compatible with ISO4217 in string format. The default value is “EUR”.
setOtherData	Optional	String	JSON String that represents extra information that can be important in some cases to identify a transaction. See the Other JSON data section.
callback	Required	InStorePaymentApiCallback Object	See definition of the object InStorePaymentApiCallback.

Other JSON info

				
					"otherData": {
    "printReceipt": integer // 0: print both tickets, 1: don’t print any ticket, 2: send only
    merchant ticket by email(
        if it is supported by payment app),
    3: print only customer ticket "posId": "string", // POS number
    "employeeId": "string", // Employee, seller, waiter, agent id or number
    "tableId": "string", // Table number in case of a restaurant
    "otherAmount": "string" // Tip or donation amount, without decimals (as per ISO4217)
    "orderId": "string" // Order number
    "indTokenization": boolean // Indicates if it is a tokenization request
    "indCofUse": "string", // Indicates the objective of tokenization. “R”: recurrent, “I”: installments, “C”: unique purchase,“D”: delayed,“E”: resubmission,“H”: reauthorization,“M”: incremental,“N”: no show.
    "subscriptionId": "string" // Indicates the subscription id of a tokenized card
    "customerId": "string" // Indicates the customer id of a client who wants to perform tokenization / a tokenized transaction 
    "token": "string" // Indicates the token of a tokenized card
}

Refunds

Initiates a refund transaction with some input parameters. This method handles all steps of the transaction, including the user interface and receipt printing. The app that calls has to handle the callback to get the transaction result.

Parameters

These are the parameters for refunds:

Name	Status	Type	Description
refundRequest	Required	refundRequest object	The parameters are as follows: setDeviceId setPaymentApp setAmount setCurrencyCode setTransactionNumber setOtherData
setDeviceId	Only required for In-ECR mode and if not paired with another payment device	String	Token for the payment terminal device. i.e: “8b1bad62eb99732a82b45e”
setPaymentApp	Required	String	Name of the payment app. The possible values are: “comercia” “dummy”
setAmount	Required	Long	Amount, without decimals (según ISO4217). So 10.00 is 1000 and 00.01 is 1.
setCurrencyCode	Optional	String	Currency code compatible with ISO4217 in string format. The default value is “EUR”.
setTransactionNumber	Required	String	Transaction number on the pre-authorization receipt.
setOtherData	Optional	String	JSON String that represents extra information that can be important in some cases to identify a transaction. See the Other JSON data section.
callback	Required	InStorePaymentApiCallback object	The content returned is the same as in the payment. See definition of the object InStorePaymentApiCallback.

getTransaction

Gets all the information for a transaction.

getTransaction (TransactionRequest transactionRequest, InStorePaymentApiCallback callback)

Parameters

These are the parameters for getTransaction:

Name	Status	Type	Description
transactionRequest	Required	transactionRequest Object	The parameters are as follows: setDeviceId setTransactionId
setDeviceId	Only required for In-ECR mode and if not paired with another payment device	String	Token for the payment terminal device. i.e: “8b1bad62eb99732a82b45e”
setTransactionId	Required	String	Transaction ID received in payment/refund in onPaymentReceived callback
callback	Required	InStorePaymentApiCallback Object	The content returned is the same as in the payment. See definition of the object InStorePaymentApiCallback.

printLastReceiptCopy

Prints a copy of the latest payment receipt. The app that calls has to handle the callback to get the print result.

printLastReceiptCopy (deviceId string, paymentApp string, InStorePaymentApiCallback callback)

Parameters

These are the parameters for printLastReceiptCopy:

Name	Status	Type	Description
deviceID	Only required for In-ECR mode and if not paired with another payment device	String	Token for the payment terminal device. i.e: “8b1bad62eb99732a82b45e”
paymentApp	Required	String	Payment app name. The possible values are: “comercia” “dummy”
callback	Required	InStorePaymentApiCallback Object	To get the result of the transaction, onPrintResult (int result) an interface must be implemented. See definition of the object InStorePaymentApiCallback.

getVersion

Gets the version of the AIDL API.

getVersion()

Return

Type	Description
String	“04.00.00”

printHTML

Print an HTML string. The app that calls has to handle the callback to get the print result.

This function is only allowed in terminal mode (not on ECR devices).

printHTML (deviceId string, htmlString, InStorePaymentApiCallback callback)

Parameters

These are the parameters for printHTML:

Name	Status	Type	Description
deviceID	Only required for In-ECR mode and if not paired with another payment device	String	Token for the payment terminal device. i.e: “8b1bad62eb99732a82b45e”
htmlString	Required	String	String in HTML format to print.
callback	Required	InStorePaymentApiCallback Object	To get the result of the transaction, onPrintResult (int result) an interface must be implemented. See definition of the object InStorePaymentApiCallback.

readCard

Only reads non-financial magnetic cards. Only reads tracks 1 and 2 (returned in AdditionalData).

readCard (deviceId string, showIndications boolean, timeout int, InStorePaymentApiCallback callback)

Parameters

These are the parameters for readCard:

Name	Status	Type	Description
deviceID	Only required for In-ECR mode and if not paired with another payment device	String	Token for the payment terminal device. i.e: “8b1bad62eb99732a82b45e”
showIndications	Required	Boolean	If ”true”, the InStorePaymentApi will show messages on screen telling the user to swipe the magnetic strip through the reader
timeout	Required	int	Maximum timeout for reading the card before it gives an error. It is limited to 60 seconds.
callback	Required	InStorePaymentApiCallback Object	The content returned is the same as in the payment. See definition of the object InStorePaymentApiCallback.

stopReadCard

Cancels current reading of non-financial cards.

stopReadCard (deviceId string)

Parameters

Name	Status	Type	Description
deviceID	Only required for In-ECR mode and if not paired with another payment device	String	Token for the payment terminal device. i.e: “8b1bad62eb99732a82b45e”

endOfDay

Executes the day’s settlement.

endOfDay (deviceId string, paymentApp string, printReceipt boolean, InStorePaymentApiCallback callback)

Parameters

These are the parameters for endOfDay:

Name	Status	Type	Description
deviceID	Only required for In-ECR mode and if not paired with another payment device	String	Token for the payment terminal device. i.e: “8b1bad62eb99732a82b45e”
paymentApp	Required	String	Name of the payment app. The possible values are: “comercia” “dummy”
printReceipt	Required	boolean	If ”true”, a receipt of the operation will be printed.
callback	Required	InStorePaymentApiCallback Object	To get the response to the operation, the onMerchantResponse interface (response string) must be implemented. See definition of the object InStorePaymentApiCallback.

Totals

Adds up the totals.

totals (deviceId string, paymentApp string, printReceipt boolean, InStorePaymentApiCallback callback)

Parameters

Name	Status	Type	Description
deviceID	Only required for In-ECR mode and if not paired with another payment device	String	Token for the payment terminal device. i.e: “8b1bad62eb99732a82b45e”
paymentApp	Required	String	Name of the payment app. The possible values are: “comercia” “dummy”
printReceipt	Required	boolean	If ”true”, a receipt of the operation will be printed.
callback	Required	InStorePaymentApiCallback Object	To get the response to the operation, the onMerchantResponse interface (response string) must be implemented. See definition of the object InStorePaymentApiCallback.

Details

Executes the operation details.

details (deviceId string, paymentApp string, printReceipt boolean, InStorePaymentApiCallback callback)

Parameters

These are the parameters for details:

Name	Status	Type	Description
deviceID	Only required for In-ECR mode and if not paired with another payment device	String	Token for the payment terminal device. i.e: “8b1bad62eb99732a82b45e”
paymentApp	Required	String	Name of the payment app. The possible values are: “comercia” “dummy”
printReceipt	Required	booleano	If ”true”, a receipt of the operation will be printed.
callback	Required	InStorePaymentApiCallback	To get the response to the operation, the onMerchantResponse interface (response string) must be implemented. See definition of the object InStorePaymentApiCallback.

printOnlineTicketCopy

Recovers information for a specific transaction in order to print a copy of the receipt.

The app that calls has to handle the callback to get the print result.

printOnlineTicketCopy (PrintOnlineTicketCopyRequest printOnlineTicketCopy,

InStorePaymentApiCallback callback)

Parameters

These are the parameters for printOnlineTicketCopy:

Name	Status	Type	Description
printOnlineTicketCopyRequest	Required	PrintOnlineTicketCopyRequest Object	Contains these fields: setDeviceId setPaymentApp setTransactionNumber
setDeviceId	Requerido sólo para el modo de trabajo In-ECR y si no ha sido emparejado con otro dispositivo de pago	String	Token for the payment terminal device. i.e: “8b1bad62eb99732a82b45e”
setPaymentApp	Required	String	Name of the payment app. The possible values are: “comercia” “dummy”
setTransactionNumber	Required	String	Transaction number to define the transaction/receipt you want a copy of.
callback	Required	InStorePaymentApiCallback Object	To get the result of the transaction, the onPrintResult interface (result int) must be implemented. See definition of the object InStorePaymentApiCallback.

preauthNew

Initiates a new pre-authorization transaction with input parameters. This method handles all steps of the transaction, including the user interface and receipt printing. The app that calls has to handle the callback to get the transaction result.

preauthNew (PreauthRequest preauthRequest, InStorePaymentApiCallback callback)

Parameters

These are the parameters for preauthNew:

Name	Status	Type	Description
preauthRequest	Required	PreauthRequest Object	Contains these fields: setDeviceId setPaymentApp setAmount setCurrencyCode setTransactionNumber setOtherData
setDeviceId	Only required for In-ECR mode and if not paired with another payment device	String	Token for the payment terminal device. i.e: “8b1bad62eb99732a82b45e”
setPaymentApp	Required	String	Name of the payment app. The possible values are: “comercia” “dummy”
setAmount	Required	Long	Amount, without decimals (según ISO4217). So 10.00 is 1000 and 00.01 is 1.
setCurrencyCode	Optional	Long	Currency code compatible with ISO4217 in string format. The default value is “EUR”.
setTransactionNumber	Optional	String	Transaction number on the pre-authorization receipt.
setOtherData	Optional	String	JSON String that represents extra information that can be important in some cases to identify a transaction. See the Other JSON data section.
callback	Required	InStorePaymentApiCallback Object	The content returned is the same as in the payment. See definition of the object InStorePaymentApiCallback.

preauthUpdate

Initiates an update of a previous new pre-authorization transaction with input parameters. This method handles all steps of the transaction, including the user interface and receipt printing. The app that calls has to handle the callback to get the transaction result.

preauthUpdate (PreauthRequest preauthRequest, InStorePaymentApiCallback callback)

Parameters

These are the parameters for preauthUpdate:

Name	Status	Type	Description
preauthRequest	Required	PreauthRequest Object	See the preAuthNew table for more information.
callback	Required	InStorePaymentApiCallback Object	The content returned is the same as in the payment. See definition of the object InStorePaymentApiCallback.

preauthConfirm

Initiates confirmation of a previous new pre-authorization transaction with input parameters. This method handles all steps of the transaction, including the user interface and receipt printing. The app that calls has to handle the callback to get the transaction result.

preauthConfirm (PreauthRequest preauthRequest, InStorePaymentApiCallback callback)

Parameters

These are the parameters for preauthConfirm:

Name	Status	Type	Description
preauthRequest	Required	PreauthRequest Object	See the preAuthNew table for more information.
callback	Required	InStorePaymentApiCallback Object	The content returned is the same as in the payment. See definition of the object InStorePaymentApiCallback.

preauthCancellation

Initiates a preauthorization cancel transaction given some input parameters. This method handles all steps of the transaction, including the user interface and receipt printing. The calling application must handle the callback to get the result of the transaction.

preauthCancellation(PreauthRequest preauthRequest, IInSotrePaymenteApiCallback callback)

Parameters

These parameters must be sent to inform the payment application with the preauthorization data to be cancelled and to allow the calling application to retrieve the completed transaction information.

Name	Status	Type	Description
preauthRequest	Required	PreauthRequest	See definition and parameters of the object “PreauthRequest” from the Preauth New section
callback	Required	InStorePaymentApiCallback	Content returned are the same as payment. See InStorePaymentApiCallback object definition.

getPaymentAppConfig

Returns the settings for the payment app.

getPaymentAppConfig (deviceId string, paymentApp string, InStorePaymentApiCallback callback)

Parameters

These are the parameters for getPaymentAppConfig:

Name	Status	Type	Description
deviceId	Only required for In-ECR mode and if not paired with another payment device	String	Token for the payment terminal device. i.e: “8b1bad62eb99732a82b45e”
paymentApp	Required	String	Name of the payment app. The possible values are: “comercia” “dummy”
callback	Required	InStorePaymentApiCallback Object	To get the response to the operation, the onPaymentAppConfigResponse (response string) interface must be implemented. See definition of the object InStorePaymentApiCallback.

setPaymentAppConfig

Sends the payment app the settings it must have.

setPaymentAppConfig (PaymentAppConfig paymentAppConfig)

Parameters

These are the parameters for setPaymentAppConfig:

Name	Status	Type	Description
paymentAppConfig	Required	Objeto PaymentAppConfig	Contains: setDeviceId setPaymentApp setAutoInit isTotalsTransactionsEnabled
setDeviceId	Only required for In-ECR mode and if not paired with another payment device	String	Token for the payment terminal device. i.e: “8b1bad62eb99732a82b45e”
setPaymentApp	Required	String	Name of the payment app. The possible values are: “comercia” “dummy”
setAutoInit	Required	String	If “true”, the payment app will be opened on startup (default operation). “false” if the payment app doesn’t need to open automatically every time it is started (generally because there is a conflict with anther app).
isTotalsTransactionsEnabled	Required	String	If “true”, it is possible to consult totals from the terminals “false” if it is not possible to consult totals from the terminals.

getDeviceConfig

It returns the information of the device configuration as DeviceConfig object. The information retrieved is explained in onDeviceConfigResponse (string response).

getDeviceConfig (String deviceId, InStorePaymentApiCallback callback)

Parameters

These parameters must be sent in order to inform the payment app with the identification of the payment device and to let the calling application retrieve the information of the completed transaction.

Name	Status	Type	Description
deviceId	Required	String	Device token of the payment terminal. i.e: “8b1bad62eb99732a82b45e”
callback	Required	InStorePaymentApiCallback	In order to get the operation response, onDeviceConfigResponse (String response) interface must be implemented. See InStorePaymentApiCallback object definition.

validateApiKey

It validates the apiKey used in the binding process (see How to use the AIDL).

validateApiKey (String apiKey)

Parameters

These parameters must be sent in order to inform the payment device with the apiKey to be validated:

Name	Status	Type	Description
apiKey	Required	String	ApiKey value

It returns a boolean value, if “true“, the apiKey is valid and can be used for binding.

cancelTransaction

It cancels a transaction: the transaction in progress will be cancelled while the card has not been read yet. Calling application must handle callback to get the cancellation result.

cancelTransaction (String deviceId, String paymentApp, ICancelTransactionCallback callback)

Parameters

These parameters must be sent in order to inform the payment app with the identification of the ECR and the payment device and to let the calling application cancel the current transaction.

Name	Status	Type	Description
deviceId	Required	String	Device token of the payment terminal. i.e: “8b1bad62eb99732a82b45e”
paymentApp	Required	String	Name of the payment app. Possible values are: “comercia” “dummy”
callback	Required	ICancelTransactionCallback	In order to get the transaction result, onTransactionCancel (int result) interface must be implemented. See ICancelTransactionCallback object definition

Useful tips

This section has useful tips for the integration.

Create a shortcut on the main page with programming

When you install the Android app from the App Store and open it for the first time, it’s easy to create a shortcut to the app from the main page of your payment terminal. Just follow these steps in your app:

Add permission in the manifest xml

To create the shortcut icon on the main screen, you need to add the permission “com.android.launcher.permission.INSTALL_SHORTCUT” to AndroidManifest.xml:

<uses-permission android:name="com.android.launcher.permission.INSTALL_SHORTCUT" />

2. Create shortcut from MainActivity Class

				
					import android.content.Intent;
import android.content.SharedPreferences;
import android.os.Bundle;
import android.preference.PreferenceManager;
import androidx.appcompat.app.AppCompatActivity;
public class MainActivity extends AppCompatActivity {
    SharedPreferences appPreferences;
    boolean isFirstRun = false;
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        // Get preference value to check the app run first time.
        appPreferences = PreferenceManager.getDefaultSharedPreferences(this);
        isFirstRun = appPreferences.getBoolean("isFirstRun", false);
        if (!isFirstRun) {
            // Create an explict intent it will be used to call Our application by click on the short
            cut
            Intent shortcutIntent = new Intent(getApplicationContext(), MainActivity.class);
            shortcutIntent.setAction(Intent.ACTION_MAIN);
            // Create an implicit intent and assign Shortcut Application Name, Icon
            Intent intent = new Intent();
            intent.putExtra(Intent.EXTRA_SHORTCUT_INTENT, shortcutIntent);
            intent.putExtra(Intent.EXTRA_SHORTCUT_NAME, getString(R.string.app_name));
            // If shortcut name is equal to the applicaion name then use
            //intent.putExtra(Intent.EXTRA_SHORTCUT_NAME, getString(R.string.app_name));
            intent.putExtra(Intent.EXTRA_SHORTCUT_ICON_RESOURCE,
Intent.ShortcutIconResource.fromContext(getApplicationContext(), R.mipmap.ic_launcher_round));
            // Avoid duplicate
            intent.putExtra("duplicate", false);
            intent.setAction("com.android.launcher.action.INSTALL_SHORTCUT");
            getApplicationContext().sendBroadcast(intent);
            // Set preference as true
            SharedPreferences.Editor editor = appPreferences.edit();
            editor.putBoolean("isFirstRun", true);
            editor.commit();
        }
    }
}

Go back to the beginning when you get the result

In the in-terminal mode, when the InStorePaymentApi app returns the result of the transaction, it is best for the app that originally sent the request to take back control of the screen and go back to the beginning so the payment request doesn’t remain on the screen.

To do so, we recommend using the following code:

				
					IInStorePaymentApiCallback.Stub callback = new IInStorePaymentApiCallback.Stub() {
    @Override
    public void onPaymentResult(PaymentResponse result) {
    // Get back to foreground after receiving the result
    ActivityManager tasksManager = (ActivityManager) getSystemService(ACTIVITY_SERVICE);
    tasksManager.moveTaskToFront(getTaskId(), ActivityManager.MOVE_TASK_NO_USER_ACTION);
    // Doing third-party application stuff
    Log.d(TAG, "result: " + result.getResult());
    Log.d(TAG, "status: " + result.getStatus());
}

It is also necessary to include the following permission in the AndroidManifest.xml, since for Android versions
higher than 6.0 it becomes essential:

				
					<uses-permission android:name=" android.permission.SYSTEM_ALERT_WINDOW" />

Generate receipt like payment app

If the external app that uses the InStore Payment API wants to print the receipt, there is a guide below on how to do it, with all the fields required and where to get them, just like the payment app.

Extension of the Android ECR scheme

This section expands the explanation of the cash register scheme with the Android operating system, looking at the communication flows between components, in addition to the different timeouts that are handled, possible errors that the integrator must take into account, etc.

The solution that operates on Android devices paired with Comercia payment terminals is what makes it easy for integrators who have developed a cash register solution to easily execute payments at the POS.

All that is needed is that both the Android device and the payment terminal have access to the Internet, and that both devices are paired with each other.

The architectural scheme that this solution follows is the following:

This solution is made up of the following elements:

InStorePaymentApi: is an application installed both on the cash register (Android ECR) and on the payment terminal (Android). The one installed on the ECR implements an AIDL service to listen calls from the integrator application, meanwhile the installed one on the payment device is constantly listening to PUSH or WEBSOCKETS type requests, originating from the InStorePaymentApi’s ECR.
AzureCloud Connector: is the Azure cloud in charge of managing the database that records all transactions carried out in the payment terminal, as well as allowing the connection between ECR and terminals.
Pushy.me Server: it is a cloud service that allows the connection between ECR and terminals.

The connection and communication between ECR and terminals can be carried out through PUSH type notifications or through WEBSOCKETS through an Azure service called SignalR:

Pushy: is a cross-platform solution based on the MQTT protocol to be able to send push notifications using unique and auto-generated identifiers for each device, thus avoiding problems such as dynamic IPs.
SignalR: is a system of calls between devices and an Azure server made through websockets that allow any task that said server is capable of executing. In this way, communication channels can be established between different devices using identifiers, as well as registering the use of the API using a database.

Apart from the normal flow that transactions follow (red arrows), there is another use of the AzureCloud Connector which is to record all operations carried out on payment terminals (orange arrows). To do this, both the ECR connector and the InStorePaymentApi are automatically registered in said cloud, and it is the InStorePaymentApi that updates the database that is managed by the AzureCloud Connector at the end of each transaction.

The connections established by the terminal to the Pushy.me and Azure servers are made every time the terminal is turned on, and are maintained indefinitely as long as there are no connection interruptions or any other errors. In the event that the terminal detects the closure of any of these connections, it will force registration again: this can occur, for example, when the terminal changes router when connected to a WiFi network, or when it changes mobile operator while roaming.

Basic transaction flow

A standard transaction, for example a sale, will be initiated in the integrator application. Through the AIDL service of the InStorePaymentApi’s ECR, the type of transaction being requested will be informed, including the amount.

Next, the ECR will send the request to the payment terminal through the communication channel activated at that moment: Pushy or SignalR.

Once the request is received in the payment terminal, the InStorePaymentApi application will launch the transaction in the Comercia C2.0 payment application through an AIDL connection. The payment application is identified as “My POS”, and is responsible for executing the entire payment process:

Card reading: in case of a reading error, it also makes retries until a correct one is obtained or the attempts are exhausted and the transaction is canceled.
PIN request, if necessary.
Communication with the Comercia authorizing service: in the event of connection failures, it automatically carries out the pertinent cancellations, informing the Windows cash register of the result.
Shows the final result (transaction accepted or rejected) on the screen so that the client can check it.

When the financial transaction has been completed in My POS, a response is prepared that travels back to the integrator’s application, using the same communication channel that was used in the original request.

This would be the flow of a standard transaction without failures:

Operation of the ECR

The AIDL service that implements the ECR on devices with an Android operating system is constantly listening whenever it is running.

When it receives a request to carry out a transaction from the integrator application, the ECR transfers the request to the payment terminal and waits for a response with the final result of the transaction. It is at the moment of receiving said response that it informs the integrator application through callbacks.

While the ECR is waiting for the response from the payment terminal, it internally establishes maximum waiting times to mitigate waits in case of failures such as the network having gone down or the payment terminal having been turned off unexpectedly. Errors of this type would cause the ECR to wait indefinitely for a response, so the integrator application would never know if the transaction has been accepted or denied, with the consequent damages.

The process that the ECR follows to avoid this situation is to ask the POS every 10 seconds if the payment process is still in progress. In the event that the transaction is still in process, and the payment terminal is still connected to the Internet, it will return to the ECR a response that everything is still correct, but there is still no final result. Keep in mind that a standard transaction can take about 30-40 seconds, and even more than 1 minute if the card PIN is required to be entered.

If the ECR does not receive a response in this situation, 2 more attempts will be made to know the status of the payment terminal. If no response is received from the payment terminal on the third attempt (this is 30 seconds after starting the transaction), the ECR will terminate the connection and return to the integrator application that the transaction has ended with a timeout error.

The following flow explains retries in case the payment terminal has been disconnected from the Internet:

InStore Payment API Android

Introduction

Files provided

Work mode

Pairing process

How to use the AIDL

Definition of AIDL API payment

Object InStorePaymentApiCallback

Object PaymentResponse

JSON Additional data

onPrintResult (int result)

onMerchantResponse (string response)

onPaymentAppConfigResponse (string response)

onDeviceConfigResponse (string response)

Object ICancelTransactionCallback

Payment

Parameters

Other JSON info

Refunds

Parameters

getTransaction

Parameters

printLastReceiptCopy

Parameters

getVersion

Return

printHTML

Parameters

readCard

Parameters

stopReadCard

Parameters

endOfDay

Parameters

Totals

Parameters

Details

Parameters

printOnlineTicketCopy

Parameters

preauthNew

Parameters

preauthUpdate

Parameters

preauthConfirm

Parameters

preauthCancellation

Parameters

getPaymentAppConfig

Parameters

setPaymentAppConfig

Parameters

getDeviceConfig

Parameters

validateApiKey

Parameters

cancelTransaction

Parameters

Useful tips

Create a shortcut on the main page with programming

Go back to the beginning when you get the result

Generate receipt like payment app

Extension of the Android ECR scheme

Basic transaction flow

Operation of the ECR

Products

Sales

Technical Support

Partners

SmartWiki, Powered by AI

Consulta la documentación de las distintas secciones de integraciones:

Addon Payments

Cyberpac

POS integrated Payments

Addon Payments

Consult the documentation of the different integrations sections:​

Consult the documentation of the different integrations sections: