Payment API

Go REST API — idempotent payment service.

---

Quick Start

cp .env.example .env   
make quick-start       # starts containers + runs migrations automatically

---

System Design

Architecture, request flow, payment flow, and design decisions: docs/SYSTEM_DESIGN_SHORT.md

---

Prerequisites

• Go 1.24+
• Docker + Docker Compose
• air (local dev only)

go install github.com/air-verse/air@latest

---

Setup

cp .env.example .env
# edit .env — set DATABASE_PASSWORD at minimum

---

Run

Docker (recommended)

make up        # start all containers (app + db + redis)
make down      # stop containers
make logs      # tail app logs

Local with hot-reload

make dev       # loads .env and runs air

---

Migrations

make migrate-up                        # apply pending migrations
make migrate-down                      # rollback last migration
make migrate-down STEPS=3              # rollback N migrations
make migrate-status                    # current version
make migrate-create NAME=add_orders    # create new migration files
make migrate-goto VERSION=5            # jump to specific version
make migrate-force VERSION=5           # force version (dirty state recovery)

---

Test & Lint

make test               # run all tests
make test-coverage      # run tests + generate coverage.html
make lint               # run golangci-lint
make lint-fix           # run golangci-lint with auto-fix

---

Swagger

make swag   # regenerate docs (available at /swagger/index.html in non-production)

---

Build

make build-binary   # build ./bin/server binary
make run-binary     # build + run binary

---

Endpoints

Method	Path	Description
POST	/api/v1/pay	Submit idempotent payment
GET	/health	Health check
GET	/metrics	Prometheus metrics
GET	/swagger/*	Swagger UI (non-production)

---

Config

All settings have defaults in configs/config.yaml. Override via .env or environment variables. See configs/config.yaml for the full list.