@fctc/minesec-soft

v0.0.4

Published

12 days ago

Capacitor plugin for Minesoft Headless SDK

0High
0Medium
0Low

capacitor plugin native

@fctc/minesec-soft

Capacitor plugin for Minesoft Headless SDK

Install

npm install @fctc/minesec-soft
npx cap sync

Configuration

1. Setup MineSec GitHub Registry Credentials

Add the following to your global ~/.gradle/gradle.properties file (NOT in project file):

MINESEC_REGISTRY_LOGIN=minesec-product-support
MINESEC_REGISTRY_TOKEN=ghp_your_token_here

2. Configure Android Build

Add to your android/build.gradle file:

allprojects {
    repositories {
        google()
        mavenCentral()
        def MINESEC_REGISTRY_LOGIN = findProperty("MINESEC_REGISTRY_LOGIN")
        def MINESEC_REGISTRY_TOKEN = findProperty("MINESEC_REGISTRY_TOKEN")

        if (MINESEC_REGISTRY_LOGIN == null) {
            throw new GradleException("""
                Please set your MineSec Github credential in gradle.properties.
                On local machine,
                ** DO NOT ** ** DO NOT ** ** DO NOT **
                Do not put it in the project's file. (and accidentally commit and push)
                ** DO **
                Do set it in your machine's global (~/.gradle/gradle.properties)
            """.trim())
        }

        if (MINESEC_REGISTRY_TOKEN == null) {
            throw new GradleException("MINESEC_REGISTRY_TOKEN is not set in gradle.properties")
        }

        repositories {
            maven {
                name = "MineSecMavenClientRegistry"
                url = uri("https://maven.pkg.github.com/theminesec/ms-registry-client")
                credentials {
                    username = MINESEC_REGISTRY_LOGIN
                    password = MINESEC_REGISTRY_TOKEN
                }
            }
        }
    }
}

Example Usage

import { MinesoftHeadless } from '@fctc/minesec-soft';

const paymentNFC = async () => {
  try {
    // Kiểm tra app MSA có cài chưa
    const installCheck = await MinesoftHeadless.isSoftPosInstalled();
    if (!installCheck.installed) {
      openToast({
        message: 'Vui lòng cài đặt ứng dụng MineSec MSA để thanh toán NFC',
        type: 'error',
      });
      return;
    }

    // Gửi giao dịch
    const result = await MinesoftHeadless.transaction({
      type: 'SALE',
      amount: inputValue,
      posMessageId: `${orderID}`,
      autoDismissResult: true,
    });

    // Xử lý kết quả
    if (result.success) {
      openToast({
        message: t('payment:paymentSuccessTitle') || 'Thanh toán thành công!',
        type: 'success',
      });
      goBack();
    } else {
      openToast({
        message: result.message || t('payment:paymentFailedTitle') || 'Thanh toán thất bại!',
        type: 'error',
      });
    }
  } catch (error: any) {
    const msg = error?.message || '';
    let errorMessage = 'Có lỗi xảy ra khi xử lý thanh toán NFC.';

    if (msg.includes('timeout')) errorMessage = 'Timeout khi kết nối MSA.';
    if (msg.includes('network')) errorMessage = 'Lỗi kết nối mạng.';
    if (msg.includes('permission')) errorMessage = 'Thiếu quyền truy cập.';

    openToast({ message: errorMessage, type: 'error' });
  }
};

API

MineSoft Headless Plugin Interface

Plugin Capacitor để tích hợp với MineSec SoftPOS app thông qua App-to-App calls.

isSoftPosInstalled()

isSoftPosInstalled() => Promise<InstallationStatusResponse>

Kiểm tra xem MSA app đã được cài đặt trên thiết bị chưa

Returns: Promise<InstallationStatusResponse>

warmUp()

warmUp() => Promise<PosResponse>

Thực hiện warm up - kiểm tra runtime của MSA app

Warm up sẽ kiểm tra:

Trạng thái thiết bị
Trạng thái ứng dụng
Các điều kiện cần thiết để thực hiện giao dịch

Returns: Promise<PosResponse>

activation(...)

activation(options: ActivationRequest) => Promise<PosResponse>

Kích hoạt MSA app với activation code

Activation sẽ:

Kích hoạt app với backend
Tải cấu hình cửa hàng
Tải cấu hình EMV
Tải payment keys

| Param | Type | Description | | ------------- | --------------------------------------------------------------- | ---------------------------------------- | | options | ActivationRequest | - Activation request với activation code |

Returns: Promise<PosResponse>

transaction(...)

transaction(options: TransactionRequest) => Promise<TransactionResponse>

Thực hiện giao dịch (SALE, VOID, REFUND, AUTH, AUTH_COMPLETION)

| Param | Type | Description | | ------------- | ----------------------------------------------------------------- | --------------------- | | options | TransactionRequest | - Transaction request |

Returns: Promise<TransactionResponse>

enquiryTransactionStatus(...)

enquiryTransactionStatus(options: EnquiryRequest) => Promise<TransactionResponse>

Truy vấn trạng thái giao dịch theo transaction ID

| Param | Type | Description | | ------------- | --------------------------------------------------------- | ------------------------------- | | options | EnquiryRequest | - Enquiry request với orgTranId |

Returns: Promise<TransactionResponse>

