Adquisición de tarjeta y pagos en dos pasos

La adquisición de tarjeta lee los datos de la tarjeta sin realizar un cobro inmediato. Su uso principal es el modelo de transacción dual (en dos pasos): el primer paso adquiere la tarjeta y predeclara el pago; el segundo paso envía una finalización que hace referencia a la adquisición. Así es como se separa "leer la tarjeta" de "cobrar la tarjeta", lo cual es útil cuando el monto final no se conoce en el momento en que se presenta la tarjeta.

Requisito previo: una sesión activa.

Adquisición simple de tarjeta

Leer los datos de la tarjeta por sí solos:

viewModelScope.launch {
    clientSDK.sendCardAcquisitionRequest(
        RetailerMessageArguments.CardAcquisitionMessageArguments.AcquisitionArguments(
            saleTransactionId = "Sale001",
            loyaltyHandlingType = LoyaltyHandlingType.FORBIDDEN
        )
    )
}

• saleTransactionId — tu referencia para la operación.
• loyaltyHandlingType — un LoyaltyHandlingType con exactamente dos valores: FORBIDDEN (sin manejo de lealtad) o ALLOWED (permitir el procesamiento de lealtad durante la adquisición).

La respuesta es un subtipo de RetailerAcquisitionResponse. Una respuesta exitosa lleva un POITransactionID — guárdalo; el paso de finalización lo necesita.

El flujo en dos pasos (transacción dual)

Paso 1 — adquirir y predeclarar el pago

DualTransactionArguments adquiere la tarjeta y declara el pago que seguirá, para que la aplicación de pago pueda capturar lo que necesita para la finalización posterior:

clientSDK.sendCardAcquisitionRequest(
    RetailerMessageArguments.CardAcquisitionMessageArguments.DualTransactionArguments(
        saleTransactionId = "Sale001",
        paymentAmounts = PaymentAmounts(currency = "EUR", amount = BigDecimal("10.00")),
        paymentType = RTRPaymentType.NORMAL,
        loyaltyHandlingType = LoyaltyHandlingType.FORBIDDEN
    )
)

Captura el POITransactionID (y su marca de tiempo) desde el SuccessRetailerAcquisitionResponse — estos vinculan el paso dos con el paso uno.

Paso 2 — completar el pago, haciendo referencia a la adquisición

Envía un pago con paymentType = COMPLETION que lleva un CardAcquisitionReference construido a partir del ID de transacción POI y la marca de tiempo de la adquisición:

clientSDK.sendPaymentRequest(
    RetailerMessageArguments.PaymentRequestMessageArguments.CardAcquisitionCompletionArguments(
        saleTransactionId = "Sale001",
        paymentAmounts = PaymentAmounts(currency = "EUR", amount = BigDecimal("10.00")),
        paymentType = PaymentType.COMPLETION,
        cardAcquisitionReference = RTRCardAcquisitionReference(
            transactionID = "<POITransactionID from step 1>",
            timeStamp = "<timestamp from step 1>"
        )
    )
)

La cardAcquisitionReference de la finalización es lo que une el cargo a la lectura de la tarjeta del paso uno. Sin una respuesta de adquisición capturada, no tienes nada a qué hacer referencia — ejecuta primero el paso uno.

Lectura de resultados

when (message) {
    is SuccessRetailerAcquisitionResponse -> { /* capturar POITransactionID + marca de tiempo */ }
    is ErrorRetailerAcquisitionResponse   -> { /* adquisición fallida */ }
    // la finalización produce un RetailerPaymentResponse, manejado como un pago normal
}

Relacionado

• Guía: realizar un pago — la alternativa de un solo paso y la mecánica de finalización.
• Cómo funciona el modelo de mensajes — capturando la respuesta de adquisición en el interceptor.
• Referencia API (sdk-doc.zip) — subtipos completos de CardAcquisitionMessageArguments, LoyaltyHandlingType y CardAcquisitionReference.