@pisell/pi-payment-sdk

Standalone PiPayment Headless SDK. The package does not import React, CSS, Pisell materials, Engine Context, or appHelper.

Initialization

import { PiPaymentSDK } from '@pisell/pi-payment-sdk';

const sdk = new PiPaymentSDK({
  environment: 'prod',
  serverRegion: 'cn',
  // Called for every request and sent as-is in Authorization.
  getToken: () => tokenManager.getValidToken(),
});

For prod and beta, serverRegion selects the regional API origin and accepts au, cn, us, or ap. It defaults to au when omitted. The dev environment keeps its development origin and ignores serverRegion. A custom baseURL takes precedence over both environment and region. A Provider registry and diagnostic logger port can also be supplied. Logger failures are isolated from payment state. Requests use a 60-second timeout and support AbortSignal.

Create one SDK per application/login lifecycle, then create an isolated Session for each payment:

const session = sdk.createSession({
  paymentMethod: 'eftpos',
  paymentProvider: 'mx51',
  salesId: 'sale-1',
  onChange(event) {
    // Render or adapt the neutral event in the host UI.
  },
});

PaymentMethod separates the existing routes:

• eftpos: terminal providers such as MX51, Tyro, and Adyen POS.
• ecom: the existing Adyen Alipay/WeChat Scan protocol.
• online: online providers; Alipay H5 currently uses the lightweight payAsync API, while Apple Pay, Google Pay, and credit-card 3DS remain future integrations.

Alipay H5 payment link

Alipay H5 does not create a Session. payAsync creates the backend payment attempt and returns the payment number plus a host-owned redirect action:

const handoff = await sdk.payAsync({
  paymentProvider: 'alipay',
  orderId: 103372,
  paymentGroupId: 4678,
  amount: 0.01,
  returnUrl: 'https://pos.example/payment-finish',
});

// Persist handoff.paymentNumber before navigating. This is not payment success.
window.location.assign(handoff.nextAction.url);

The SDK does not navigate, observe the browser return, or confirm the final payment result. The host's return page and backend payment callback are the source of truth after the user leaves for Alipay.

Host boundary

This package does not implement Pisell printing task dispatch, durable Recovery tasks, native scanner bridges, log persistence, deviceTask, interaction, or appHelper. Those capabilities and all UI belong in the host, such as @pisell/private-materials.

currency is caller-owned data. SCI pay/refund requests do not send it, and the package does not infer, convert, or validate symbols versus ISO codes.