Payment Gateway Service (mpac-pgw)

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

---

Overview

The Payment Gateway (PGW) is a unified payment processing service that abstracts multiple payment providers behind a single API interface. It manages the entire payment lifecycle from intent creation through completion, handling provider integrations, state transitions, webhooks, and multi-tenant configuration. The service implements a robust PaymentIntent state machine and provides both server-to-server and SDK-facing APIs for secure payment processing.

Table of Contents

• Purpose & Responsibilities
• PaymentIntent State Machine
• Authentication
• Provider Integration
• Multi-Tenant Configuration Sync
• Rate Limiting
• API Endpoints Summary

---

Purpose & Responsibilities

The Payment Gateway (PGW) is a unified payment processing service that abstracts multiple payment providers behind a single API interface. It handles:

• Payment provider integrations (PayPay, LINE Pay, etc.)
• PaymentIntent state machine
• Idempotency and retry handling
• Webhook processing from providers
• Transaction ledger and reconciliation
• Multi-tenant configuration management

---

PaymentIntent State Machine

Core Entity: PaymentIntent represents a customer's intent to pay.

State Transitions

requires_payment_method ──▶ requires_action ──▶ processing ──▶ succeeded
         │                        │                │
         └────────────────────────┴────────────────┴──▶ failed
         │                        │
         └────────────────────────┴──────────────────▶ cancelled

State Descriptions

• requires_payment_method - Created, awaiting payment method selection
• requires_action - Customer action required (scan QR, enter card)
• processing - Provider processing payment
• succeeded - Payment completed successfully
• failed - Payment failed (insufficient funds, declined, etc.)
• cancelled - Customer or staff cancelled payment

PaymentIntent Entity

{
  "id": "pi_01HXYZ...",
  "merchant_id": 1,
  "store_id": 2,
  "client_partner_id": 1,
  "merchant_ref_id": "POS-TXN-12345",
  "order_id": "ORDER-001",
  "amount": 100000,
  "currency": "JPY",
  "payment_method_type": "qr_mpm|qr_cpm|credit_card|cash",
  "processing_mode": "pgw_processed|external|manual",
  "status": "requires_payment_method",
  "payment_token": "tok_abc123",
  "provider_name": "paypay",
  "provider_transaction_id": "PAYPAY-TXN-456",
  "failure_code": null,
  "failure_message": null,
  "metadata": {},
  "created_at": "2026-01-28T11:00:00Z",
  "updated_at": "2026-01-28T11:01:00Z"
}

---

Authentication

Two Auth Methods:

1. HMAC-SHA256 (Server-to-Server)

Used by: svc-smarttab ↔ mpac-pgw

Header: Authorization: HMAC-SHA256 <client_id>:<timestamp>:<signature>

Signature Calculation:
  message = HTTP_METHOD + ":" + REQUEST_PATH + ":" + timestamp + ":" + request_body
  signature = HMAC-SHA256(message, secret_key)
  signature_base64 = Base64(signature)

Used for:
- POST /v1/payment_intents (create)
- GET /v1/payment_intents (list)
- POST /v1/payment_intents/{id}/capture (capture)
- POST /v1/sync/merchants (sync config)

2. payment_token (Frontend/SDK)

Used by: WebView SDK ↔ mpac-pgw

Header: Authorization: Bearer <payment_token>

Token is payment-specific, short-lived
Issued when PaymentIntent created

Used for:
- GET /v1/payment_intents/{id} (retrieve)
- POST /v1/payment_intents/{id}/confirm (confirm)
- POST /v1/payment_intents/{id}/cancel (cancel)
- GET /v1/payment_intents/{id}/transactions (list txns)

---

Provider Integration

Provider Adapter Pattern

type QRProvider interface {
    Name() string
    CreateQR(ctx, credentials, request) (*QRResponse, error)
    GetPaymentStatus(ctx, credentials, providerRefID) (*StatusResponse, error)
    CancelPayment(ctx, credentials, providerRefID) error
    RefundPayment(ctx, credentials, providerRefID, amount) error
}

