InStore Payment API Android

  • Versión: 4.08.04

Introducción

InStore Payment API es un producto para realizar pagos con una API única para la aplicación de pagos de Comercia. Su modo de funcionamiento es sencillo, envías un pago y recibes respuesta. 

Esta guía describe una implementación de cliente Android de un AIDL que garantiza un IPC seguro.

Las ventajas de InStore Payment API frente a una solución intent-based serían el hecho de que no necesitamos modificar las aplicaciones y podemos obtener una interacción en tiempo real basada en devolución de llamada sin depender de motores de intent-filtering demasiado complejos para tener una pretensión de una conexión tipo enchufe. Otra ventaja de utilizar un servicio AIDL frente a intent, socket o mecanismos similares es el hecho de que Android certifica que el IPC de un servicio AIDL es seguro.

A continuación, se explicará en qué consiste cada parte del servicio por el lado de la solución del cliente y cómo se puede utilizar, con ejemplos útiles.
Este servicio se puede implementar en cualquier dispositivo que cumpla con los siguientes requisitos previos:

  1. Es un terminal de pago Android InStore (modo in-terminal) o es un dispositivo Android (modo in-android-ecr).
  2. El terminal está equipado con la aplicación de pago Comercia (certificada y debidamente instalada).

NOTA (1): El servicio instalado en un terminal de pago Android también permite recibir solicitudes de dispositivos con el sistema operativo Windows (modo in-windows-ecr). Para obtener más información sobre cómo integrar esta solución en un dispositivo Windows, consulta la guía InStore Payment API Windows.

NOTA (2): Para facilitar las tareas de integración, el servicio InStore Payment Api instalado en la plataforma o terminal de pago, permite simular una aplicación de pago ficticia para no depender de una aplicación de pago real y no necesitar tarjetas físicas para probar el flujo completo.
Esta aplicación ficticia es simplemente un conjunto de pantallas que muestra directamente la aplicación InStore Payment Api, por lo que no se requeriría una solicitud adicional. Por tanto, aunque por defecto siempre se utilizará la aplicación de pago Comercia, también es posible utilizar la aplicación «ficticia».
Esta selección de aplicaciones se puede ver en detalle en cada funcionalidad de la sección Definición de Pago ADI AIDL.

Archivos proporcionados

En el Welcome pack recibirás el archivo instore-payment-api-android-XX.XX.XX-debug.zip con el siguiente contenido:

  • instorepaymentapilib-XX.XX.XX.aar: Biblioteca que la aplicación de integración debe usar para poder utilizar diferentes funcionalidades de la InStore Payment Api.
  • instorepaymentapi-XX.XX.XX-debug.apk: InStore Payment Api, que recibirá las solicitudes desde la aplicación integradora.

También encontrarás la carpeta «PaymentApp» con el siguiente contenido:

  • cgp-XX.XX.XX-pre.apk: Aplicación de pago que leerá la tarjeta y se comunicará con los servidores de Comercia. Se distribuye la versión que apunta al entorno de preproducción.

Otras aplicaciones necesarias para el correcto funcionamiento del ecosistema, tal como el HAL, que depende del modelo de terminal utilizado, deberá venir preinstalado o se cargará de forma remota.

Aparte de todos los elementos necesarios para poder desarrollar una solución, la carpeta «InStorePaymentApiDemo» también se distribuye con un proyecto de ejemplo donde se utiliza InStore Payment Api de forma sencilla.

Modo de trabajo

Esta API podría usarse en dos entornos diferentes:

  1. In-Terminal: Software ECR y aplicación de pago dentro del mismo terminal, por ejemplo DX8000.
  2. In-ECR: Software ECR en un dispositivo diferente a la aplicación de pago, por ejemplo, software ECR dentro de un AECR C5, C9 o Raspberry Pi y aplicación de pago dentro del dispositivo de pago.
    • La conexión con la aplicación de pago se gestiona mediante instorepaymentapi-XX.XX.XX-debug.apk a través de WiFi/4G.
    • Necesitas el deviceId del dispositivo ECR que enviará la solicitud al dispositivo de pago.
    • Se debe realizar el proceso de emparejamiento con el dispositivo de pago. Consulta la sección Proceso de emparejamiento de esta guía.

Proceso de emparejamiento

Si estás trabajando en el modo In-ECR, se pueden emparejar el dispositivo de pago y la ECR. Hay dos procesos de emparejamiento:

1. En la ECR, abre la aplicación «InStorePaymentApi», verás:

2. En el dispositivo de pago, abre la aplicación «InStorePaymentApi», haz click en el botón «QR» y captura el código QR de ECR.
Tras unos segundos el proceso de emparejamiento habrá sido exitoso:

3. En la ECR, verás:

1. Si hubiera un problema con la cámara que impida leer el código QR, puedes introducir manualmente el ID de ECR en el dispositivo de pago y dar al botón para emparejarlo manualmente:

Cómo usar el AIDL

