Retiro de Efectivo SDK

Que es Retiro de Efectivo vía SDK

Retiro de Efectivo es una funcionalidad que permite al cliente retirar efectivo adicional al momento de realizar una compra con tarjeta, integrando el monto del retiro dentro de la misma transacción.

Esto significa que, además de pagar por sus productos o servicios, el tarjetahabiente tiene la opción de solicitar un monto extra en efectivo, el cual se carga directamente a su tarjeta de débito, sumándose al total de la compra.

Esta funcionalidad se habilita a través del modelo SaleRequest, utilizando el parámetro enableCashback. Adicionalmente, se cuenta con el parámetro cashbackFee, el cual permite configurar la comisión asociada a las transacciones con retiro de efectivo.

Beneficios

Para el cliente:

• Evita desplazarse a un cajero automático o sucursal bancaria para disponer de efectivo.
• Mayor conveniencia y rapidez al realizar compras y obtener efectivo en un solo movimiento.

Para el comercio:

• Brinda un valor agregado a sus clientes, mejorando la experiencia de compra.
• Fortalece la relación con los clientes, aumentando la lealtad y satisfacción.
• Puede generar mayor afluencia de clientes al ofrecer un servicio adicional.

Compatibilidad

Compatibles con terminales PAX y Urovo con APP Netpay Smart Core versón 2.3 en adelante integradas con sdk versión 1.2.1 y superior.

Condiciones de Uso

• El comercio debe tener habilitada la funcionalidad de retiro de efectivo tanto en configuración backend(storeid) y terminal.
• El comercio puede ofrecer transacciones de retiro de efectivo de acuerdo a la disponibilidad de efectivo existente.
• La transacción es realizado por chip y usando un NIP (no aplica para contactless)
• No aplica para transacciones con operativa QPS.
• Solo aplica pagando con tarjeta de débito que tengan la funcionalidad de retiro de efectivo.
• El bin de la tarjeta debe ser válido.
• El monto de la transaccion (antes de sumar la cantidad de retiro de efectivo) debe ser mayor a 0.
• Solo aplica para operativas de venta directa sin propina y sin meses sin intereses
• Aun y cuando este implmentada la funcionalidad, solo aplica para las transacciones que se envian con la bandera de cashbackEnabled en 1
• El monto máximo y minimo a retirar depende de la configuración establecida por adquirente, la red emisora y el comercio .
• No hay cancelación de esta transacción, las devoluciones solo aplica para el monto de compra y no el efectivo.
• Tener la librería del SDK correctamente integrada.
• Contar con un appId válido.
• El usuario debe selecionar en pantalla si requiere retiro de efectivo en su operación

Si y solo si las condiciones de uso de cumplen, la terminal desplegará el flujo de retiro de efectivo con la siguiente pantalla, de lo contrario continua con la operacion de manera normal.

Flujo de Transacción

1. El App del comercio envía una petición de venta normal con monto y el indicador de que permite cashback.

   1. La terminal inicia el proceso de cobro.
   2. El cliente inserta su tarjeta.
   3. Cliente Ingresa NIP.
   4. La terminal valida las condiciones necesarias para habilitar el retiro de efectivo

2. Si todas las condiciones se cumplen, la terminal ofrece el retiro de efectivo. Si alguna condición no se cumple, se procesa como venta normal sin opción a retiro.

3. En caso de si cumplir con las condiciones. Pregunta al cliente si desea retirar efectivo.

   1. Si el cliente no desea retiro, da click en "No" la transacción se procesa y continúa con normalidad.

   2. En caso de quie el cliente seleccion que si, le pide confirmar el monto a retirar. Si al ingresar el monto, el tarjetahabiente no se confirma el monto en 120 segundos, la terminal cancela automáticamente la transacción y notifica al punto de venta.

      

4. Al momento de confirmar el monto, la terminal envía autorización al adquirente por el total = venta + comisión + retiro.

5. Terminal recibe respuesta de la transacción (aprobada o rechazada).

   1. Si el monto de retiro está fuera de límites, se declina la transacción y muestra el mensaje “El monto del retiro de efectivo está fuera de los límites permitidos.”
   2. Si el monto de retiro = 0, se declina la transacción y se muestra el mensaje “Monto de cashback inválido.”

Integración del SDK requiere agregar la dependencia del SDK en el proyecto.

build.gradle (Project)

allprojects {
    repositories {
        google()
        jcenter()
        mavenCentral()
        maven {
            url "https://nexus.api-netpay.com/repository/netpay/"
            credentials {
                username "ext-corex"
                password "contraseña_ejemplo"
            }
        }
    }
}

build.gradle (Module)

dependencies {
    ...
    implementation 'sdk.corex:smartapi:1.2.1@aar'
}

Configuración del Modelo habilitar retiro de efectivo, debes configurar:

• enableCashback = true
• cashbackFee = <Monto de la comisión> (Opcional)

Parámetros relevantes del modelo SaleRequest:

Ejemplo:

val sale = SaleRequest(
    appId = "mx.com.netpay.demosdk",   /* PackageName de la aplicación */
    amount = 500.0,                    /* Monto total de la venta */
    tip = 0.0,                         /* Propina */
    msi = 0,                           /* Meses sin intereses */
    enableCashback = true,             /* Bandera para habilitar retiro de efectivo */
    cashbackFee = 10.0                 /* Monto de la comisión de retiro de efectivo */
)

Pasos de implementación

