mpac-pgw Developer Onboarding

One-time setup to work with the mpac-pgw repository and consume its SDKs.

---

1. Prerequisites

• Go 1.24+
• Node.js 20+ and pnpm 9+
• Python 3.11+ with uv
• Docker and Docker Compose
• GitHub Personal Access Token (PAT) — see step 2

---

2. GitHub PAT Setup (One-Time)

All SDKs are published to GitHub Packages (private, org-scoped). You need a GitHub PAT with read:packages scope.

Create a PAT:

1. Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Click "Generate new token (classic)"
3. Select scopes: read:packages, repo
4. Generate and copy the token — you won't see it again

Configure package managers:

# npm (for sdk-js in frontend projects)
echo "//npm.pkg.github.com/:_authToken=ghp_YOUR_TOKEN" >> ~/.npmrc

# Go (for sdk-go in server-to-server integrations)
echo "export GOPRIVATE=github.com/mp-solution-inc/*" >> ~/.zshrc
git config --global url."https://ghp_YOUR_TOKEN@github.com/".insteadOf "https://github.com/"

# Python (for sdk-python — reuses git config above, no extra setup needed)

Verify setup:

# Test npm auth
npm dist-tag ls @cloudsky/mpac-pgw-sdk-js --registry https://npm.pkg.github.com

# Test Go auth (after running: source ~/.zshrc)
GONOSUMCHECK=* go install github.com/mp-solution-inc/mpac-pgw/sdks/sdk-go@latest

---

3. Local Development Setup

# Clone the repo
git clone https://github.com/mp-solution-inc/mpac-pgw.git
cd mpac-pgw

# Start the full local stack (PGW + PostgreSQL + Redis)
make up

# In another terminal, apply migrations
make migrate

# Verify PGW is running
curl http://localhost:8080/health

Expected response: {"status":"ok","version":"..."}

---

4. Running Tests

# All tests (backend + all SDKs)
make test

# Individual components
make test-backend   # Go backend (requires local stack running)
make test-sdk-js    # JavaScript/TypeScript SDK
make test-sdk-go    # Go SDK
make test-sdk-py    # Python SDK

---

5. SDK Installation

JavaScript/TypeScript (browser/WebView)

# In the consuming project directory
echo "@cloudsky:registry=https://npm.pkg.github.com" > .npmrc
pnpm add @cloudsky/mpac-pgw-sdk-js

Go (server-to-server)

export GOPRIVATE=github.com/mp-solution-inc/*
go get github.com/mp-solution-inc/mpac-pgw/sdks/sdk-go@v1.0.0

Python (server-to-server)

# Option A: install from git tag (recommended)
uv pip install "mpac-pgw-sdk @ git+https://github.com/mp-solution-inc/mpac-pgw.git@sdks/sdk-python/v1.0.0#subdirectory=sdks/sdk-python"

# Option B: install from GitHub Releases wheel
uv pip install https://github.com/mp-solution-inc/mpac-pgw/releases/download/sdks-sdk-python-v1.0.0/mpac_pgw_sdk-1.0.0-py3-none-any.whl

---

6. Environment Variables

For local development with the pgw:

cp pgw/.env.example pgw/.env
# Edit .env with your local values

Key variables:

Variable	Description	Local Default
DB_HOST	PostgreSQL host	localhost
DB_PORT	PostgreSQL port	5433
DB_USER	DB username	pgw
DB_PASSWORD	DB password	pgw
DB_NAME	Database name	pgwdb
REDIS_HOST	Redis host	localhost
REDIS_PORT	Redis port	6380
API_KEY_SALT	HMAC key salt	any random string

---

7. Creating Test Credentials

For local testing with the HMAC SDK, create test API keys:

# Generate a test merchant with API key
curl -X POST http://localhost:8080/v1/internal/merchants \
  -H "Content-Type: application/json" \
  -d '{"merchant_id": "test-merchant", "store_id": "test-store"}'

# The response includes api_key and secret_key for HMAC auth

See docs/integration-guide.md for full authentication examples.

---

8. CI Authentication

GitHub Actions workflows within the mpac-pgw repo have automatic access to GITHUB_TOKEN. Cross-repo workflows (e.g., mpac-smartpos's sdk-compatibility check) use CROSS_REPO_TOKEN — an org-level secret that must be configured by an org admin.

Required org secrets (configure in org Settings → Secrets → Actions):

Secret	Scope	Description
CROSS_REPO_TOKEN	All repos	PAT with repo scope for repository_dispatch
AWS_ROLE_ARN_STAGING	mpac-pgw	OIDC role ARN for staging deploy
AWS_ROLE_ARN_PROD	mpac-pgw	OIDC role ARN for prod deploy

---

9. Useful Links

Resource	URL
API Reference	docs/api-reference.md
Integration Guide	docs/integration-guide.md
Provider Adapters	docs/provider-adapters.md
Infrastructure	mpac-infra/mpac-pgw/ in the mpac-infra repo
Grafana Dashboards	mpac-obs repo (once deployed)