NOTA: Como acción previa, si alguna versión del Ingenico Payment Service estuviera instalada en el terminal (un proyecto anterior a InStore Payment Api), ésta se debe desinstalar de antemano para garantizar que no haya ningún conflicto con la nueva versión que se va a instalar.

1. Solo para el modo de trabajo In-Android-ECR, instala “instorepaymentapi-XX.XX.XX-debug.apk” en la caja registradora.

2. Instala “instorepaymentapi-XX.XX.XX-debug.apk” en el dispositivo de pago.

NOTA: La instalación de aplicaciones dependerá del fabricante de cada terminal, ya que cada hardware puede tener diferentes formas de hacerlo. 

3. Crea o abre tu proyecto Android Studio.

NOTA: Como se menciona en la sección anterior, dentro del ZIP compartido hay una carpeta «InStorePaymentApiDemo» con un proyecto de ejemplo donde se utiliza InStorePayment de forma sencilla.

4. Añade permisos en el AndroidManifest.xml:

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

NOTA: A partir de la versión 11 de Android es necesario indicar en el Manifest qué servicios van a ser vinculados expresamente, por lo que se debe añadir lo siguiente:

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

5. Solicita una apiKey a Comercia en este correo.

6. Copia “instorepaymentapilib-XX.XX.XX.aar” proporcionado a tu <YourProject>\libs.

7. Asegúrate de incluir ‘*.aar’ en las dependencias del módulo de la aplicación:

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

8. Categoriza ServiceConnection en tu Actividad:

				
					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. Vincula el servicio en el método 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. ¡Eso es todo! Ahora puedes realizar pagos usando el método “payment”:

				
					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. Y manejar la respuesta de la transacción administrando el objeto devuelto «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. Importante: Recuerda desvincular la InStore Payment API cuando destruyas la actividad:

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

Definición de pago AIDL API

En esta sección puedes encontrar la definición del método y descripción de los parámetros.

Objeto InStorePaymentApiCallback

Se deben implementar los siguientes métodos:

Objeto PaymentResponse

Estos son los parámetros del objeto PaymentResponse: 

NombreTipoDescripción
getDeviceIdStringToken de dispositivo del terminal de pago.
getTransactionTypeStringTipo de transacción de devolución. Los valores posibles son:

«SALE»
«REFUND»
«READCARD»
«PREAUTHNEW»
«PREAUTHUPDATE»
«PREAUTHCONFIRM»
getAmountLongDevuelve el importe del pago.
getCurrencyCodeStringDevuelve el código de moneda de la transacción (código de moneda compatible con ISO4217 en formato string).
getTransactionNumberStringNúmero de transacción que aparece en el recibo. Este número debería ser utilizado en reembolsos, actualizaciones y confirmaciones de autorización previa, e imprimir copia del recibo.
getResultintDevuelve el resultado de la transacción. Los valores posibles son:

TRANSACTION_RESULT_UNKNOWN = 0;
TRANSACTION_ACCEPTED = 100;
TRANSACTION_NOT_ACCEPTED = 101;
getStatusintDevuelve el código extendido del resultado. Los valores posibles son:

// Código de estado predeterminado
TRANSACTION_STATUS_UNKNOWN = -1;

// Códigos de estado extendidos aceptados
TRANSACTION_ACCEPTED_ONLINE = -1001;
TRANSACTION_ACCEPTED_OFFLINE = -1002;
CARD_READ = -1003;

// Códigos de estado extendidos denegados
TRANSACTION_DENIED_ONLINE = -1010;
TRANSACTION_DENIED_OFFLINE = -1011;

// Códigos de estado extendidos cancelados
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;

// Códigos de estado extendidos de 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;
getPaymentAppStringDevuelve la aplicación de pago que realizó la transacción.
getAdditionalDataStringDevuelve datos adicionales en formato de JSON String. Comprueba el JSON de datos adicionales.
JSON Datos adicionales

Dependiendo de la versión de la aplicación de pago, se podrían recibir algunos datos adicionales. Esta información es OPCIONAL y se representa en una JSON string de la siguiente manera:

Todos los campos a continuación son opcionales:

				
					"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 (resultado int)

Los valores posibles son:

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

onMerchantResponse (Respuesta String)

La respuesta devuelta para «endOfDay» y «totals» se representa en un JSON string de la siguiente manera:

				
					"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"
}

La respuesta devuelta para «detalles» se representa en un JSON string de la siguiente manera:

				
					"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"
}

Si no se pudiera realizar la operación del comerciante, se devolverá el código de error correspondiente:

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

Algunos de estos errores pueden ser:

501 = No procesado: los datos de conciliación no coinciden
601 = No procesado, Totales no disponibles
602 = No procesado, Detalle no disponible
603 = No procesado, Recibo no encontrado
604 = No procesado, ParamsSync no disponible
605 = No procesado, Donación no disponible

onPaymentAppConfigResponse (Respuesta String)

