Service Communication Patterns

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

Overview

This document defines all communication patterns between services, clients, and external systems in the MPAC platform. It specifies authentication mechanisms, message formats, and protocol details for each integration point. The architecture supports multiple communication patterns including REST APIs with JWT/HMAC authentication, WebSocket connections for real-time device communication, and Android Intent-based inter-app communication for terminal applications.

Frontend → Backend
SmartPOS Device → Backend
svc-smarttab → mpac-pgw
WebView SDK → mpac-pgw
External Provider → mpac-pgw (Webhooks)
Business App ↔ Credit Card App (Android Intent)

Frontend → Backend

Purpose: Secure communication between Portal UI and backend services with JWT-based authentication.

Architecture

Portal UI (React)
  └─ HTTPS + Bearer JWT
  └─ API Gateway (Kong/Krakend)
     ├─ Validates JWT via JWKS from svc-portal
     ├─ Injects headers: X-Caller-Type, X-Caller-Id, X-Role, X-Merchant-Id, X-Store-Id
     ├─ Rate limiting per user/IP
     └─ Routes to:
        ├─ svc-portal: /api/v1/auth/*, /api/v1/device/*, /api/v1/merchants/*
        └─ svc-smarttab: /api/v1/orders/*, /api/v1/bills/*, /api/v1/payments/*

JWT Claims (Human)

json

{
  "iss": "svc-portal-users",
  "sub": "user_uuid",
  "role": "MERCHANT_ADMIN",
  "merchant_id": 1,
  "store_id": 2,
  "psp_id": 1,
  "impersonated_by": "system_op_uuid",
  "exp": 1706515200
}

Key Fields:

iss: Token issuer (svc-portal-users)
sub: User UUID
role: User role (SYSTEM_OP, PSP_ADMIN, MERCHANT_ADMIN, STORE_MANAGER, STAFF)
merchant_id/store_id/psp_id: Tenant scope
impersonated_by: Present when admin impersonates another user
exp: Token expiration (15 minutes from issuance)

Key Features

JWT validation at API Gateway level
Automatic header injection for downstream services
Rate limiting per user/IP (1000 requests/min)
Request routing based on path patterns
Token refresh mechanism for long sessions

SmartPOS Device → Backend

Purpose: Secure device authentication and POS operations using OAuth2 private_key_jwt flow.

Architecture

SmartPOS Device (Android)
  ├─ OAuth2 Token Request
  │  POST /auth/device/token
  │  Body: {client_id, client_assertion (signed JWT)}
  │  ← Returns: {access_token, expires_in: 90}
  │
  └─ POS Operations (with device JWT)
     POST /orders (Bearer device_token)
     ├─ API Gateway validates token
     ├─ Injects headers: X-Caller-Type=device, X-Caller-Id=device_uuid, X-Merchant-Id, X-Store-Id
     └─ Routes to svc-smarttab

JWT Claims (Device)

json

{
  "iss": "svc-portal-devices",
  "sub": "device_uuid",
  "device_sn": "ABC123",
  "merchant_id": 1,
  "store_id": 2,
  "scope": ["order:create", "bill:create", "payment:create"],
  "exp": 1706515200
}

Key Fields:

iss: Token issuer (svc-portal-devices)
sub: Device UUID
device_sn: Device serial number
merchant_id/store_id: Store binding
scope: Permitted operations
exp: Token expiration (60-120 seconds)

Key Features

Short-lived tokens (60-120 seconds) for enhanced security
EC P-256 keypair stored in Android Keystore
Automatic token refresh by SDK
Scope-based permission control
Device binding to merchant/store

svc-smarttab → mpac-pgw

Purpose: Service-to-service communication for payment processing with HMAC authentication.

Architecture

svc-smarttab (POS Operations)
  └─ HTTPS + HMAC-SHA256 authentication
  └─ POST /v1/payment_intents
     Headers:
       Authorization: HMAC-SHA256 mpac:<timestamp>:<signature>
       Content-Type: application/json
       Idempotency-Key: uuid
     Body: {
       merchant_ref_id: "unique_per_merchant",
       amount: 100000,
       currency: "JPY",
       order_id: "ORDER-123",
       payment_method_type: "qr_mpm",
       processing_mode: "pgw_processed"
     }

  ← Response: PaymentIntent {
      id: "pi_01HXYZ",
      status: "requires_payment_method",
      payment_token: "tok_abc123"
    }

HMAC Signature Calculation

message = HTTP_METHOD + ":" + REQUEST_PATH + ":" + timestamp + ":" + request_body
signature = HMAC-SHA256(message, secret_key)
auth_header = "HMAC-SHA256 " + client_id + ":" + timestamp + ":" + Base64(signature)

Example:

Method: POST
Path: /v1/payment_intents
Timestamp: 1706515200
Body: {"merchant_ref_id":"REF123","amount":100000}

message = "POST:/v1/payment_intents:1706515200:{"merchant_ref_id":"REF123","amount":100000}"
signature = HMAC-SHA256(message, "secret_abc123")
Authorization: HMAC-SHA256 mpac:1706515200:aGVsbG8gd29ybGQ=

Key Features

HMAC-SHA256 request signing for integrity
Timestamp validation (reject requests >5 minutes old)
Idempotency key for retry safety (24h cache)
Rate limiting per merchant (1000 requests/min)
Global rate limiting (10000 requests/min)

WebView SDK → mpac-pgw

Purpose: Frontend payment confirmation using short-lived payment tokens.

Architecture

WebView (embedded in device)
  └─ Receives payment_token from parent app
  └─ HTTPS + Bearer payment_token
  └─ POST /v1/payment_intents/{id}/confirm
     Headers:
       Authorization: Bearer tok_abc123
       Content-Type: application/json
     Body: {}

  ← Response: PaymentIntent {
      status: "processing" → "succeeded"
    }

Payment Token Format

json

{
  "token": "tok_abc123",
  "payment_intent_id": "pi_01HXYZ",
  "expires_in": 300
}

Key Fields:

token: Short-lived bearer token (5 minutes)
payment_intent_id: Associated PaymentIntent
expires_in: Time to live in seconds

Key Features

Token-based authentication (no device credentials in frontend)
5-minute token TTL
One-time use tokens (invalidated after confirm)
Prevents token reuse attacks
CORS protection for WebView origins

External Provider → mpac-pgw (Webhooks)

Purpose: Asynchronous payment status updates from external payment providers.

Architecture

PayPay Backend
  └─ POST /v1/webhooks/paypay
     Headers:
       X-PayPay-Signature: hmac_signature
       Content-Type: application/json
     Body: {
       transaction_id: "PAYPAY-TXN-456",
       status: "SUCCESS",
       amount: 100000,
       currency: "JPY",
       timestamp: "2026-01-28T11:05:00Z"
     }

PGW validates signature
  └─ Lookup PaymentIntent by provider_transaction_id
  └─ Update status: succeeded
  └─ Emit event (for polling consumers)

Webhook Security

Signature Verification:

python

# Provider sends signature in header
provider_signature = request.headers["X-PayPay-Signature"]

# Calculate expected signature
message = request.body
expected_signature = HMAC-SHA256(message, provider_webhook_secret)

# Verify match
if provider_signature != expected_signature:
    raise Unauthorized()

Supported Providers

Provider	Webhook Path	Signature Header	Algorithm
PayPay	`/v1/webhooks/paypay`	`X-PayPay-Signature`	HMAC-SHA256
LINE Pay	`/v1/webhooks/linepay`	`X-LINE-Signature`	HMAC-SHA256
Rakuten Pay	`/v1/webhooks/rakuten`	`X-Rakuten-Signature`	HMAC-SHA256
d Payment	`/v1/webhooks/dpayment`	`X-DPayment-Signature`	HMAC-SHA256

Key Features

Provider-specific signature validation
Idempotency handling (ignore duplicate webhooks)
Async event emission for status updates
Retry mechanism for failed webhook processing
Dead letter queue for persistent failures

Business App ↔ Credit Card App (Android Intent)

Purpose: Inter-app communication for credit card payment processing on SmartPOS terminals.

Architecture

Business App
  └─ Launches Credit Card App via explicit Intent
     Intent: com.demo.smarttab.creditcard.MainActivity
     Extras: {
       "request": JSON {
         "corr_id": "CORR-36-1730188800000",
         "amount": 100000,
         "classificationCode": 5,
         "authorizationID": "AUTH01"
       },
       "terminal_id": "device_uuid"
     }

Credit Card App processes payment
  └─ Returns via ActivityResult
     Result Code: RESULT_OK
     Extras: {
       "result": JSON {
         "approval_code": "123456",
         "card_slip_number": "00123",
         "card_last_4": "1234",
         "status": "success"
       }
     }

Business App receives result
  └─ Updates payment record
  └─ Continues checkout flow

Request Format

json

{
  "corr_id": "CORR-36-1730188800000",
  "amount": 100000,
  "classificationCode": 5,
  "authorizationID": "AUTH01",
  "terminal_id": "device_uuid"
}

Key Fields:

corr_id: Correlation ID (format: CORR-{classification}-{timestamp})
amount: Payment amount in smallest currency unit (JPY)
classificationCode: Transaction classification (1-9)
authorizationID: Authorization identifier
terminal_id: Device UUID

Response Format

json

{
  "approval_code": "123456",
  "card_slip_number": "00123",
  "card_last_4": "1234",
  "status": "success",
  "error_message": null
}

Status Values:

success: Payment approved
declined: Payment declined
error: Processing error
cancelled: User cancelled

Key Features

Explicit Intent for security (no intent interception)
Correlation ID for transaction tracking
Error handling and timeout management
Structured response format
Automatic app installation check

Cross-References

Identity & Access Management (IAM) - JWT token format and validation
Payment Gateway - HMAC authentication and payment flows
Device Management - Device provisioning and OAuth2 flow

Security Architecture - Authentication and encryption details
Database Architecture - Data synchronization patterns
Performance & Scalability - Rate limiting and caching

API Reference - Complete endpoint documentation
WebSocket Protocol - Real-time device communication
SDK Documentation - Client library integration

Previous: Reporting & AnalyticsNext: Database ArchitectureUp: Technical Architecture Index

Service Communication Patterns

Overview

Table of Contents

Frontend → Backend

Architecture

JWT Claims (Human)

Key Features

SmartPOS Device → Backend

Architecture

JWT Claims (Device)

Key Features

svc-smarttab → mpac-pgw

Architecture

HMAC Signature Calculation

Key Features

WebView SDK → mpac-pgw

Architecture

Payment Token Format

Key Features

External Provider → mpac-pgw (Webhooks)

Architecture

Webhook Security

Supported Providers

Key Features

Business App ↔ Credit Card App (Android Intent)

Architecture

Request Format

Response Format

Key Features

Cross-References

Navigation

Service Communication Patterns ​

Overview ​

Table of Contents ​

Frontend → Backend ​

Architecture ​

JWT Claims (Human) ​

Key Features ​

SmartPOS Device → Backend ​

Architecture ​

JWT Claims (Device) ​

Key Features ​

svc-smarttab → mpac-pgw ​

Architecture ​

HMAC Signature Calculation ​

Key Features ​

WebView SDK → mpac-pgw ​

Architecture ​

Payment Token Format ​

Key Features ​

External Provider → mpac-pgw (Webhooks) ​

Architecture ​

Webhook Security ​

Supported Providers ​

Key Features ​

Business App ↔ Credit Card App (Android Intent) ​

Architecture ​

Request Format ​

Response Format ​

Key Features ​

Cross-References ​

Related Domains ​

Related Technical Sections ​

Related Integration Sections ​

Navigation ​

Service Communication Patterns

Overview

Table of Contents

Frontend → Backend

Architecture

JWT Claims (Human)

Key Features

SmartPOS Device → Backend

Architecture

JWT Claims (Device)

Key Features

svc-smarttab → mpac-pgw

Architecture

HMAC Signature Calculation

Key Features

WebView SDK → mpac-pgw

Architecture

Payment Token Format

Key Features

External Provider → mpac-pgw (Webhooks)

Architecture

Webhook Security

Supported Providers

Key Features

Business App ↔ Credit Card App (Android Intent)

Architecture

Request Format

Response Format

Key Features

Cross-References

Related Domains

Related Technical Sections

Related Integration Sections

Navigation