2. Implement contactless payment callbacks

Overview

During APDU processing, NFC Wallet SDK calls your application with payment lifecycle events.

Implement ContactlessPaymentServiceListener in your digital wallet application to:

• Detect when a contactless transaction starts and completes.
• Trigger step-up authentication when CDCVM is required.
• Handle errors and recover for the next transaction.

SDK integration

Implement ContactlessPaymentServiceListener

Create a listener instance and implement the callbacks you need.

// Instantiate a listener for the HCE service.
PaymentServiceListener myPaymentListener = new ContactlessPaymentServiceListener() {

    @Override
    public void onTransactionStarted() {
        /*
         * Triggered when the first APDU is exchanged with the POS terminal.
         */
    }

    @Override
    public void onAuthenticationRequired(
            PaymentService activatedPaymentService,
            CHVerificationMethod chVerificationMethod,
            long cvmResetTimeout) {
        /*
         * Triggered when the end user must authenticate (CDCVM).
         *
         * Use chVerificationMethod to determine the required method.
         * cvmResetTimeout applies only to some methods (for example, wallet PIN).
         * Use it to tell the end user how long the verification stays valid.
         */
    }

    @Override
    public void onReadyToTap(PaymentService paymentService) {
        /*
         * Triggered after successful authentication.
         * Prompt the end user to tap again before cvmResetTimeout expires.
         */
    }

    @Override
    public void onTransactionCompleted(TransactionContext transactionContext) {
        /*
         * Triggered when the transaction completes successfully.
         * Use TransactionContext to display details (amount, date, and more).
         */
    }

    @Override
    public void onTransactionInterrupted() {
        /*
         * Triggered when the NFC link to the POS terminal is interrupted.
         * Prompt the end user to tap again.
         * Optional callback
         */
    }

    @Override
    public void onError(
            TransactionContext transactionContext,
            PaymentServiceErrorCode paymentServiceErrorCode,
            String message) {
        /*
         * Triggered when the transaction cannot complete successfully.
         */
    }

    @Override
    public void onFirstTapCompleted() {
        /*
         * Indicates the first-tap APDU processing completed.
         * Supported only for PFP-based transactions.
         */
    }

    @Override
    public void onNextTransactionReady(
            DeactivationStatus deactivationStatus,
            DigitalizedCardStatus digitalizedCardStatus,
            DigitalizedCard digitalizedCard) {
        /*
         * Triggered after a transaction completes.
         * Use it to verify the card state and prepare for the next payment.
         */
    }
};

Return the listener from your HCE service

In your class extending AsyncHCEService, return the listener from setupListener().

public class MyHCEService extends AsyncHCEService {

    @Override
    public PaymentServiceListener setupListener() {
        return myPaymentListener;
    }
}

Callback flow (typical)

Callbacks are usually triggered in this order.

onTransactionInterrupted() can occur any time after onTransactionStarted().

1. onTransactionStarted() after the first APDU exchange with the POS terminal.
2. onAuthenticationRequired() when the end user must complete CDCVM.
3. onReadyToTap() after successful authentication, to request a second tap.
4. onTransactionCompleted() when the transaction completes successfully.
5. onTransactionInterrupted() (optional) when the NFC link to the POS terminal drops. See Handle POS terminal disconnects.
6. onNextTransactionReady() when the SDK is ready for the next transaction.

If an error occurs, the SDK triggers onError() instead of completing the flow.

Handle POS terminal disconnects (optional)

The SDK can notify you when the NFC link to the POS terminal is interrupted.

Use onTransactionInterrupted() to prompt the end user to tap again.

Configure the retry behavior before starting contactless payments:

• PaymentSetting.setRetryLimit(int)

  Sets how many POS terminal disconnects are tolerated before failing the transaction.

  Default is 0.

  With 0, the SDK triggers onError() on the first disconnect.
• PaymentSetting.setTransactionRetryTimeout(long)

  Sets how long the POS terminal can retry after a disconnect.

  If no APDU is received during this interval, the SDK triggers onError().

  Range is 500 to 10000 milliseconds.

  Default is 2000 milliseconds.