API Reference & Usage

📡 API Reference & Usage

FlossPay exposes a secure, auditable, and contract-first API for payment operations.
This section deep-dives into endpoints, authentication, error handling, usage patterns, and best practices for integration.

---

🏁 Base Path

All endpoints are under /api/v1

---

📋 Endpoints

Method	Endpoint	Description	Auth Required	Idempotent	Typical Response
POST	/pay	Initiate a UPI push payment	Yes (HMAC)	Yes	200 OK / 400 / 409
POST	/collect	Initiate a UPI pull/collect request	Yes (HMAC)	Yes	202 / 400
GET	/transaction/{id}/status	Retrieve transaction status by ID	Yes (HMAC)	N/A	200 / 404
GET	/health	Liveness check	No	N/A	200
GET	/health/ready	Readiness check	No	N/A	200 / 503

---

🔐 Authentication & Idempotency

• Authentication:

  • All sensitive endpoints require HMAC-SHA256 signature.
  • Client signs canonical request, includes signature in X-HMAC header.

• Idempotency:

  • All POST endpoints require unique Idempotency-Key header (UUIDv4).
  • Ensures at-most-once execution, prevents double-processing.

---

📦 Example: Initiate Payment (/pay)

curl -X POST http://localhost:8080/api/v1/pay \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-key-280" \
  -H "X-HMAC: <your-signature-here>" \
  -d '{"senderUpi": "flossalice@upi", "receiverUpi": "flossbob@upi", "amount": 28.00}'