Watch Payment SDK - HarmonyOS Lite

HarmonyOS Lite Pay SDK Introduction

Basic abbreviations and definitions

What is HarmonyOS Lite Pay SDK?

HarmonyOS Lite Pay SDK is a client-side payment component for HarmonyOS Lite wallet applications. It manages local card profiles and transaction credentials, establishes pairing and provisioning sessions, selects payment cards, and processes contactless payments.

The SDK is not a complete wallet application. The integrator owns the UI, HCE lifecycle, backend or companion-application transport, payment-instrument store, and HarmonyOS platform adapters.

How Huawei Pay SDK works

The SDK provides five public components:

• Crypto - adapts HUKS and CryptoFramework.
• StatusManager - SDK version and device pairing.
• SyncManager - secure session, profiles, credentials, and deletion.
• PaymentInstance - payment dependencies and application callbacks.
• PaymentManager - card selection and APDU processing.

HarmonyOS Lite page-size limitation

For HarmonyOS Lite, divide SDK bootstrap work across dedicated pages because the platform constrains the size of an individual page. Do not concentrate all SDK setup in one startup page: prepare Crypto, PaymentInstance, PaymentManager, SyncManager, and StatusManager in a sequential page chain.

This is a recommended HarmonyOS Lite integration architecture, not a public SDK limitation. You may use different page names or UI structure, provided that the SDK dependency and initialisation order are retained.

Versioning and backward compatibility

The runtime version is available through StatusManager.getSdkVersion().

Adopt semantic versioning for released artifacts:

Technical overview

SDK basic configuration

The host application must provide:

• A file-system adapter compatible with @system.file.
• HUKS through @ohos.security.huks.
• CryptoFramework through @ohos.security.cryptoFramework.
• An NFC HCE service that receives terminal APDUs and transmits SDK responses.
• An authorised backend or companion application for pairing and provisioning.
• Optional non-sensitive logging adapters.

The SDK is delivered as five ES modules: SdkDependencies, SdkInit, SdkPayment, SdkStatus, and SdkSync. Each module exposes one public SDK component.

Application architecture and responsibilities

SDK setup

For HarmonyOS Lite, organise SDK setup as five lightweight pages to stay within per-page size constraints. Each page configures one SDK component and then navigates to the next page. Store the configured SDK instances in shared application state: crypto, paymentInstance, paymentManager, syncManager, and statusManager.

Page 1 - init_payment_dependencies

import huks from '@ohos.security.huks';
import cryptoFramework from '@ohos.security.cryptoFramework';

export default {
  onInit() {
    const paymentKit = getApp().data.paymentKit;

    paymentKit.crypto = new Crypto()
      .setHuks(huks)
      .setCryptoFramework(cryptoFramework)
      .initialize();

    navigate('init_payment_instance');
  }
};

Page 2 - init_payment_instance

import File from '@system.file';

export default {
  onInit() {
    const paymentKit = getApp().data.paymentKit;

    paymentKit.paymentInstance = new PaymentInstance()
      .setFileSystem(File)
      .setTransactionEventListener(paymentListener)
      .setCrypto(paymentKit.crypto);

    navigate('init_payment_manager');
  }
};

paymentListener must implement onContactlessPaymentCompleted, onContactlessPaymentAborted, and onTransactionStopped.

Page 3 - init_payment_manager

export default {
  onInit() {
    getApp().data.paymentKit.paymentManager = new PaymentManager();

    navigate('init_payment_sync_manager');
  }
};

Page 4 - init_payment_sync_manager

import File from '@system.file';

export default {
  onInit() {
    const paymentKit = getApp().data.paymentKit;

    paymentKit.syncManager = new SyncManager()
      .setFileSystem(File)
      .setCrypto(paymentKit.crypto);

    navigate('init_payment_status_manager');
  }
};

Page 5 - init_payment_status_manager

export default {
  onInit() {
    const paymentKit = getApp().data.paymentKit;

    paymentKit.statusManager = new StatusManager()
      .setCrypto(paymentKit.crypto)
      .initialize();

    if (paymentKit.statusManager.isDevicePaired()) {
      paymentKit.paymentInstance.initialize();
      paymentKit.paymentManager
        .setInitializedPaymentInstance(paymentKit.paymentInstance)
        .initialize();
      paymentKit.syncManager.initialize();
    }

    navigate('next_application_page');
  }
};

When the device is not paired, run the pairing flow first. After StatusManager.pairDevice(...) succeeds, initialise PaymentInstance, PaymentManager, and SyncManager using the same sequence shown in Page 5.

Configuration methods return the same instance, so they can be called in a chain. Operational methods throw an error when invoked before the component has been initialized.

HCE integration

The host application owns the HCE service. It selects a card before terminal exchange and forwards every received APDU to PaymentManager.

