FAQ & Troubleshooting

General

What does MPAC stand for?

MP-Solution Advanced Cloud Service. It is the cloud platform powering S-Pitt (Smart Parallel Intelligent Transaction Tool) payment terminals.

What is the difference between mpac-smartpos and mpac-pgw?

mpac-smartpos is the core platform handling portal UI, terminal management, orders, and business logic. mpac-pgw is the dedicated payment gateway handling PaymentIntent lifecycle, provider integrations, and transaction processing. They run in separate VPCs and communicate over HTTPS.

Which environment should I use for testing?

Use the dev environment (mpac-cloud-dev.com). Each environment is isolated in a separate AWS account:

• Dev: api.pgw.mpac-cloud-dev.com
• Staging: api.pgw.mpac-cloud-stg.com
• Production: api.pgw.mpac-cloud.com

---

Payment Gateway

How does authentication work?

Two authentication methods:

• Server-to-server: HMAC-SHA256 signature in the Authorization header. The signing key is the byte representation of the hex-encoded SHA-256 of your secret key.
• Client/SDK: Use the payment_token returned when creating a PaymentIntent.

See API Authentication Guide for implementation details.

What are the three processing modes?

Mode	Use Case	Flow
pgw_processed	QR code payments	Terminal → PGW → Provider API → QR code → Customer pays
external	Credit card payments	Terminal → External card app → PGW records result
manual	Cash payments	Terminal → PGW records cash amount

Why is my PaymentIntent stuck in requires_action?

Common causes:

1. QR code expired — the provider's QR code has a TTL. Create a new PaymentIntent.
2. Provider API unreachable — check provider status and store credentials in StoreProviderConfig.
3. Missing polling — the SDK or terminal must poll for status updates or listen to webhooks.

What is idempotency and how do I use it?

Send an Idempotency-Key header with a unique value (e.g., ULID) on POST requests. If the same key is sent again within 24 hours, PGW returns the original response without re-processing. This prevents duplicate payments on retries.

---

SDKs

Which SDK should I use?

SDK	Use Case
JavaScript/TypeScript	Web applications, Node.js backends
Go	Go microservices, server-side integrations
Python	Python backends, scripts, data pipelines

How do I test without a real payment provider?

Use the dev environment with test credentials. The PGW supports manual processing mode for testing payment flows without connecting to a real provider.

---

Infrastructure

Why are VPCs isolated (no peering)?

Each system (smartpos, pgw, obs) runs in its own VPC to enforce security boundaries. Communication happens over public HTTPS endpoints with authentication, making each system independently deployable and auditable.

How do I access the database in a non-local environment?

Use the SSH tunnel via bastion host. See SSH Tunnel & Bastion for step-by-step instructions.

How do I check if my deployment succeeded?

cd mpac-infra
make status    # Shows CloudFormation stack status

Or check the CI/CD pipeline in GitHub Actions.

---

Observability

Where do I view logs and traces?

Open Grafana at grafana.obs.mpac-cloud-dev.com (dev environment). Use:

• Loki for log queries
• Tempo for distributed traces
• Prometheus for metrics and alerts

All telemetry is correlated via trace_id and service labels.

How do I instrument my service?

Send OTLP data to Alloy:

• gRPC: otlp.obs.mpac-cloud-dev.com:4317
• HTTP: otlp.obs.mpac-cloud-dev.com:4318

See Observability Onboarding for setup details.