Hipay MiniApp SDK

Typed JavaScript/TypeScript API for calling native Hipay SuperApp features from a MiniApp running inside the Hipay WebView.

The SDK communicates through window.HPSNative, which is injected by the Hipay application. Calls return promises and must be made from inside a supported Hipay MiniApp WebView.

Installation

npm install @hipaymn/miniapp-sdk

Or with Yarn:

yarn add @hipaymn/miniapp-sdk

Quick start

Use named exports:

import {pay, requestPasscode} from "@hipaymn/miniapp-sdk";

const verification = await requestPasscode();

if (verification.pass) {
    await pay("CHECKOUT_ID");
}

The same methods are available on the default export:

import hipay from "@hipaymn/miniapp-sdk";

await hipay.pay("CHECKOUT_ID");

Handler availability and compatibility

Recent versions of the Hipay bridge publish their supported handlers. The SDK automatically loads and caches this list before making a native call. If a method is unavailable, the call is rejected locally with NativeHandlerUnavailableError instead of sending an unsupported message to the native application.

import {
    getAvailableHandlers,
    isNativeHandlerAvailable,
    NativeHandlerUnavailableError,
    readUmoneyCard,
} from "@hipaymn/miniapp-sdk";

const handlers = await getAvailableHandlers();
console.log(handlers);

if (await isNativeHandlerAvailable("readUmoneyCard")) {
    const card = await readUmoneyCard();
    console.log(card.idEp);
}

try {
    await readUmoneyCard();
} catch (error) {
    if (error instanceof NativeHandlerUnavailableError) {
        console.error(`${error.handler} is not supported by this app version`);
    }
}

Call getAvailableHandlers(true) to bypass the cache and refresh the list.

Older bridge versions that do not expose HPSNative.getAvailableHandlers remain supported. In that case, the SDK sends the requested call directly and lets the native bridge handle compatibility.

Payments and transfers

pay(checkoutId)

Starts payment confirmation for a checkout ID.

import {pay} from "@hipaymn/miniapp-sdk";

await pay("123456");

topupMCSD(data)

Starts an MCSD account top-up.

import {topupMCSD} from "@hipaymn/miniapp-sdk";

await topupMCSD({
    biccode: "BANK_CODE",
    acntno: "ACCOUNT_NUMBER",
    acntname: "Account holder",
    comment: "Investment top-up",
    url: window.location.href,
    title: "My MiniApp",
    entityId: "MINI_APP_ENTITY_ID",
});

goToTopUp(data?)

Opens the transfer top-up flow. amount is optional and becomes a fixed transfer amount when provided.

import {goToTopUp} from "@hipaymn/miniapp-sdk";

await goToTopUp({
    amount: 50_000,
    isTransfer: true,
    url: window.location.href,
    title: "My MiniApp",
    entityId: "MINI_APP_ENTITY_ID",
});

Navigation

navigate(screen, params?, options?)

Navigates to a native screen. Set replace to replace the current route. Transfer-related routes may also receive amount and returnScreen.

import {navigate} from "@hipaymn/miniapp-sdk";

await navigate(
    "TargetScreen",
    {source: "miniapp"},
    {
        replace: false,
        amount: 25_000,
        returnScreen: {
            screen: "MiniWebView",
            params: {
                url: window.location.href,
                title: "My MiniApp",
                entityId: "MINI_APP_ENTITY_ID",
            },
        },
    },
);

Native route names are defined by the Hipay application. Only navigate to routes documented for MiniApps.

Other navigation methods

import {back, openMiniApp} from "@hipaymn/miniapp-sdk";

await openMiniApp("ANOTHER_MINI_APP_ENTITY_ID");
await back();

Image selection and modals

launchImageLibrary(imageType, options?)

Opens the device image library and resolves with the selected image.

import {launchImageLibrary} from "@hipaymn/miniapp-sdk";

const image = await launchImageLibrary("profile", {
    title: "Choose a photo",
    mediaType: "photo",
    maxWidth: 1024,
    maxHeight: 1024,
});

console.log(image.uri, image.imageType);

pickImage and imageLibrary are aliases of launchImageLibrary.

openCitizenIdImagePicker(imageType, options?)

Opens the configured citizen-ID gallery picker.

import {openCitizenIdImagePicker} from "@hipaymn/miniapp-sdk";

const image = await openCitizenIdImagePicker("citizenIdFront");
console.log(image.uri);

For other native modals, use the generic API:

import {openModal} from "@hipaymn/miniapp-sdk";

const result = await openModal<MyModalResult>("MY_MODAL", {
    example: true,
});

The modal type must be registered by the native bridge.

Profile settings

changeEmail and changeAddress open their corresponding native settings flows. Return information allows the application to reopen the MiniApp afterward.

import {changeAddress, changeEmail} from "@hipaymn/miniapp-sdk";

const returnToMiniApp = {
    url: window.location.href,
    title: "My MiniApp",
    entityId: "MINI_APP_ENTITY_ID",
};

await changeEmail(returnToMiniApp);
// Or:
await changeAddress(returnToMiniApp);

Passcode verification

import {requestPasscode} from "@hipaymn/miniapp-sdk";

const result = await requestPasscode({biometric: false});

if (result.pass) {
    // Continue with the protected action.
}

The call rejects when a passcode is not configured or native verification fails.

UMoney NFC card

import {readUmoneyCard} from "@hipaymn/miniapp-sdk";

const card = await readUmoneyCard();

console.log({
    cardType: card.cardType,
    cardId: card.idEp,
    issuedAt: card.diss,
    expiresAt: card.dexp,
});

The user must run this method on an NFC-capable device with NFC enabled.

Low-level API

Use callNative for a native handler that does not yet have a high-level SDK wrapper. Known SDK handlers are fully typed.

import {callNative} from "@hipaymn/miniapp-sdk";

const result = await callNative<{value: string}>(
    "customHandler",
    {input: "example"},
    30_000,
);

Arguments are callNative(type, data?, timeout?). The bridge's default timeout is 60 seconds.

Error handling

All SDK operations return promises. Handle errors around native calls, including cancellation, timeout, an unavailable bridge, and unsupported handlers.

import {NativeHandlerUnavailableError, pay} from "@hipaymn/miniapp-sdk";

try {
    await pay("CHECKOUT_ID");
} catch (error) {
    if (error instanceof NativeHandlerUnavailableError) {
        console.error("Please update the Hipay application");
    } else {
        console.error("Native operation failed", error);
    }
}

HPSNative bridge not found means the page is not running inside a compatible Hipay WebView or the bridge has not been injected yet.

Development

yarn install
yarn build

The build produces ESM, CommonJS, and TypeScript declaration files in dist.

License

MIT