Frontend SDK (@cloudsky/mpac-pgw-sdk-js)

Part of: MPAC SmartPOS Cloud Platform - Product RequirementsVersion: 2.0 Last Updated: 2026-01-28

---

Overview

The Frontend SDK provides a JavaScript/TypeScript client library for WebView applications to integrate seamlessly with the Payment Gateway (mpac-pgw). It abstracts the complexity of payment intent management, status polling, and transaction lifecycle handling, offering a clean and type-safe API for frontend developers building terminal applications.

Table of Contents

• Installation
• SDK Initialization
• Usage Examples
• SDK Methods
• Error Handling

---

Installation

NPM Package:

npm install @cloudsky/mpac-pgw-sdk-js

Yarn:

yarn add @cloudsky/mpac-pgw-sdk-js

pnpm:

pnpm add @cloudsky/mpac-pgw-sdk-js

---

SDK Initialization

Initialize the SDK client with the Payment Gateway API URL and payment token:

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

const pgw = new PGWClient({
  apiUrl: 'https://api.pgw.mpac-cloud.com',
  paymentToken: payment.payment_token
});

Configuration Options:

• apiUrl (required): Base URL of the Payment Gateway API
• paymentToken (required): Authentication token for payment operations
• timeout (optional): Request timeout in milliseconds (default: 30000)
• retryAttempts (optional): Number of retry attempts for failed requests (default: 3)

---

Usage Examples

Basic Payment Confirmation Flow

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

// Initialize client
const pgw = new PGWClient({
  apiUrl: 'https://api.pgw.mpac-cloud.com',
  paymentToken: payment.payment_token
});

// Confirm payment
const result = await pgw.confirmPayment(paymentIntentId);

if (result.status === 'succeeded') {
  // Payment completed successfully
  displayReceipt(result);
} else if (result.status === 'requires_action') {
  // Display QR code for customer scanning
  displayQR(result.qr_code_url);

  // Poll for status until terminal state reached
  const finalResult = await pgw.pollPaymentStatus(paymentIntentId, {
    maxAttempts: 60,
    interval: 2000 // Poll every 2 seconds
  });

  if (finalResult.status === 'succeeded') {
    displayReceipt(finalResult);
  } else if (finalResult.status === 'failed') {
    displayError(finalResult.error);
  }
}

Payment Cancellation

try {
  const result = await pgw.cancelPayment(paymentIntentId);
  console.log('Payment canceled:', result);
} catch (error) {
  console.error('Cancellation failed:', error);
}

Checking Payment Status

const status = await pgw.getPaymentStatus(paymentIntentId);
console.log('Current status:', status.status);
console.log('Amount:', status.amount);
console.log('Provider:', status.provider);

Listing Transactions

const transactions = await pgw.listTransactions(paymentIntentId);

transactions.forEach(tx => {
  console.log(`Transaction ${tx.id}: ${tx.status} - ${tx.amount}`);
});

---

SDK Methods

confirmPayment(id: string)

Confirms a payment intent and initiates payment processing.

Parameters:

• id (string): Payment intent ID

Returns: Promise<PaymentIntentResponse>

Throws: PGWError if confirmation fails

---

cancelPayment(id: string)

Cancels a pending payment intent.

Parameters:

• id (string): Payment intent ID

Returns: Promise<PaymentIntentResponse>

Throws: PGWError if payment cannot be canceled (e.g., already completed)

---

getPaymentStatus(id: string)

Retrieves the current status of a payment intent.

Parameters:

• id (string): Payment intent ID

Returns: Promise<PaymentIntentResponse>

Throws: PGWError if payment intent not found

---

pollPaymentStatus(id: string, options: PollOptions)

Polls payment status until a terminal state is reached (succeeded, failed, canceled).

Parameters:

• id (string): Payment intent ID
• options (object):
  • maxAttempts (number): Maximum polling attempts (default: 30)
  • interval (number): Polling interval in milliseconds (default: 2000)
  • terminateOn (string[]): Additional statuses to treat as terminal

Returns: Promise<PaymentIntentResponse>

Throws: PGWError if max attempts exceeded or polling fails

---

listTransactions(paymentIntentId: string)

Lists all transactions related to a payment intent.

Parameters:

• paymentIntentId (string): Payment intent ID

Returns: Promise<Transaction[]>

Throws: PGWError if request fails

---

Error Handling

The SDK throws typed errors that can be caught and handled appropriately:

import { PGWClient, PGWError, PGWErrorCode } from '@cloudsky/mpac-pgw-sdk-js';

try {
  const result = await pgw.confirmPayment(paymentIntentId);
} catch (error) {
  if (error instanceof PGWError) {
    switch (error.code) {
      case PGWErrorCode.PAYMENT_NOT_FOUND:
        console.error('Payment intent not found');
        break;
      case PGWErrorCode.PAYMENT_ALREADY_CONFIRMED:
        console.error('Payment already confirmed');
        break;
      case PGWErrorCode.NETWORK_ERROR:
        console.error('Network connection failed');
        break;
      default:
        console.error('Payment error:', error.message);
    }
  }
}

Common Error Codes:

• PAYMENT_NOT_FOUND - Payment intent does not exist
• PAYMENT_ALREADY_CONFIRMED - Payment already processed
• PAYMENT_CANCELED - Payment was canceled
• INVALID_TOKEN - Authentication token invalid or expired
• NETWORK_ERROR - Network request failed
• TIMEOUT - Request exceeded timeout threshold
• RATE_LIMITED - Too many requests

---

See Also

Related Integration:

• Android Native Bridge - Communication between Android app and WebView
• External System Integrations - Payment provider integrations

Domain Context:

• Payment Gateway - Payment Gateway domain specification
• Payment Processing - Payment processing workflows

Technical Implementation:

• API Architecture - REST API design patterns
• Security Architecture - Authentication and authorization

API Reference:

• API Endpoints - Complete API specification

---

Navigation: ↑ Back to Integration Specifications | Next: Android Native Bridge →