const result = paymentManager.selectForPayment(cardId);
if (result.unusedCredentialsCount === 0) {
  // Trigger authorised credential replenishment instead of local payment.
}

function onHceCommand(apduBytes) {
  const request = new Int8Array(apduBytes.length);
  request.set(apduBytes);

  const response = paymentManager.processApdu(request);
  if (response && response.length > 0) {
    hceService.transmit(Array.from(response));
  }
}

The SDK dispatches SELECT, READ RECORD, GET PROCESSING OPTIONS, and GENERATE AC payment APDUs. Do not modify request or response bytes.

HCE configuration

HCE is configured by the HarmonyOS Lite host application. It is required to deliver contactless APDUs to PaymentManager, but it is not configured by the SDK itself.

Required HarmonyOS permissions

HCE configuration consists of the ability declaration in config.json and the runtime application name and AID list. Keep the AID values identical in both places.

{
  "app": {
    "bundleName": "[APP_PACKAGE_NAME]"
  },
  "module": {
    "deviceType": [
      "liteWearable"
    ],
    "reqPermissions": [
      {
        "name": "ohos.permission.NFC_TAG",
        "reason": "Card payments",
        "usedScene": {
          "ability": [
            "MainAbility"
          ],
          "when": "always"
        }
      },
      {
        "name": "ohos.permission.NFC_CARD_EMULATION",
        "reason": "Card payments",
        "usedScene": {
          "ability": [
            "MainAbility"
          ],
          "when": "always"
        }
      }
    ],
    "abilities": [
      {
        "skills": [
          {
            "entities": [
              "ohos.nfc.cardemulation.action.HOST_APDU_SERVICE"
            ],
            "actions": [
              "ohos.nfc.cardemulation.action.HOST_APDU_SERVICE"
            ]
          }
        ],
        "metaData": {
          "customizeData": [
            {
              "name": "paymentAid",
              "value": "325041592E5359532E4444463031"
            },
            {
              "name": "paymentAid",
              "value": "A0000000041010"
            },
            {
              "name": "otherAid",
              "value": "A0000000042203"
            },
            {
              "name": "otherAid",
              "value": "A0000000043060"
            },
            {
              "name": "otherAid",
              "value": "A0000000049100"
            }
          ]
        },
        "name": ".MainAbility",
        "srcLanguage": "js",
        "srcPath": "MainAbility",
        "type": "page"
      }
    ]
  }
}

HCE service configuration

Configure the host HCE service with the application name and AID list from the HCE configuration above. The complete example below creates the service, starts it, handles the hceCmd event, forwards APDUs to PaymentManager, transmits the response, and stops the service.

config.js

export const appName = '[APP_PACKAGE_NAME]';

export const aidList = [
  '325041592E5359532E4444463031', // PPSE: 2PAY.SYS.DDF01
  'A0000000041010',
  'A0000000042203',
  'A0000000043060',
  'A0000000049100'
];

import cardEmulation from '@ohos.nfc.cardEmulation';
import { appName, aidList } from './config';


// Create one service instance for the application lifecycle.
const hceService = cardEmulation
  ? new cardEmulation.HceService()
  : undefined;

export function startHce(paymentManager) {
  if (!hceService) {
    throw new Error('HCE service is not available on this device.');
  }

  // Register this application and all supported AIDs for HCE.
  hceService.start(appName, aidList);

  // Receive an APDU command from the payment terminal.
  hceService.on('hceCmd', apduBytes => {
    const apdu = new Int8Array(apduBytes.length);
    apdu.set(apduBytes);

    // PaymentManager must already be initialised and a card selected.
    const response = paymentManager.processApdu(apdu);
    if (!response || response.length === 0) {
      return;
    }

    // Send the SDK response APDU back to the terminal.
    hceService.transmit(Array.from(response), error => {
      if (error) {
        // Apply non-sensitive application error handling.
      }
    });
  });
}

export function stopHce() {
  if (hceService) {
    hceService.stop(appName);
  }
}

Call startHce(paymentManager) during the application lifecycle after PaymentManager is available. Call stopHce() when the host application is destroyed.

SDK usage

Domains

Error handling

SDK methods throw JavaScript Error objects. Catch errors at the application boundary, present safe user states, and log only a non-sensitive code or correlation ID.

File-system, cryptography, validation, and APDU layers can also surface underlying errors. Do not expose raw exception text or sensitive values to users.

Dependencies domain

Crypto

Status domain

StatusManager

Pairing flow

const pairingData = statusManager.getDevicePairingData();
// Send pairingData to the authorised backend or companion application.
// Receive encryptedPairingResult through the authenticated channel.
statusManager.pairDevice(encryptedPairingResult);

paymentInstance.initialize();
paymentManager.setInitializedPaymentInstance(paymentInstance).initialize();
syncManager.initialize();

