@cloudsky/mpac-pgw-sdk-js

MPAC Payment Gateway JavaScript/TypeScript SDK. A headless, logic-only library for integrating with the mpac-pgw payment gateway from browser and WebView applications.

Installation

npm install @cloudsky/mpac-pgw-sdk-js
# or
pnpm add @cloudsky/mpac-pgw-sdk-js
# or
yarn add @cloudsky/mpac-pgw-sdk-js

GitHub Packages

This package is published to GitHub Packages. Configure your .npmrc:

@cloudsky:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

Quick Start

import { MPSGateway } from '@cloudsky/mpac-pgw-sdk-js';

// Initialize the SDK
const mps = new MPSGateway({
  publicKey: 'pk_test_xxx',
  environment: 'sandbox',
});

// Retrieve PaymentIntent (created by your backend via HMAC-authenticated S2S call)
const intent = await mps.retrievePaymentIntent('pi_123_secret_abc888');

// Confirm QR payment (MPM - Merchant Presented Mode)
const qr = await mps.confirmQRPayment('PAYPAY');

// Render QR code using qr.qr_content
renderQRCode(qr.qr_content);

// Listen for payment events
mps.on('payment_success', (data) => {
  console.log('Payment succeeded!', data);
});

mps.on('payment_failed', (data) => {
  console.log('Payment failed:', data.error);
});

mps.on('payment_timeout', (data) => {
  console.log('Payment timed out');
});

// Clean up when done
mps.destroy();

Configuration

new MPSGateway(config: MPSGatewayConfig)

Option	Type	Default	Description
publicKey	string	Required	Your MPAC public API key
environment	'sandbox' | 'production'	'sandbox'	API environment
baseUrl	string	Auto	Custom base URL (overrides environment)
locale	'ja' | 'en'	'ja'	Locale for messages
timeout	number	300000	Polling timeout in ms (5 min)
pollingInterval	number	3000	Status check interval in ms
debug	boolean	false	Enable debug logging

API Reference

retrievePaymentIntent(paymentToken: string): Promise<PaymentIntent>

Retrieve a PaymentIntent using the payment token from your backend.

confirmQRPayment(provider: QRProvider): Promise<QRResult>

Confirm a QR payment (MPM mode). Currently supports PAYPAY, ALIPAY_PLUS, and WECHAT_PAY.

cancelPaymentIntent(): Promise<void>

Cancel the current PaymentIntent.

stopPolling(): void

Stop polling for payment status.

on(event, callback) / off(event, callback)

Subscribe/unsubscribe from payment events: payment_success, payment_failed, payment_cancelled, payment_timeout, polling_error.

destroy(): void

Clean up resources (stop polling, remove listeners).

Error Handling

import { MPSError } from '@cloudsky/mpac-pgw-sdk-js';

try {
  await mps.confirmQRPayment('PAYPAY');
} catch (error) {
  if (error instanceof MPSError) {
    console.log(error.code);    // 'provider_not_supported'
    console.log(error.message); // Human-readable message
    console.log(error.details); // Optional additional details
  }
}

Development

pnpm install
pnpm dev          # Watch mode
pnpm build        # Build for production
pnpm test         # Run tests
pnpm test:run     # Run tests once
pnpm lint         # Lint source
pnpm check-types  # Type check

License

MIT