1. btiene una instancia de SmartApi, la cual permitirá ejecutar la transacción. La forma de obtener dicha instancia puede variar según el lenguaje de programación, como se muestra en los ejemplos de código.
2. Se construye el objeto de venta (SaleRequest), configurando los parámetros appId, amount, tip, msi, enableCashback y cashbackFee, tal como se describe en el apartado anterior.
3. Se ejecuta la transacción a través del método doTrans.

A continuación, se presentan ejemplos en Kotlin y Java que muestran cómo enviar una transacción con retiro de efectivo.

fun performSaleWithCashback() {
    /** Se obtiene una instancia de la api **/
    private val smartApi = SmartApiFactory.createSmartApi(this)

    /** Construir un objeto SaleRequest **/
    val sale = SaleRequest(
        appId = "mx.com.netpay.demosdk",   /* PackageName de la aplicación */
        amount = 500.0,                    /* Monto total de la venta */
        tip = 0.0,                         /* Propina */
        msi = 0,                           /* Meses sin intereses */
        enableCashback = true,             /* Bandera para habilitar retiro de efectivo */
        cashbackFee = 5.0                  /* Monto de la comisión */
    )

    try {
        /** Realizar transacción **/
        smartApi.doTrans(sale)
    } catch (e: SmartApiException) {
        Toast.makeText(this, e.message, Toast.LENGTH_LONG).show()
    }
}

void performSaleWithCashback() {
    try {
        /** Se obtiene una instancia de la api **/
        private SmartApi smartApi = SmartApiFactory.INSTANCE.createSmartApi(this);

        /** Datos fijos, sólo para propósito de muestra **/
        double saleAmount = 500.0;
        double tip = 0.0;
        int msi = 0;
        boolean enableCashback = true;
        double cashbackFee = 5.0;

        /** Construir objeto SaleRequest **/
        SaleRequest sale = new SaleRequest(
            "mx.com.netpay.demosdk",
            saleAmount, tip, msi, null, null, null, null, null,
            null, null, null, null, null, null, null, null,
            enableCashback, cashbackFee
        );

        /** Realizar transacción **/
        smartApi.doTrans(sale);
    } catch (JSONException je) {
        Log.e(TAG, "performSale(): " + je.getMessage());
    }
}

Se recomienda utilizar la clase OnSingleClickListener, la cual está diseñada para prevenir múltiples ejecuciones de una misma acción en un corto periodo de tiempo, evitando así eventos duplicados provocados por múltiples clicks consecutivos.

abstract class OnSingleClickListener : View.OnClickListener {
    companion object {
        private const val TAG = "OnSingleClickListener"
        private const val DISABLE_CLICK_TIME_MS = 750
        private var lastClickMs: Long = 0
    }

    override fun onClick(v: View?) {
        val currClickMs = System.currentTimeMillis()
        val diffClickMs = currClickMs - lastClickMs
        if (diffClickMs > DISABLE_CLICK_TIME_MS) {
            Log.d(TAG, "OnClick() Click allowed, diff: ${diffClickMs} ms")
            lastClickMs = currClickMs
            v?.let { onSingleClick(v) }
        } else {
            Log.w(TAG, "onClick() Click blocked, diff: ${diffClickMs} ms")
        }
    }

    abstract fun onSingleClick(view: View)
}

Implementación:

saleButton.setOnClickListener(object : OnSingleClickListener() {
    override fun onSingleClick(view: View) {
        // Lógica a implementar de smartApi
    }
})

Response

La respuesta de la transacción se obtiene mediante el callback onActivityResult(). El SDK incluye un método que facilita el procesamiento de este resultado, retornando un objeto SaleResponse para su manejo.

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    when (val response = smartApi.onResult(requestCode, resultCode, data!!)) {
        is SaleResponse -> {
            /** Utilizar objeto response **/
        }
    }
}

Los datos que serán recibidos en el objeto SaleResponse se desglosan a continuación:

Ejemplo de response de una venta con retiro de efectivo:

{
  "affiliation": "6015126",
  "aid": "A0000000031010",
  "amount": "1145.0",
  "appLabel": "VISA DEBITO",
  "arqc": "1FAE06E001C7E6B0",
  "authCode": "222110",
  "bankName": "BBVA",
  "bin": "415231",
  "cardHolderName": "",
  "cardType": "D",
  "cardTypeName": "VISA",
  "cashback": {
    "amount": "130.0",
    "fee": "15.0"
  },
  "chargeNo": "39",
  "folioNumber": "",
  "hasPin": true,
  "isOnlineTrans": true,
  "isRePrint": false,
  "orderId": "260324174433-1493194550",
  "reprintModule": "C",
  "responseCode": "00",
  "spanRoute": "1501",
  "terminalId": "1493194550",
  "transDate": "MAR. 24, 26 16:05:06",
  "transType": "A",
  "message": "Aprobada",
  "success": true
}

Ticket

Al realizar una venta con retiro de efectivo, el ticket mostrará el título "Venta con retiro".

• El campo "Subtotal" es el monto inicial.
• El campo "Retiro en efectivo" es el monto del retiro de efectivo.
• El campo "Comisión por retiro" es la comisión del retiro de efectivo.
• El campo "Total" es la suma del monto inicial + retiro de efectivo + cashbackFee.

Ejemplo:

Venta:              $200.00 (Subtotal)
Retiro de efectivo: $100.00 (Retiro en efectivo)
Comisión:           $5.00   (Comisión por retiro)
Total:              $305.00