Treat pairing input and output values as opaque Base64. Never parse, modify, log, or expose them in the UI.

Synchronisation domain

SyncManager

Secure-session and provisioning flow

const profileSessionResponse = syncManager.getSessionKey(profileRsaComponentsBase64);
// Return profileSessionResponse through the authenticated channel.
const { cardId } = syncManager.syncProfileData(encryptedProfileBase64);


const credentialsSessionResponse = syncManager.getSessionKey(
  credentialsRsaComponentsBase64
);
// Return credentialsSessionResponse through the authenticated channel.
const { credentialsCount } = syncManager.syncTransactionCredentials(
  encryptedCredentialsBase64
);
// Persist cardId against the host payment instrument.

Synchronise the profile before credentials. Create a new secure session with getSessionKey() before each encrypted payload. Treat every provisioning value as opaque Base64 data.

Credentials status, deletion, and reset

const status = syncManager.getUsedCredentials();
// status.cardInfos: [{ cardId, credentialsCount }]
// status.usedCredentialsInfo: opaque Base64 status for the remote party

syncManager.deleteCard(cardId); // One card
syncManager.clear(); // Explicit user-confirmed unpair/logout/reset only

clear() is destructive. It deletes every stored card profile and credential, then removes local wallet and pairing keys. The device must be paired and provisioned again afterwards.

Payment domain

PaymentInstance

PaymentManager

Transaction event listener

const paymentListener = {
  onContactlessPaymentCompleted(card, log) {
    const cardId = card.getCardId();
    const outcome = log.getTransactionOutcome();
  },
  onContactlessPaymentAborted(card, abortReason, error) {
    // Show a safe aborted state; record non-sensitive diagnostics.
  },
  onTransactionStopped() {
    // Clear transient payment UI state.
  }
};

Models

Core result models

type SelectForPaymentResult = { unusedCredentialsCount: number };
type SyncProfileResult = { cardId: string };
type SyncCredentialsResult = { cardId: string, credentialsCount: number };
type UsedCredentialsResult = {
  cardInfos: Array<{ cardId: string, credentialsCount: number }>;
  usedCredentialsInfo: string; // opaque Base64 value
};

Payment-event models

interface Card { getCardId(): string; }
interface ContactlessLog {
  getTransactionOutcome(): TransactionOutcome;
  getTerminalInformation(): TerminalInformation;
  getTransactionInformation(): TransactionInformation;
  getTransactionId(): Int8Array;
}
interface TerminalInformation {
  getTerminalType(): TerminalType;
  getMerchantAndLocation(): Int8Array;
}
interface TransactionInformation {
  getCurrencyCode(): Int8Array;
  getAuthorizedAmount(): Int8Array;
  getOtherAmount(): Int8Array;
  getTransactionRange(): 'LOW_VALUE' | 'HIGH_VALUE' | 'UNKNOWN';
  getRichTransactionType():
    | 'PURCHASE' | 'REFUND' | 'CASH' | 'TRANSIT'
    | 'PURCHASE_WITH_CASHBACK' | 'UNKNOWN';
  getExpectedUserActionOnPoi():
    | 'NONE' | 'ONLINE_PIN' | 'SIGNATURE'
    | 'ONLINE_PIN_OR_SIGNATURE' | 'UNKNOWN';
  getPurpose(): 'AUTHORIZE' | 'AUTHENTICATE' | 'UNKNOWN';
  getConditionsOfUse(): 'DOMESTIC' | 'INTERNATIONAL' | 'UNKNOWN';
  hasTerminalRequestedCdCvm(): boolean;
}

Transaction outcomes: AUTHORIZE_ONLINE, AUTHENTICATE_OFFLINE, DECLINE_BY_TERMINAL, DECLINE_BY_CARD, WALLET_ACTION_REQUIRED.

Abort reasons: WALLET_CANCEL_REQUEST, CARD_ERROR, TERMINAL_ERROR.

TerminalType returns BANK_ATTENDED_, BANK_UNATTENDED_, MERCHANT_ATTENDED_, MERCHANT_UNATTENDED_, CARDHOLDER_OPERATED_*, or UNKNOWN.

Amounts, currency code, merchant/location, and transaction ID are Int8Array values. Preserve bytes until decoding them according to the applicable EMV/protocol rules.

HarmonyOS Lite SDK initialisation pages

Split the SDK bootstrap flow across dedicated pages to keep individual pages within HarmonyOS Lite page-size constraints and to isolate the setup responsibility of each SDK component.

Only SDK-related pages are documented here. Other application pages and services are host-application concerns and are not part of the SDK contract.

Keep the shared SDK instances in getApp().data, rather than in page-local state, so every initialisation page and payment flow uses the same objects. Store crypto, paymentInstance, paymentManager, syncManager, and statusManager there.

You may use a different page structure or page names, but retain this dependency order: