Skip to content

Payment Service API

💰

A comprehensive payment processing REST API built with Java, Spring Boot, and PostgreSQL. Integrates with payment gateways, manages transactions, settlements, and financial reconciliation.

Features

Feature Description Icon
Payment Gateway Integration Support for Stripe, PayPal, Square, and local payment providers 💳
Transaction Management Create, track, and manage payment transactions 📊
Settlement Processing Automated settlement and payout management 🏦
Refund Management Process and track refunds with detailed audit trail ↩️
Fraud Detection Built-in fraud prevention and anomaly detection 🛡️
Multi-Currency Support Handle transactions in multiple currencies 💱
Multi-Tenant Support Isolate payments per tenant 🏢

Architecture Overview

flowchart TD
    A[Client] -->|REST API| B(PaymentController)
    B --> C[PaymentService]
    C --> D[GatewayService]
    C --> E[TransactionService]
    D --> F[PaymentGateway]
    E --> G[TransactionRepository]
    G --> H[(PostgreSQL)]
    C --> I[FraudDetection]
    C --> J[SettlementService]
Hold "Alt" / "Option" to enable pan & zoom

API Endpoints

Note: Real API endpoints to be provided and included here.

Method Endpoint Description Notes/Parameters
POST /api/v1/payments/charge Create payment charge tenantId header, amount, card info
GET /api/v1/payments/{transactionId} Get payment details
POST /api/v1/payments/{transactionId}/refund Refund transaction Refund amount, reason
POST /api/v1/settlements Create settlement Date range, accounts

Sequence: Process Payment

sequenceDiagram
    participant U as User
    participant API as PaymentController
    participant P as PaymentService
    participant G as GatewayService
    participant F as PaymentGateway
    participant T as TransactionRepository
    U->>API: POST /payments/charge (amount, card)
    API->>P: validate payment
    P->>G: send to gateway
    G->>F: authorize with provider
    F-->>G: authorization response
    G-->>P: transaction result
    P->>T: save transaction
    T-->>P: saved
    P-->>API: PaymentResponse
    API-->>U: 201 Created + transaction details
Hold "Alt" / "Option" to enable pan & zoom

Database Schema

erDiagram
    transactions {
        UUID id PK
        UUID tenant_id
        DECIMAL amount
        VARCHAR currency
        VARCHAR payment_status
        VARCHAR payment_method
        VARCHAR gateway_reference
        VARCHAR merchant_reference
        TIMESTAMP created
        TIMESTAMP updated
    }

    refunds {
        UUID id PK
        UUID transaction_id FK
        DECIMAL refund_amount
        VARCHAR refund_status
        VARCHAR refund_reason
        TIMESTAMP created
        TIMESTAMP updated
    }

    settlements {
        UUID id PK
        UUID tenant_id
        DECIMAL settlement_amount
        VARCHAR settlement_status
        DATE settlement_date
        TIMESTAMP created
        TIMESTAMP updated
    }

    payment_methods {
        UUID id PK
        UUID tenant_id
        VARCHAR method_type
        VARCHAR provider
        VARCHAR account_token
        BOOLEAN active
        TIMESTAMP created
    }

    transactions ||--o{ refunds : "has"
    payment_methods ||--o{ transactions : "used_in"
Hold "Alt" / "Option" to enable pan & zoom

Getting Started

Prerequisites

  • Java 17+
  • PostgreSQL
  • Gradle

Setup

git clone https://github.com/Olanna-tech/payment-service-java.git
cd payment-service-java
./gradlew build

Database

  • Configure your PostgreSQL credentials in src/main/resources/application.yml.
  • Run Flyway migrations (auto on startup).

Run

./gradlew bootRun

Configuration

Set the following environment variables in application.yml: 

payment:
  default-gateway: stripe
  stripe-api-key: sk_live_xxxx
  paypal-client-id: xxxx
  settlement-batch-size: 100
  fraud-detection-enabled: true
  webhook-signature-verify: true

Contributing

Pull requests are welcome! For major changes, please open an issue first.

License

MIT

Contact