External System Integrations

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

Overview

External System Integrations define how the MPAC platform communicates with third-party payment providers, accounting systems, and other external services. These integrations follow industry-standard protocols (OAuth2, webhooks, batch file transfer) while maintaining security, reliability, and data consistency across system boundaries.

Payment Providers
Accounting System Integration

Payment Providers

PayPay Integration

Purpose: QR code payment processing for mobile wallet transactions.

API Version: v2

Authentication: OAuth2 client credentials flow

Base URL: https://api.paypay.ne.jp

API Endpoints

Generate QR Code (MPM - Merchant Presented Mode)

http

POST /v2/codes
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "merchantPaymentId": "ORDER-12345",
  "amount": {
    "amount": 10000,
    "currency": "JPY"
  },
  "codeType": "ORDER_QR",
  "orderDescription": "Coffee x2, Sandwich x1",
  "orderItems": [
    {
      "name": "Coffee",
      "quantity": 2,
      "unitPrice": {"amount": 500, "currency": "JPY"}
    }
  ]
}

Response:

json

{
  "resultInfo": {
    "code": "SUCCESS",
    "message": "Success"
  },
  "data": {
    "codeId": "PP-CODE-12345",
    "url": "https://qr.paypay.ne.jp/...",
    "deeplink": "paypay://payment?..."
  }
}

Create Payment (CPM - Customer Presented Mode)

http

POST /v2/payments
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "merchantPaymentId": "ORDER-12345",
  "userAuthorizationId": "USER-AUTH-001",
  "amount": {
    "amount": 10000,
    "currency": "JPY"
  },
  "orderDescription": "Coffee x2, Sandwich x1"
}

Response:

json

{
  "resultInfo": {
    "code": "SUCCESS",
    "message": "Success"
  },
  "data": {
    "paymentId": "PP-PAY-67890",
    "status": "COMPLETED",
    "amount": {"amount": 10000, "currency": "JPY"}
  }
}

Get Payment Status

http

GET /v2/payments/{paymentId}
Authorization: Bearer {access_token}

Response:

json

{
  "resultInfo": {
    "code": "SUCCESS",
    "message": "Success"
  },
  "data": {
    "paymentId": "PP-PAY-67890",
    "status": "COMPLETED",
    "amount": {"amount": 10000, "currency": "JPY"},
    "merchantPaymentId": "ORDER-12345",
    "userAuthorizationId": "USER-AUTH-001",
    "storeId": "STORE-001"
  }
}

Refund Payment

http

POST /v2/refunds
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "merchantRefundId": "REFUND-001",
  "paymentId": "PP-PAY-67890",
  "amount": {
    "amount": 10000,
    "currency": "JPY"
  },
  "reason": "Customer requested refund"
}

Response:

json

{
  "resultInfo": {
    "code": "SUCCESS",
    "message": "Success"
  },
  "data": {
    "refundId": "PP-REFUND-111",
    "status": "COMPLETED",
    "amount": {"amount": 10000, "currency": "JPY"}
  }
}

Webhook Integration

Endpoint: POST /v1/webhooks/paypay

Purpose: Receive real-time payment status updates from PayPay.

Webhook Payload:

json

{
  "merchantPaymentId": "ORDER-12345",
  "paymentId": "PP-PAY-67890",
  "status": "COMPLETED",
  "amount": {"amount": 10000, "currency": "JPY"},
  "timestamp": "2026-01-28T10:30:00Z"
}

Security:

HMAC-SHA256 signature validation
Signature header: X-PayPay-Signature
Secret shared during merchant onboarding

Signature Verification:

python

import hmac
import hashlib

def verify_paypay_webhook(payload: str, signature: str, secret: str) -> bool:
    expected_signature = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(signature, expected_signature)

Credit Card Processor (SP-NET)

Purpose: Credit card payment processing via external Android application.

Integration Method: Intent-based communication (no direct API)

Communication Flow:

Terminal WebView → Android Bridge → Launch Credit Card App (Intent)
    → SP-NET App Processes Payment → Return Result via ActivityResult
    → Android Bridge → WebView JavaScript Callback

Intent Payload:

kotlin

val intent = Intent().apply {
    setClassName(
        "com.demo.smarttab.creditcard",
        "com.demo.smarttab.creditcard.MainActivity"
    )
    putExtra("amount", 10000)
    putExtra("currency", "JPY")
    putExtra("transaction_id", "TXN-12345")
}
startActivityForResult(intent, REQUEST_CODE_CREDIT_CARD)

Result Payload:

kotlin

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    if (requestCode == REQUEST_CODE_CREDIT_CARD) {
        val status = data?.getStringExtra("status") // "success" | "declined" | "error"
        val approvalCode = data?.getStringExtra("approval_code")
        val reason = data?.getStringExtra("reason")

        // Pass result to WebView
        bridge.sendCreditCardResult(status, approvalCode, reason)
    }
}

Batch Reconciliation

Purpose: Daily settlement file exchange for credit card transactions.

Method: FTP file transfer

Schedule: Daily at 02:00 JST

Upload Format (Transactions):

csv