reloadConfiguration()

reloadConfiguration() => Promise<PosResponse>

Reload cấu hình EMV và payment keys từ backend

Returns: Promise<PosResponse>

enquiryBluetoothStatus()

enquiryBluetoothStatus() => Promise<BluetoothStatusResponse>

Kiểm tra trạng thái kết nối Bluetooth với thiết bị MPOS D177

Returns: Promise<BluetoothStatusResponse>

settlement(...)

settlement(options: SettlementRequest) => Promise<SettlementResponse>

Thực hiện settlement (quyết toán) tất cả các batch

| Param | Type | Description | | ------------- | --------------------------------------------------------------- | ------------------------------------- | | options | SettlementRequest | - Settlement request với posMessageId |

Returns: Promise<SettlementResponse>

Interfaces

InstallationStatusResponse

Response cho check installation

| Prop | Type | Description | | --------------- | -------------------- | -------------------------------- | | installed | boolean | true nếu MSA app đã được cài đặt |

PosResponse

Response cơ bản từ POS operations

| Prop | Type | Description | | ------------------ | -------------------- | ------------------------------------------------------------------ | | success | boolean | true nếu operation thành công | | responseCode | string | Mã phản hồi từ MSA (VD: "00" = success, "51" = insufficient funds) | | message | string | Thông báo lỗi hoặc thông tin bổ sung |

ActivationRequest

Request cho activation

| Prop | Type | Description | | -------------------- | ------------------- | ----------------------- | | activationCode | string | Mã kích hoạt từ MineSec |

TransactionResponse

Response chi tiết cho giao dịch

| Prop | Type | Description | | ------------------- | ------------------- | ----------------------------------------------- | | transactionId | string | ID giao dịch từ MSA system | | amount | string | Số tiền giao dịch | | cardNumber | string | Số thẻ đã được mask (VD: "**** **** **** 1234") | | cardType | string | Loại thẻ (VISA, MASTERCARD, AMEX, JCB, etc.) | | approvalCode | string | Mã phê duyệt từ ngân hàng | | timestamp | string | Thời gian giao dịch (ISO 8601 format) | | merchantId | string | ID merchant | | terminalId | string | ID terminal | | batchNumber | string | Số batch | | invoiceNumber | string | Số hóa đơn | | rrn | string | Retrieval Reference Number | | stan | string | System Trace Audit Number |

TransactionRequest

Request cho transaction operations

| Prop | Type | Description | | ------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------- | | type | TransactionType | Loại giao dịch | | amount | string | Số tiền (required cho SALE, AUTH) | | orgTranId | string | ID giao dịch gốc (required cho VOID, REFUND, AUTH_COMPLETION) | | posMessageId | string | ID tham chiếu từ POS system (required cho tất cả) | | autoDismissResult | boolean | Tự động đóng màn hình kết quả và quay về app (default: true) | | adminPwd | string | Mật khẩu admin merchant (required cho VOID, REFUND) | | preferredInstrument | PreferredInstrument | Phương thức thanh toán ưu tiên (cho QR payment) | | qrPaymentMethods | QRPaymentMethod | Phương thức thanh toán QR cụ thể |

EnquiryRequest

Request cho enquiry transaction status by transaction ID

| Prop | Type | Description | | --------------- | ------------------- | ------------------------- | | orgTranId | string | ID giao dịch cần truy vấn |

BluetoothStatusResponse

Response cho Bluetooth status enquiry

| Prop | Type | Description | | ------------------- | -------------------- | ------------------------------------- | | connected | boolean | true nếu đã kết nối với thiết bị MPOS | | deviceName | string | Tên thiết bị Bluetooth | | deviceAddress | string | Địa chỉ MAC của thiết bị |

SettlementResponse

Response cho settlement operation

| Prop | Type | Description | | ---------------------- | ------------------- | ---------------------------- | | batchCount | number | Số lượng batch đã settlement | | totalAmount | string | Tổng số tiền đã settlement | | transactionCount | number | Tổng số giao dịch |

SettlementRequest

Request cho settlement

| Prop | Type | Description | | ------------------ | ------------------- | --------------------------- | | posMessageId | string | ID tham chiếu từ POS system |

Type Aliases

TransactionType

Loại giao dịch

'SALE' | 'VOID' | 'REFUND' | 'AUTH' | 'AUTH_COMPLETION'

PreferredInstrument

Phương thức thanh toán ưu tiên

'QR_MERCHANT_SCAN' | 'QR_GUEST_SCAN'

QRPaymentMethod

Phương thức thanh toán QR

'ALIPAY_PLUS' | 'WECHAT_PAY' | 'VNPAY_QR'

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@fctc/minesec-soft

Install

Configuration

1. Setup MineSec GitHub Registry Credentials

2. Configure Android Build

Example Usage

API

isSoftPosInstalled()

warmUp()

activation(...)

transaction(...)

enquiryTransactionStatus(...)

reloadConfiguration()

enquiryBluetoothStatus()

settlement(...)

Interfaces

InstallationStatusResponse

PosResponse

ActivationRequest

TransactionResponse

TransactionRequest

EnquiryRequest

BluetoothStatusResponse

SettlementResponse

SettlementRequest

Type Aliases

TransactionType

PreferredInstrument

QRPaymentMethod