1. Implement HCE service

Overview

NFC Wallet SDK supports Android Host Card Emulation (HCE). It allows NFC card emulation and exchange APDUs with a POS terminal over NFC.

For details, see Android documentation: Host-based card emulation overview.

To continue, first implement an HCE service as described in this section.

After you register the service, verify it appears under Tap and Pay in Android settings.

SDK integration

Extend AsyncHCEService

To handle contactless payments, enable APDU processing by extending AsyncHCEService.

You do not need to override any methods.

Use overrides only if you want to log or customize APDU handling.

public class MyHCEService extends AsyncHCEService {

    // Overriding 'processCommandApdu' is optional
    // Digital wallet application can capture APDU processing time.
    @Override
    public byte[] processCommandApdu(byte[] inputApdu, Bundle bundle) {
        // Return the SDK value (always 'null').
        // APDU processing is asynchronous.
        // The SDK automatically sends response APDU to the POS terminal.
        return super.processCommandApdu(inputApdu, bundle);
    }

    // Overriding 'onApduResponse' is optional
    // Digital wallet application can inspect or override the response APDU.
    @Override
    public boolean onApduResponse(final byte[] inputApdu, final Bundle extras, final byte[] responseApdu){
        // Digital wallet application can log responseApdu.

        // If you want to override the response and reply to the POS terminal:
        // 1. modify the responseAPDU
        // 2. sendResponseApdu(modifiedResponseApdu);
        // 3. return true; it tells the SDK the response is already sent.

        // Otherwise, return false and let the SDK send responseApdu.
        return false;
    }
}

NFC Wallet SDK suspends APDU processing when authentication is required.

APDU processing resumes after authentication succeeds, is aborted, or the HCE service is deactivated.

Some devices block background launches of an Activity for the step-up authentication prompt. This can block contactless payments until you call deactivate().

Your digital wallet application can implement a timeout and call deactivate() to unblock the contactless payment flow.

Register the service in AndroidManifest.xml

Register your HCE service (the class that extends AsyncHCEService) as HOST_APDU_SERVICE in your manifest.

<!-- The service name must match your package structure. -->
<service android:name="com.mycompany.myapplication.myservices.MyHCEService"
  android:exported="true"
  android:label="@string/app_name"
  android:permission="android.permission.BIND_NFC_SERVICE">
  <intent-filter>
    <action android:name="android.nfc.cardemulation.action.HOST_APDU_SERVICE" />
  </intent-filter>
  <meta-data
    android:name="android.nfc.cardemulation.host_apdu_service"
    android:resource="@xml/apduservice"/>
</service>

Create apduservice.xml in res/xml to declare the supported AIDs.

Declare supported AIDs

Create apduservice.xml in res/xml.

Declare the PPSE AID and the payment network AIDs you support.

 <?xml version="1.0" encoding="utf-8"?>
<host-apdu-service xmlns:android="http://schemas.android.com/apk/res/android"
  android:description="@string/hce_service_description"
  android:requireDeviceUnlock="false"
  android:apduServiceBanner="@drawable/hce_banner">
  <aid-group
    android:description="@string/aid_description"
    android:category="payment">
    <!-- required PPSE AID -->
    <aid-filter android:name="325041592E5359532E4444463031"/>
    <!-- Mastercard AIDs -->
    <aid-filter android:name="A0000000041010"/>
    <aid-filter android:name="A0000000043060"/>
    <aid-filter android:name="A0000000042010"/>
    <!-- Visa AIDs -->
    <aid-filter android:name="A0000000031010"/>
    <aid-filter android:name="A0000000980840"/>
    <aid-filter android:name="A0000000032020"/>
    <aid-filter android:name="A0000000032010"/>
    
  </aid-group>
</host-apdu-service>

In the example above:

• The required PPSE AID is:

  • 325041592E5359532E4444463031
• The Mastercard AIDs are:

  • A0000000041010
  • A0000000043060
  • A0000000042010
• The Visa AIDs are:

  • A0000000031010
  • A0000000980840
  • A0000000032020
  • A0000000032010

The AID list depends on your NFC Wallet program. Confirm the list with your payment network representative.

Verify Tap and Pay settings

After you register the HCE service in AndroidManifest.xml, it appears under Tap and Pay in Android settings.

To verify:

1. Open Settings on the device.
2. Go to Tap and Pay.
3. Confirm your application appears in the list.

Android settings showing the application listed under Tap and Pay.