La respuesta devuelta para «getPaymentAppConfig» se representa en un JSON string de la siguiente manera:

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

onDeviceConfigResponse (Respuesta String)

Este método informa que la solicitud «getDeviceConfig» se ha completado (con éxito o no) y recupera la información de la app de pago. La respuesta devuelta para «getDeviceConfig» se representa en un JSON string de la siguiente manera:

				
					"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" 
}

Objeto ICancelTransactionCallback

Este objeto contiene un método que permite que InStorePaymentApi y el dispositivo de pago se comuniquen para informar de que la transacción cancelada se ha completado (con éxito o no).

onTransactionCancel(int result): para obtener el resultado de la cancelación. Se utiliza para informar de que la cancelación de la transacción se ha completado o de que se ha producido un error al intentarlo. Los valores posibles son:

				
					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

Pago

Inicia una transacción de pago dados algunos parámetros de entrada. Este método gestiona todos los pasos de la transacción, incluyendo interfaz de usuario e impresión de recibos. La aplicación que llama debe manejar la devolución de llamada para obtener el resultado de la transacción.

payment (PaymentRequest paymentRequest, InStorePaymentApiCallback callback)

Parámetros

Estos son los parámetros para los pagos:

NombreEstadoTipoDescripción
paymentRequest
RequeridoObjeto
PaymentRequest		Los parámetros son los siguientes:
setDeviceId
setPaymentApp
setAmount
setCurrencyCode
setOtherData
setDeviceId

Requerido sólo para el modo de trabajo In-ECR y si no ha sido emparejado con otro dispositivo de pagoStringToken de dispositivo del terminal de pago.

i.e: «8b1bad62eb99732a82b45e»
setPaymentApp

RequeridoStringNombre de la aplicación de pago. Los valores posibles son:

“comercia”
«dummy»
setAmount

RequeridoLongImporte, expresado sin decimales (según ISO4217).

Por lo tanto 10,00€ se escribirían como 1000 y 00,01€ se enviaría como 1.
setCurrencyCodeOpcionalStringCódigo de moneda compatible con ISO4217 en formato string.

El valor predeterminado es “EUR”.
setOtherDataOpcionalStringJSON String que representa información extra que en
algunos casos pueden ser importantes para identificar una transacción.

Consulte la sección Otros datos del JSON.
callback
RequeridoObjeto
InStorePaymentApiCallback		Ver definición de objeto InStorePaymentApiCallback.

Otros datos del JSON

				
					"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
}

Devoluciones (refund)

Inicia una transacción de devolución con algunos parámetros de entrada. Este método gestiona todos los pasos de la transacción, incluyendo interfaz de usuario e impresión de recibos. La aplicación que llama debe manejar la devolución de llamada para obtener el resultado de la transacción.

Parámetros

Estos son los parámetros de las devoluciones: 

NombreEstadoTipoDescripción
refundRequest
RequeridoObjeto
refundRequest		Los parámetros son los siguientes:
setDeviceId
setPaymentApp
setAmount
setCurrencyCode
setTransactionNumber
setOtherData
setDeviceId

Requerido sólo para el modo de trabajo In-ECR y si no ha sido emparejado con otro dispositivo de pagoStringToken de dispositivo del terminal de pago.

i.e: «8b1bad62eb99732a82b45e»
setPaymentApp

RequeridoStringNombre de la aplicación de pago. Los valores posibles son:

“comercia”
«dummy»
setAmount

RequeridoLongImporte, expresado sin decimales (según ISO4217).

Por lo tanto 10,00€ se escribirían como 1000 y 00,01€ se enviaría como 1.
setCurrencyCodeOpcionalStringCódigo de moneda compatible con ISO4217 en formato string.

El valor predeterminado es “EUR”.
setTransactionNumber
RequeridoStringNúmero de transacción que aparece en el recibo de autorización previa.
setOtherDataOpcionalStringJSON String que representa información extra que en
algunos casos pueden ser importantes para identificar una transacción.

Consulte la sección Otros datos del JSON.
callback
RequeridoObjeto
InStorePaymentApiCallback		El contenido devuelto es el mismo que el del pago. Ver definición de objeto InStorePaymentApiCallback.

getTransaction

Obtiene toda la información de una transacción.

getTransaction (TransactionRequest transactionRequest, InStorePaymentApiCallback callback)

Parámetros

Estos son los parámetros para getTransaction: 

NombreEstadoTipoDescripción
transactionRequest
RequeridoObjeto
transactionRequest		Los parámetros son los siguientes:
setDeviceId
setTransactionId
setDeviceId

Requerido sólo para el modo de trabajo In-ECR y si no ha sido emparejado con otro dispositivo de pagoStringToken de dispositivo del terminal de pago.

i.e: «8b1bad62eb99732a82b45e»
setTransactionId

RequeridoStringID de transacción recibida en pago/reembolso en onPaymentReceived callback
callback
RequeridoObjeto
InStorePaymentApiCallback		El contenido devuelto es el mismo que en el pago. Ver definición de objeto InStorePaymentApiCallback.

printLastReceiptCopy

Imprime una copia del último recibo de pago. La aplicación que llama debe manejar la devolución de llamada para obtener el resultado de impresión.

printLastReceiptCopy (String deviceId, String paymentApp, InStorePaymentApiCallback callback)

Parámetros

Estos son los parámetros para printLastReceiptCopy: 

NombreEstadoTipoDescripción
deviceIdRequerido sólo para el modo de trabajo In-ECR y si no ha sido emparejado con otro dispositivo de pagoStringToken de dispositivo del terminal de pago.

i.e: «8b1bad62eb99732a82b45e»
paymentApp

RequeridoStringNombre de la aplicación de pago. Los valores posibles son:

“comercia”
«dummy»
callback
RequeridoObjeto
InStorePaymentApiCallback		Para obtener el resultado de la transacción, onPrintResult (int result) debe tener implementada un interfaz.
Ver definición de objeto InStorePaymentApiCallback.

getVersion

Obtiene la versión de la API AIDL.


getVersion()

Devuelve

TipoDescripción
String“04.00.00”

printHTML

Imprime una cadena HTML. La aplicación que llama debe manejar la devolución de llamada para obtener el resultado de impresión.

Esta funcionalidad solo se admite en el modo de funcionamiento del terminal (no se admite con cajas registradoras ECR).

printHTML (String deviceId, String htmlString, InStorePaymentApiCallback callback)

Parámetros

Estos son los parámetros para printHTML:

NombreEstadoTipoDescripción
deviceIdRequerido sólo para el modo de trabajo In-ECR y si no ha sido emparejado con otro dispositivo de pagoStringToken de dispositivo del terminal de pago.

i.e: «8b1bad62eb99732a82b45e»
htmlString
RequeridoStringString en formato HTML a imprimir.
callback
RequeridoObjeto
InStorePaymentApiCallback		Para obtener el resultado de la transacción, onPrintResult (int result) debe tener implementada un interfaz.
Ver definición de objeto InStorePaymentApiCallback.

readCard

Lee únicamente tarjetas magnéticas no financieras. Solo se leerán las pistas 1 y 2 (devueltas por AdditionalData).

readCard (String deviceId, Boolean showIndications, int timeout, InStorePaymentApiCallback callback)

Parámetros

Estos son los parámetros para readCard:

NombreEstadoTipoDescripción
deviceIdRequerido sólo para el modo de trabajo In-ECR y si no ha sido emparejado con otro dispositivo de pagoStringToken de dispositivo del terminal de pago.

i.e: «8b1bad62eb99732a82b45e»
showIndications
RequeridoBooleanoSi es »true», la InStorePaymentApi mostrará mensajes en la pantalla para indicar al usuario que pase la tarjeta magnética por el lector
timeout
RequeridointTiempo de espera máximo para la lectura de la tarjeta antes de mostrar error. Está limitado a 60 segundos.
callback
RequeridoObjeto
InStorePaymentApiCallback		El contenido se devuelve igual que en el pago.
Ver definición de objeto InStorePaymentApiCallback.

stopReadCard

Anula la lectura actual de tarjetas no financieras.

stopReadCard (String deviceId)

Parámetros

NombreEstadoTipoDescripción
deviceIdRequerido sólo para el modo de trabajo In-ECR y si no ha sido emparejado con otro dispositivo de pagoStringToken de dispositivo del terminal de pago.

i.e: «8b1bad62eb99732a82b45e»

endOfDay

Se ejecuta una liquidación del día.

endOfDay (String deviceId, String paymentApp, Boolean printReceipt, InStorePaymentApiCallback callback)

Parámetros

Estos son los parámetros para endOfDay:

NombreEstadoTipoDescripción
deviceIdRequerido sólo para el modo de trabajo In-ECR y si no ha sido emparejado con otro dispositivo de pagoStringToken de dispositivo del terminal de pago.

i.e: «8b1bad62eb99732a82b45e»
paymentApp
RequeridoStringNombre de la aplicación de pago. Los valores posibles son:

“comercia”
«dummy»
printReceipt
RequeridobooleanoSi es »true», se imprimirá un recibo de la operación.
callbackRequeridoObjeto
InStorePaymentApiCallback		Para obtener la respuesta de la operación, la interfaz onMerchantResponse (respuesta String) debe estar implementada.

Ver definición del objeto InStorePaymentApiCallback.

Totales (totals)

Realiza una totalización.

totals (String deviceId, String paymentApp, Boolean printReceipt, InStorePaymentApiCallback callback)

Parámetros

NombreEstadoTipoDescripción
deviceIdRequerido sólo para el modo de trabajo In-ECR y si no ha sido emparejado con otro dispositivo de pagoStringToken de dispositivo del terminal de pago.