Transaction ID,Date,Time,Amount,Approval Code,Status
TXN-12345,2026-01-28,10:30:00,10000,APP123,APPROVED
TXN-12346,2026-01-28,11:15:00,5000,APP124,APPROVED
TXN-12347,2026-01-28,12:00:00,8000,,DECLINED

Download Format (Settlement):

csv

Merchant ID,Date,Transaction Count,Gross Amount,Fees,Net Amount
MERCHANT-001,2026-01-28,245,12500000,125000,12375000

Error Handling:

Retry failed FTP transfers up to 3 times
Email notification on persistent failures
Manual reconciliation for missing files

Accounting System Integration

Status: Future Implementation

Purpose: Export transaction data to external accounting systems for financial reporting and reconciliation.

Export Data Format

json

{
  "export_type": "daily_settlement",
  "date": "2026-01-28",
  "merchant_id": 1,
  "store_id": 2,
  "transactions": [
    {
      "transaction_id": "TXN-001",
      "timestamp": "2026-01-28T10:30:00Z",
      "amount": 100000,
      "tax_amount": 8000,
      "payment_method": "CREDIT_CARD",
      "receipt_number": "RCP-001"
    },
    {
      "transaction_id": "TXN-002",
      "timestamp": "2026-01-28T11:15:00Z",
      "amount": 50000,
      "tax_amount": 4000,
      "payment_method": "PAYPAY",
      "receipt_number": "RCP-002"
    }
  ],
  "totals": {
    "gross_revenue": 25000000,
    "tax_collected": 2000000,
    "net_revenue": 23000000
  }
}

Field Descriptions:

export_type: Type of export (daily_settlement, monthly_summary, etc.)
date: Export date (YYYY-MM-DD)
merchant_id: Merchant identifier
store_id: Store identifier
transactions: Array of transaction records
- transaction_id: Unique transaction identifier
- timestamp: Transaction timestamp (ISO 8601)
- amount: Transaction amount (in smallest currency unit, e.g., yen)
- tax_amount: Tax amount included in transaction
- payment_method: Payment method used (CREDIT_CARD, PAYPAY, QR, CASH, etc.)
- receipt_number: Receipt number for reconciliation
totals: Aggregated totals for the export period
- gross_revenue: Total revenue including tax
- tax_collected: Total tax collected
- net_revenue: Revenue excluding tax

Delivery Method

Protocol: SFTP (Secure File Transfer Protocol)

Schedule: Daily at midnight (00:00 JST)

File Format Options:

CSV (comma-separated values)
JSON (structured data)
XML (legacy system compatibility)

File Naming Convention:

settlement_{merchant_id}_{store_id}_{YYYYMMDD}.{format}

Examples:
- settlement_1_2_20260128.csv
- settlement_1_2_20260128.json

SFTP Configuration

Connection Details:

Host: sftp.accounting-system.example.com
Port: 22
Authentication: SSH key-based
Directory: /exports/mpac/{merchant_id}/

Retry Policy:

Initial attempt: 00:00 JST
Retry interval: 30 minutes
Max retries: 5
Failure notification: Email to merchant admin

Error Notification

Email Template:

Subject: Daily Settlement Export Failed - Merchant {merchant_id}

Dear Administrator,

The daily settlement export for {date} failed to upload to the accounting system.

Details:
- Merchant ID: {merchant_id}
- Store ID: {store_id}
- Export Date: {date}
- Failure Reason: {error_message}
- Retry Attempt: {attempt_number}/5

The system will automatically retry in 30 minutes.

If the issue persists, please contact support.

Best regards,
MPAC SmartPOS Platform

Implementation Timeline

Phase 1 (Q2 2026): Export file generation and local storage Phase 2 (Q3 2026): SFTP integration and automated delivery Phase 3 (Q4 2026): Error handling, monitoring, and alerting

External System Integrations

Overview

Table of Contents

Payment Providers

PayPay Integration

API Endpoints

Generate QR Code (MPM - Merchant Presented Mode)

Create Payment (CPM - Customer Presented Mode)

Get Payment Status

Refund Payment

Webhook Integration

Credit Card Processor (SP-NET)

Batch Reconciliation

Accounting System Integration

Export Data Format

Delivery Method

SFTP Configuration

Error Notification

Implementation Timeline

See Also

External System Integrations ​

Overview ​

Table of Contents ​

Payment Providers ​

PayPay Integration ​

API Endpoints ​

Generate QR Code (MPM - Merchant Presented Mode) ​

Create Payment (CPM - Customer Presented Mode) ​

Get Payment Status ​

Refund Payment ​

Webhook Integration ​

Credit Card Processor (SP-NET) ​

Batch Reconciliation ​

Accounting System Integration ​

Export Data Format ​

Delivery Method ​

SFTP Configuration ​

Error Notification ​

Implementation Timeline ​

See Also ​

External System Integrations

Overview

Table of Contents

Payment Providers

PayPay Integration

API Endpoints

Generate QR Code (MPM - Merchant Presented Mode)

Create Payment (CPM - Customer Presented Mode)

Get Payment Status

Refund Payment

Webhook Integration

Credit Card Processor (SP-NET)

Batch Reconciliation

Accounting System Integration

Export Data Format

Delivery Method

SFTP Configuration

Error Notification

Implementation Timeline

See Also