Card acquisition and two-step payments

Card acquisition reads card data without immediately taking a payment. Its main use is the dual-transaction (two-step) model: step one acquires the card and pre-declares the payment; step two sends a completion that references the acquisition. This is how you split "read the card" from "charge the card" — useful when the final amount isn't known at the moment the card is presented.

Prerequisite: a live session.

Simple card acquisition

Read card data on its own:

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

saleTransactionId — your reference for the operation.
loyaltyHandlingType — a LoyaltyHandlingType with exactly two values: FORBIDDEN (no loyalty handling) or ALLOWED (permit loyalty processing during acquisition).

The response is a subtype of RetailerAcquisitionResponse. A successful response carries a POITransactionID — keep it; the completion step needs it.

The two-step (dual-transaction) flow

Step 1 — acquire and pre-declare the payment

DualTransactionArguments acquires the card and declares the payment that will follow, so the payment app can capture what it needs for the later completion:

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

Capture the POITransactionID (and its timestamp) from the SuccessRetailerAcquisitionResponse — these link step two back to step one.

Step 2 — complete the payment, referencing the acquisition

Send a payment with paymentType = COMPLETION carrying a CardAcquisitionReference built from the acquisition's POI transaction ID and timestamp:

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

The completion's cardAcquisitionReference is what ties the charge to the card read in step one. Without a captured acquisition response, you have nothing to reference — run step one first.

Reading the results

when (message) {
    is SuccessRetailerAcquisitionResponse -> { /* capture POITransactionID + timestamp */ }
    is ErrorRetailerAcquisitionResponse   -> { /* acquisition failed */ }
    // completion produces a RetailerPaymentResponse, handled as a normal payment
}

Guide: taking a payment — the single-step alternative, and the completion mechanics.
How the message model works — capturing the acquisition response in the interceptor.
API reference (sdk-doc.zip) — full CardAcquisitionMessageArguments subtypes, LoyaltyHandlingType, and CardAcquisitionReference.