i.e: «8b1bad62eb99732a82b45e»
paymentApp
RequeridoStringNombre de la aplicación de pago. Los valores posibles son:

“comercia”
«dummy»
printReceipt
RequeridobooleanoSi es »true», se imprimirá un recibo de la operación.
callbackRequerido
Objeto
InStorePaymentApiCallback		Para obtener la respuesta de la operación, la interfaz onMerchantResponse (respuesta String) debe estar implementada.

Ver definición del objeto InStorePaymentApiCallback.

Detalles (details)

Ejecuta detalles de operaciones.

details (String deviceId, String paymentApp, Boolean printReceipt, InStorePaymentApiCallback callback)

Parámetros

Estos son los parámetros para details:

NombreEstadoTipoDescripción
deviceIdRequerido sólo para el modo de trabajo In-ECR y si no ha sido emparejado con otro dispositivo de pagoStringToken de dispositivo del terminal de pago.

i.e: «8b1bad62eb99732a82b45e»
paymentApp
RequeridoStringNombre de la aplicación de pago. Los valores posibles son:

“comercia”
«dummy»
printReceipt
RequeridobooleanoSi es »true», se imprimirá un recibo de la operación.
callbackRequeridoInStorePaymentApiCallbackPara obtener la respuesta de la operación, la interfaz onMerchantResponse (respuesta String) debe estar implementada.

Ver definición del objeto InStorePaymentApiCallback.

printOnlineTicketCopy

Recupera información de una transacción determinada con el fin de volver a imprimir el recibo de la transacción.

La aplicación de llamada debe manejar la devolución de llamada para obtener el resultado de impresión.

printOnlineTicketCopy (PrintOnlineTicketCopyRequest printOnlineTicketCopy,
InStorePaymentApiCallback callback)

Parámetros

Estos son los parámetros para printOnlineTicketCopy:

NombreEstadoTipoDescripción
printOnlineTicketCopyRequest

RequeridoObjeto
PrintOnlineTicketCopyRequest		Contiene estos campos:
setDeviceId
setPaymentApp
setTransactionNumber
setDeviceId

Requerido sólo para el modo de trabajo In-ECR y si no ha sido emparejado con otro dispositivo de pagoStringToken de dispositivo del terminal de pago.

i.e: “8b1bad62eb99732a82b45e»
setPaymentApp

RequeridoStringNombre de la aplicación de pago. Los valores posibles son:

“comercia”
«dummy»
setTransactionNumber

RequeridoStringNúmero de transacción para definir la transacción/recibo del que desea obtener una copia.
callbackRequeridoObjeto
InStorePaymentApiCallback		Para obtener el resultado de la transacción, la interfaz onPrintResult (resultado int) debe ser implementada.

Ver definición del objeto InStorePaymentApiCallback.

preauthNew

Inicia una nueva transacción de autorización previa dados algunos parámetros de entrada. Este método gestiona todos pasos de la transacción, incluida la interfaz de usuario y la impresión de recibos. La aplicación que llama debe manejar la devolución de llamada para obtener el resultado de la transacción.

preauthNew (PreauthRequest preauthRequest, InStorePaymentApiCallback callback)

Parámetros

Estos son los parámetros para preauthNew:

NombreEstadoTipoDescripción
preauthRequest
RequeridoObjeto
PreauthRequest		Contiene estos campos:
setDeviceId
setPaymentApp
setAmount
setCurrencyCode
setTransactionNumber
setOtherData
setDeviceId

Requerido sólo para el modo de trabajo In-ECR y si no ha sido emparejado con otro dispositivo de pagoStringToken de dispositivo del terminal de pago.

i.e: “8b1bad62eb99732a82b45e»
setPaymentApp

RequeridoStringNombre de la aplicación de pago. Los valores posibles son:

“comercia”
«dummy»
setAmount

RequeridoLongImporte, expresado sin decimales (según ISO4217).

Por lo tanto 10,00€ se escribirían como 1000 y 00,01€ se enviaría como 1.
setCurrencyCodeOpcionalLongCódigo de moneda compatible con ISO4217 en formato string.

El valor predeterminado es “EUR”.
setTransactionNumberOpcionalStringNúmero de transacción que aparece en el recibo de autorización previa.
setOtherDataOpcionalStringJSON string que representa información extra que en algunos casos puede ser importante identificar una transacción.

Consulta la sección Otros datos JSON.
callbackRequeridoObjeto
InStorePaymentApiCallback		El contenido devuelto es el mismo que en el de pago.

Ver definición del objeto InStorePaymentApiCallback.

preauthUpdate

Inicia una transacción de actualización de autorización previa dados algunos parámetros de entrada. Este método gestiona todos los pasos de la transacción, incluida la interfaz de usuario y la impresión de recibos. La aplicación que llama debe manejar la devolución de llamada para obtener el resultado de la transacción.

preauthUpdate (PreauthRequest preauthRequest, InStorePaymentApiCallback callback)

Parámetros

Estos son los parámetros para preauthUpdate:

NombreEstadoTipoDescripción
preauthRequest
RequeridoObjeto
PreauthRequest		Consulta la tabla de preAuthNew para más detalles.
callbackRequeridoObjeto
InStorePaymentApiCallback		El contenido devuelto es el mismo que en el de pago.

Ver definición del objeto InStorePaymentApiCallback.

preauthConfirm

Inicia una transacción de confirmación de autorización previa dados algunos parámetros de entrada. Este método gestiona todos los pasos de la transacción, incluida la interfaz de usuario y la impresión de recibos. La aplicación que llama debe manejar la devolución de llamada para obtener el resultado de la transacción.

preauthConfirm (PreauthRequest preauthRequest, InStorePaymentApiCallback callback)

Parámetros

Estos son los parámetros para preauthConfirm:

NombreEstadoTipoDescripción
preauthRequest
RequeridoObjeto
PreauthRequest		Consulta la tabla de preAuthNew para más detalles.
callbackRequeridoObjeto
InStorePaymentApiCallback		El contenido devuelto es el mismo que en el de pago.

Ver definición del objeto InStorePaymentApiCallback.

preauthCancellation

Inicia una transacción de cancelación de pre-autorización dados algunos parámetros de entrada. Este método gestiona todos los pasos de la transacción, incluida la interfaz de usuario y la impresión del recibo. La aplicación que llama debe gestionar la devolución de llamada para obtener el resultado de la transacción.

preauthCancellation(PreauthRequest preauthRequest, IInSotrePaymenteApiCallback callback)

Parámetros

Estos son los parámetros a enviar para informar de la pre-autorización a cancelar:

NombreEstadoTipoDescripción
preauthRequestRequeridoPreauthRequestVer la definición y parámetros del objeto «PreauthRequest» de la sección preAuth New
callback
RequeridoInStorePaymentApiCallbackEl contenido que se devuelve es el mismo que en el pago.
Ver definición de objeto InStorePaymentApiCallback.

getPaymentAppConfig

Devuelve la configuración de la aplicación de pago.

getPaymentAppConfig  (String deviceId, String paymentApp, InStorePaymentApiCallback callback)

Parámetros

Estos son los parámetros para getPaymentAppConfig:

NombreEstadoTipoDescripción
deviceId

Requerido sólo para el modo de trabajo In-ECR y si no ha sido emparejado con otro dispositivo de pagoStringToken de dispositivo del terminal de pago.

i.e: “8b1bad62eb99732a82b45e»
paymentApp

RequeridoStringNombre de la aplicación de pago. Los valores posibles son:

“comercia”
«dummy»
callback

RequeridoObjeto
InStorePaymentApiCallback		Para obtener la respuesta de la operación, la interfaz onPaymentAppConfigResponse (respuesta String) debe estar implementada.
Ver definición del objeto InStorePaymentApiCallback.

setPaymentAppConfig

Envía a la aplicación de pago la configuración que debería tener.

setPaymentAppConfig (PaymentAppConfig paymentAppConfig)

Parámetros

Estos son los parámetros para setPaymentAppConfig:

NombreEstadoTipoDescripción
paymentAppConfig

RequeridoObjeto
PaymentAppConfig		Contiene:
setDeviceId
setPaymentApp
setAutoInit
isTotalsTransactionsEnabled
setDeviceId

Requerido sólo para el modo de trabajo In-ECR y si no ha sido emparejado con otro dispositivo de pagoStringToken de dispositivo del terminal de pago.

i.e: “8b1bad62eb99732a82b45e»
setPaymentApp
RequeridoStringNombre de la aplicación de pago. Los valores posibles son:

“comercia”
«dummy»
setAutoInit
RequeridoStringSi es «true», la aplicación de pago se iniciará en el momento del lanzamiento (operación predeterminada).
«false» si no es necesario que la aplicación de pago se inicie automáticamente
en cada arranque (generalmente porque entra en conflicto con otra
aplicación).
isTotalsTransactionsEnabledRequeridoStringSi es «true», es posible consultar los totales desde los terminales. Si es «false», no es posible.

getDeviceConfig

Devuelve la información de la configuración del dispositivo como objeto DeviceConfig. La respuesta se explica en el punto onDeviceConfigResponse (Respuesta String). 

getDeviceConfig (String deviceId, InStorePaymentApiCallback callback)

Parámetros

Estos son los parámetros para getDeviceConfig

NombreEstadoTipoDescripción
deviceId
RequeridoStringToken de dispositivo del terminal de pago.

i.e: «8b1bad62eb99732a82b45e»
callback
RequeridoInStorePaymentApiCallbackPara obtener la respuesta de la operación, onDeviceConfigResponse (respuesta string) se debe implementar como interfaz.
Ver definición de objeto InStorePaymentApiCallback.

validateApiKey

Valida la apiKey en el proceso de emparejamiento. Ver en cómo usar el AIDL.

validateApiKey (String apiKey)