Current Providers

• PayPay - Implemented (MPM/CPM)
• LINE Pay - Planned
• Rakuten Pay - Planned
• au PAY - Planned

Provider Configuration

{
  "store_id": 2,
  "provider_code": "paypay",
  "credentials": {
    "merchant_id": "PAYPAY-MERCHANT-123",
    "api_key": "encrypted_api_key",
    "api_secret": "encrypted_secret"
  },
  "is_active": true
}

Webhook Handling

Provider (PayPay) sends webhook
  └─ POST /v1/webhooks/paypay
     Headers: X-PayPay-Signature: <hmac>
     Body: {transaction_id, status, amount, ...}

PGW validates signature
  └─ Lookup PaymentIntent by provider_transaction_id
  └─ Update status based on provider status
  └─ Emit event for svc-smarttab to poll

---

Multi-Tenant Configuration Sync

Purpose: Keep PGW in sync with merchant/store/payment configuration from svc-portal.

Sync Flow

svc-portal (source of truth)
  └─ Merchant/Store/Config changes
  └─ POST /v1/sync/merchants (HMAC auth)
     Body: {
       "client_partner_id": 1,
       "merchants": [
         {
           "merchant_id": 1,
           "merchant_code": "MERCHANT-ABC",
           "stores": [
             {
               "store_id": 2,
               "store_code": "STORE-001",
               "provider_configs": [
                 {
                   "provider_code": "paypay",
                   "credentials": {...},
                   "is_active": true
                 }
               ]
             }
           ]
         }
       ]
     }

PGW receives sync
  └─ Upsert merchants table
  └─ Upsert stores table
  └─ Upsert store_provider_configs table
  └─ Return: {synced_merchants: 1, synced_stores: 1}

Sync Frequency

• On-demand when config changes
• Periodic sync every 15 minutes (fallback)

---

Rate Limiting

Purpose: Protect payment providers and system from abuse.

Rate Limits

• Per Merchant: 1,000 requests/minute
• Per Store: 500 requests/minute
• Global: 10,000 requests/minute
• Per IP: 100 requests/minute

Implementation

• Redis-based sliding window counter
• Returns 429 Too Many Requests when exceeded
• Response header: X-RateLimit-Remaining, X-RateLimit-Reset

---

API Endpoints Summary

Method	Endpoint	Auth	Purpose
POST	/v1/payment_intents	HMAC	Create PaymentIntent (S2S)
GET	/v1/payment_intents	HMAC	List PaymentIntents (S2S)
GET	/v1/payment_intents/{id}	Token	Retrieve PaymentIntent (SDK)
POST	/v1/payment_intents/{id}/confirm	Token	Confirm payment (SDK)
POST	/v1/payment_intents/{id}/cancel	Token	Cancel payment (SDK)
POST	/v1/payment_intents/{id}/capture	HMAC	Capture external/manual (S2S)
POST	/v1/payment_intents/{id}/refund	HMAC	Refund payment (S2S)
GET	/v1/payment_intents/{id}/transactions	Token	List transactions (SDK)
GET	/v1/transactions/{id}	HMAC	Transaction details (S2S)
POST	/v1/sync/merchants	HMAC	Sync merchant config (S2S)
POST	/v1/webhooks/{provider}	Signature	Provider webhooks

---

See Also

Related Domains:

• Payment Processing - Order management and payment flows
• Settlement - Transaction reconciliation and financial settlement
• External Systems - Integration with payment providers

Technical Implementation:

• Security Architecture - HMAC authentication and webhook validation
• Database Architecture - PaymentIntent and transaction data models

API Reference:

• API Endpoints - Complete API specification for payment gateway endpoints

---

Navigation: ↑ Back to Domain Catalog | ← Previous: IAM | Next: Payment Processing →