Parámetros

Estos son los parámetros a enviar para informar al dispositivo de pago de la apiKey a validar:

NombreEstadoTipoDescripción
apiKeyRequeridoStringValor de la apiKey

Devuelve un valor Booleano, si es «true«, la apiKey es válida y se puede usar para emparejar. 

cancelTransaction

Cancela una transacción: la transacción en curso se cancelará siempre que la tarjeta no se haya leído aún. La aplicación que llama debe manejar el callback para obtener el resultado de la cancelación.

cancelTransaction (String deviceId, String paymentApp, ICancelTransactionCallback callback)

Parámetros

Estos son los parámetros a enviar para cancelar una transacción

NombreEstadoTipoDescripción
deviceIdRequeridoStringToken de dispositivo del terminal de pago.

i.e: «8b1bad62eb99732a82b45e»
paymentApp
RequeridoStringNombre de la aplicación de pago. Los valores posibles son:

“comercia”
«dummy»
callback
RequeridoICancelTransactionCallbackPara obtener el resultado de la operación, onTransactionCancel (int Result) se debe implementar como interfaz.
Ver definición de objeto ICancelTransactionCallback

Recomendaciones útiles

En esta sección encontrarás recomendaciones útiles para la integración.

Crear acceso directo en la pantalla de inicio mediante programación

Cuando instalas tu aplicación de Android desde App Store y la ejecutas por primera vez, es muy útil crear un acceso directo de tu aplicación en la pantalla de inicio de nuestro terminal de pago. Sigue los siguientes pasos en tu aplicación para hacerlo posible:

  1. Agregar permiso en el manifest xml

Para crear el icono de acceso directo en la pantalla de inicio, necesitas agregar el permiso
“com.android.launcher.permission.INSTALL_SHORTCUT” en AndroidManifest.xml:

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

2. Crear acceso directo en 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();
        }
    }
}

Volver al inicio cuando se obtiene el resultado

En el modo in-terminal, cuando la aplicación InStorePaymentApi devuelve el resultado de la transacción, es conveniente que la aplicación que lanzó originalmente la solicitud recupere el control de la pantalla y vuelva al inicio para evitar que la solicitud de pago quede mostrada de forma residual.

Para ello recomendamos utilizar el siguiente código:

				
					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());
}

Además, es necesario incluir el siguiente permiso en el AndroidManifest.xml, especialmente en versiones Android superiores a la 6.0, que es esencial:

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

Generar ticket como lo hace la aplicación de pago

En el caso de que la aplicación externa que utiliza InStore Payment Api quiera imprimir el ticket, se proporciona una guía a continuación para poder hacerlo, indicando todos los campos necesarios y dónde obtenerlos, haciéndolo como lo hace la aplicación de pago.

Esquema Android ECR

En este apartado se amplía la explicación del esquema de caja registradora con sistema operativo Android, viendo los flujos de comunicación entre componentes, además de los diferentes tiempos de espera que se manejan, posibles errores que el integrador debe tener en cuenta, etc.

La solución que opera sobre dispositivos Android emparejados con terminales de pago Comercia es la que facilita a los integradores que han desarrollado una solución de caja registradora la ejecución de pagos en el TPV de forma sencilla.

Lo único que se necesita es que tanto el dispositivo Android como el terminal de pago tengan acceso a Internet, y que ambos dispositivos estén emparejados entre sí.

El esquema arquitectónico que sigue esta solución es el siguiente:

Esta solución está compuesta por los siguientes elementos:

  • InStorePaymentApi: Es una aplicación instalada tanto en la caja registradora (ECR Android) como en el terminal de pago (Android). La que está instalada en la ECR implementa un servicio AIDL para escuchar las llamadas de la aplicación integradora, mientras que la instalada en el dispositivo de pago está constantemente escuchando solicitudes de tipo PUSH o WEBSOCKETS, originadas desde la InStorePaymentApi de la ECR.
  • AzureCloud Connector: Es la nube de Azure encargada de gestionar la base de datos que registra todas las transacciones realizadas en el terminal de pago, además de permitir la conexión entre la ECR y los terminales.
  • Servidor Pushy.me: Es un servicio en la nube que permite la conexión entre la ECR y los terminales.

La conexión y comunicación entre la ECR y los terminales se puede realizar a través de notificaciones de tipo PUSH o a través de WEBSOCKETS mediante un servicio de Azure llamado SignalR:

  • Pushy: Es una solución multiplataforma basada en el protocolo MQTT para poder enviar notificaciones push utilizando identificadores únicos y autogenerados para cada dispositivo, evitando así problemas como las IP dinámicas.
  • SignalR: Es un sistema de llamadas entre dispositivos y un servidor de Azure realizado a través de websockets que permite cualquier tarea que dicho servidor sea capaz de ejecutar. De esta manera, se pueden establecer canales de comunicación entre diferentes dispositivos usando identificadores, así como registrar el uso de la API mediante una base de datos.

Aparte del flujo normal que siguen las transacciones (flechas rojas), hay otro uso del AzureCloud Connector, que es registrar todas las operaciones realizadas en los terminales de pago (flechas naranjas). Para ello, tanto el conector de la ECR como el InStorePaymentApi se registran automáticamente en dicha nube, y es el InStorePaymentApi el que actualiza la base de datos gestionada por el AzureCloud Connector al final de cada transacción.

Las conexiones establecidas por el terminal con los servidores de Pushy.me y Azure se realizan cada vez que se enciende el terminal, y se mantienen indefinidamente mientras no haya interrupciones de la conexión u otros errores. En caso de que el terminal detecte el cierre de alguna de estas conexiones, forzará el registro nuevamente: esto puede ocurrir, por ejemplo, cuando el terminal cambia de router al conectarse a una red WiFi, o cuando cambia de operador móvil mientras está en roaming.

Flujo básico de la transacción

Una transacción estándar, por ejemplo, una venta, se iniciará en la aplicación integradora. A través del servicio AIDL del InStorePaymentApi en la ECR, se informará el tipo de transacción solicitada, incluyendo el monto.

Luego, la ECR enviará la solicitud al terminal de pago a través del canal de comunicación activado en ese momento: Pushy o SignalR.

Una vez que la solicitud sea recibida en el terminal de pago, la aplicación InStorePaymentApi lanzará la transacción en la aplicación de pago Comercia C2.0 a través de una conexión AIDL. La aplicación de pago se identifica como «My POS», y es la encargada de ejecutar todo el proceso de pago:

  • Lectura de la tarjeta: en caso de error de lectura, también realiza reintentos hasta obtener una lectura correcta o agotar los intentos y cancelar la transacción.
  • Solicitud de PIN, si es necesario.
  • Comunicación con el servicio autorizador de Comercia: en caso de fallos de conexión, realiza automáticamente las cancelaciones pertinentes, informando el resultado a la caja registradora de Windows.
  • Muestra el resultado final (transacción aceptada o rechazada) en la pantalla para que el cliente lo pueda verificar.

Cuando se ha completado la transacción financiera en My POS, se prepara una respuesta que viaja de regreso a la aplicación del integrador, utilizando el mismo canal de comunicación que se usó en la solicitud original.

Este es el flujo de una transacción estándar sin errores:

Operación del ECR

El servicio AIDL que implementa la ECR en dispositivos con sistema operativo Android está en constante escucha siempre que esté en ejecución.

Cuando recibe una solicitud para realizar una transacción desde la aplicación integradora, la ECR transfiere la solicitud al terminal de pago y espera una respuesta con el resultado final de la transacción. Es en el momento de recibir dicha respuesta cuando informa a la aplicación integradora a través de callbacks.

Mientras la ECR espera la respuesta del terminal de pago, establece internamente tiempos máximos de espera para mitigar posibles demoras en caso de fallos como la caída de la red o que el terminal de pago se haya apagado inesperadamente. Errores de este tipo causarían que la ECR espere indefinidamente una respuesta, lo que haría que la aplicación integradora nunca supiera si la transacción ha sido aceptada o rechazada, con los consecuentes perjuicios.

El proceso que sigue la ECR para evitar esta situación es preguntar al POS cada 10 segundos si el proceso de pago sigue en curso. En caso de que la transacción siga en proceso y el terminal de pago continúe conectado a Internet, se enviará a la ECR una respuesta indicando que todo sigue correcto, pero aún no hay un resultado final. Hay que tener en cuenta que una transacción estándar puede tomar unos 30-40 segundos, e incluso más de 1 minuto si se requiere la introducción del PIN de la tarjeta.

Si la ECR no recibe una respuesta en esta situación, se realizarán 2 intentos adicionales para conocer el estado del terminal de pago. Si no se recibe respuesta del terminal de pago en el tercer intento (esto es, 30 segundos después de iniciar la transacción), la ECR finalizará la conexión y devolverá a la aplicación integradora que la transacción ha terminado con un error de tiempo de espera.

Este es el flujo que explica los reintentos en caso de que el terminal de pago se haya desconectado de internet:

Comparte este documento
Tabla de Contenidos

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

Comienza a integrar

undraw_add_to_cart_re_wrdo 1 (1) (1)

Plugins para CMS

Complementa la integración

SDKs

Métodos de pago

Herramientas

Addon Payments

Consulta la documentación de Addon Payments. Aquí tienes las distintas secciones:

Integraciones

Consultas frecuentes

Portal Backoffice

Cyberpac

Consulta la documentación de Cyberpac. Aquí tienes las distintas secciones:

Canales

Módulos de integración

Integraciones a medida

Pagos integrados en TPV

Crea una solución que te ayudará a automatizar procesos. Incluso, podrás agregar procesos de pago en terminales físicos.

Pago integrado con TPV Android

Pago integrado con Smartphone TPV

Fichas Técnicas TPVs