Payments Service

🌱 📄

A modern, production-ready Spring Boot microservice for managing payment processing, gateway integrations, and webhooks.

🌟 Table of Contents

Overview
Features
Setup Instructions
API Endpoints
Payments
Banks
Payloads & Field Explanations
Architecture
Testing
Troubleshooting
Contributing
License

📝 Overview

This service provides endpoints to: - Initiate payments via multiple gateways (e.g., Stripe) - Handle payment webhooks for status updates - List available payment gateways and their configurations - Manage banks (CRUD for global bank data)

🚀 Features

🔌 Multi-gateway support (Stripe, extensible for others)
🔒 Webhook handling with signature verification
♻️ Idempotent payment creation
💸 Wallet crediting on successful payment
📃 Paginated gateway listing
🏦 Bank CRUD API (global bank data, including logo)
🔗 OpenFeign for service-to-service communication
🐇 RabbitMQ integration for messaging
📊 Observability with Micrometer and Loki
🧩 Extensive DTOs and clear API contracts

⚡️ Setup Instructions

Prerequisites

☕️ Java 17 or later
🛠 Gradle (wrapper included)
🐳 Docker (for RabbitMQ and dependencies)

1. Clone the Repository

git clone https://github.com/olara-tech/payments-service-java.git
cd payments-service-java

2. Start Dependencies (RabbitMQ, etc.)

docker-compose -f docker-compose-payment-service-local.yml up -d

3. Configure Environment

Edit src/main/resources/application-local.yml or application-uat.yml as needed for your environment (DB, RabbitMQ, Stripe keys, etc).

4. Build the Project

./gradlew build

5. Run the Service

./gradlew bootRun

The service will start on http://localhost:10002 by default.

📚 API Endpoints

🛡️ Admin API Endpoints

1. Create Gateway

POST /api/v1/admin/gateways

Creates a new gateway configuration.

Request Body: CreateGatewayConfigDto

| Field | Type | Description | |---------------------|-----------|------------------------------------| | name | String | Gateway name | | isEnabled | Boolean | Whether gateway is enabled | | imageUrl | String | Logo URL for the gateway | | priority | Integer | Priority for selection | | webhookSecret | String | Webhook secret | | supportedCurrencies | List | Supported currency codes | | supportedMethods | List | Supported payment methods | | environment | String | Environment (e.g., production) | | credentials | Map | Extra credentials | | metadata | Map | Extra metadata |

Example Request

{
  "name": "stripe",
  "isEnabled": true,
  "imageUrl": "https://.../stripe.png",
  "priority": 1,
  "webhookSecret": "secret",
  "supportedCurrencies": ["USD", "NGN"],
  "supportedMethods": ["card"],
  "environment": "production",
  "credentials": {"accountId": "acct_..."},
  "metadata": {"priority": "1"}
}

Response: GatewayConfigDto

| Field | Type | Description | |---------------------|-----------|------------------------------------| | id | UUID | Gateway config ID | | name | String | Gateway name | | ... | ... | ... (same as request) |

Example Response

{
  "id": "uuid",
  "name": "stripe",
  "isEnabled": true,
  "imageUrl": "https://.../stripe.png",
  "priority": 1,
  "webhookSecret": "secret",
  "supportedCurrencies": ["USD", "NGN"],
  "supportedMethods": ["card"],
  "environment": "production",
  "credentials": {"accountId": "acct_..."},
  "metadata": {"priority": "1"}
}

2. Update Gateway

PUT /api/v1/admin/gateways/{id}

Updates an existing gateway configuration.

Request Body: CreateGatewayConfigDto

_Same as Create Gateway._

Response: GatewayConfigDto

_Same as Create Gateway response._

{
  "id": "a1b2c3d4-5678-1234-9abc-def012345678",
  "name": "stripe",
  "isEnabled": true,
  "imageUrl": "https://.../stripe.png",
  "priority": 1,
  "webhookSecret": "secret",
  "supportedCurrencies": ["USD", "NGN"],
  "supportedMethods": ["card"],
  "environment": "production",
  "credentials": {"accountId": "acct_..."},
  "metadata": {"priority": "1"},
  "created": "2025-06-02T10:00:00Z",
  "updated": "2025-06-02T10:00:00Z"
}

3. Delete Gateway

DELETE /api/v1/admin/gateways/{id}

Deletes a gateway configuration by its ID.

Response

- `204 No Content` (on success)

4. List Gateways

GET /api/v1/admin/gateways

Returns a paginated list of all gateway configurations (admin view).

Response: List of GatewayConfigDto

_Same as Create Gateway response, in a list._ [ { "id": "a1b2c3d4-5678-1234-9abc-def012345678", "name": "stripe", "isEnabled": true, "imageUrl": "https://.../stripe.png", "priority": 1, "webhookSecret": "secret", "supportedCurrencies": ["USD", "NGN"], "supportedMethods": ["card"], "environment": "production", "credentials": {"accountId": "acct_..."}, "metadata": {"priority": "1"}, "created": "2025-06-02T10:00:00Z", "updated": "2025-06-02T10:00:00Z" } ]

5. Get Gateway by ID

GET /api/v1/admin/gateways/{id}

Returns a single gateway configuration by its ID.

Response: GatewayConfigDto

_Same as Create Gateway response._

6. Create Bank

POST /api/v1/admin/banks

Creates a new bank record.

Request Body: CreateBankDto

| Field | Type | Description | |---------------|-----------|---------------------------------------------| | name | String | Bank name | | code | String | Bank code (unique, e.g., SWIFT, NUBAN, etc) | | country | String | Country code (ISO 3166-1 alpha-2, e.g., NG) | | currency | String | Currency code (e.g., NGN, USD, GBP) | | logoUrl | String | URL to the bank's logo | | swiftCode | String | SWIFT/BIC code (optional) | | routingNumber | String | Routing number (optional) | | sortCode | String | Sort code (optional) | | iban | String | IBAN (optional) | | address | String | Bank address (optional) | | metadata | Map | Additional metadata (optional) |

Example Request

{
  "name": "Guaranty Trust Bank",
  "code": "058",
  "country": "NG",
  "currency": "NGN",
  "logoUrl": "https://banks.ng/gtb.png",
  "swiftCode": "GTBINGLA",
  "routingNumber": null,
  "sortCode": null,
  "iban": null,
  "address": "635 Akin Adesola St, Victoria Island, Lagos",
  "metadata": {"tier": "1"}
}

Response: BankDto

| Field | Type | Description | |---------------|--------|---------------------------------------------| | id | UUID | Bank ID | | ... | ... | ... (same as request) |

Example Response

{
  "id": "uuid",
  "name": "Guaranty Trust Bank",
  "code": "058",
  "country": "NG",
  "currency": "NGN",
  "logoUrl": "https://banks.ng/gtb.png",
  "swiftCode": "GTBINGLA",
  "routingNumber": null,
  "sortCode": null,
  "iban": null,
  "address": "635 Akin Adesola St, Victoria Island, Lagos",
  "metadata": {"tier": "1"},
  "created": "2025-06-02T10:00:00Z",
  "updated": "2025-06-02T10:00:00Z"
}

7. Update Bank

PUT /api/v1/admin/banks/{id}

Updates an existing bank record.

Request Body: BankDto

_Same as Create Bank._

Response: BankDto

_Same as Create Bank response._

{
  "id": "b2c3d4e5-6789-1234-9abc-def012345678",
  "name": "Guaranty Trust Bank",
  "code": "058",
  "country": "NG",
  "currency": "NGN",
  "logoUrl": "https://banks.ng/gtb.png",
  "swiftCode": "GTBINGLA",
  "routingNumber": null,
  "sortCode": null,
  "iban": null,
  "address": "635 Akin Adesola St, Victoria Island, Lagos",
  "metadata": {"tier": "1"},
  "created": "2025-06-02T10:00:00Z",
  "updated": "2025-06-02T10:00:00Z"
}

8. Delete Bank

DELETE /api/v1/admin/banks/{id}

Deletes a bank record by its ID.

Response

- `204 No Content` (on success)

9. List Banks

GET /api/v1/admin/banks

Returns a paginated list of all banks (admin view).

Response: List of BankDto

_Same as Create Bank response, in a list._ [ { "id": "b2c3d4e5-6789-1234-9abc-def012345678", "name": "Guaranty Trust Bank", "code": "058", "country": "NG", "currency": "NGN", "logoUrl": "https://banks.ng/gtb.png", "swiftCode": "GTBINGLA", "routingNumber": null, "sortCode": null, "iban": null, "address": "635 Akin Adesola St, Victoria Island, Lagos", "metadata": {"tier": "1"}, "created": "2025-06-02T10:00:00Z", "updated": "2025-06-02T10:00:00Z" } ]

10. Get Bank by ID

GET /api/v1/admin/banks/{id}

Returns a single bank record by its ID.

Response: BankDto

_Same as Create Bank response._

{
  "id": "b2c3d4e5-6789-1234-9abc-def012345678",
  "name": "Guaranty Trust Bank",
  "code": "058",
  "country": "NG",
  "currency": "NGN",
  "logoUrl": "https://banks.ng/gtb.png",
  "swiftCode": "GTBINGLA",
  "routingNumber": null,
  "sortCode": null,
  "iban": null,
  "address": "635 Akin Adesola St, Victoria Island, Lagos",
  "metadata": {"tier": "1"},
  "created": "2025-06-02T10:00:00Z",
  "updated": "2025-06-02T10:00:00Z"
}

11. List Payments

GET /api/v1/admin/payments

Returns a paginated list of payments for a user (admin view, filter via PaymentFilterDto).

Request Body: PaymentFilterDto

| Field | Type | Description | |---------------|-----------|---------------------------------------------| | status | String | Payment status (optional) | | method | String | Payment method (optional) | | currency | String | Currency code (optional) | | ... | ... | ... |

Response: List of PaymentDto

_See PaymentDto fields below._

{
  "id": "p1q2r3s4-5678-1234-9abc-def012345678",
  "tenantId": "t1u2v3w4-5678-1234-9abc-def012345678",
  "userId": "u1v2w3x4-5678-1234-9abc-def012345678",
  "walletId": "w1x2y3z4-5678-1234-9abc-def012345678",
  "reference": "unique-ref-123",
  "gatewayReference": "gw-ref-abc",
  "gatewayName": "stripe",
  "amount": 100.00,
  "currency": "USD",
  "status": "succeeded",
  "paymentMethod": "card",
  "description": "Payment for order #123",
  "metadata": {"orderId": "123"},
  "created": "2025-06-02T10:00:00Z",
  "updated": "2025-06-02T10:05:00Z"
}

{
  "id": "p1q2r3s4-5678-1234-9abc-def012345678",
  "tenantId": "t1u2v3w4-5678-1234-9abc-def012345678",
  "userId": "u1v2w3x4-5678-1234-9abc-def012345678",
  "walletId": "w1x2y3z4-5678-1234-9abc-def012345678",
  "reference": "unique-ref-123",
  "gatewayReference": "gw-ref-abc",
  "gatewayName": "stripe",
  "amount": 100.00,
  "currency": "USD",
  "status": "succeeded",
  "paymentMethod": "card",
  "description": "Payment for order #123",
  "metadata": {"orderId": "123"},
  "created": "2025-06-02T10:00:00Z",
  "updated": "2025-06-02T10:05:00Z"
}

{
  "id": "p1q2r3s4-5678-1234-9abc-def012345678",
  "tenantId": "t1u2v3w4-5678-1234-9abc-def012345678",
  "userId": "u1v2w3x4-5678-1234-9abc-def012345678",
  "walletId": "w1x2y3z4-5678-1234-9abc-def012345678",
  "reference": "unique-ref-123",
  "gatewayReference": "gw-ref-abc",
  "gatewayName": "stripe",
  "amount": 100.00,
  "currency": "USD",
  "status": "succeeded",
  "paymentMethod": "card",
  "description": "Payment for order #123",
  "metadata": {"orderId": "123"},
  "created": "2025-06-02T10:00:00Z",
  "updated": "2025-06-02T10:05:00Z"
}

{
  "id": "p1q2r3s4-5678-1234-9abc-def012345678",
  "tenantId": "t1u2v3w4-5678-1234-9abc-def012345678",
  "userId": "u1v2w3x4-5678-1234-9abc-def012345678",
  "walletId": "w1x2y3z4-5678-1234-9abc-def012345678",
  "reference": "unique-ref-123",
  "gatewayReference": "gw-ref-abc",
  "gatewayName": "stripe",
  "amount": 100.00,
  "currency": "USD",
  "status": "succeeded",
  "paymentMethod": "card",
  "description": "Payment for order #123",
  "metadata": {"orderId": "123"},
  "created": "2025-06-02T10:00:00Z",
  "updated": "2025-06-02T10:05:00Z"
}

{
  "id": "p1q2r3s4-5678-1234-9abc-def012345678",
  "tenantId": "t1u2v3w4-5678-1234-9abc-def012345678",
  "userId": "u1v2w3x4-5678-1234-9abc-def012345678",
  "walletId": "w1x2y3z4-5678-1234-9abc-def012345678",
  "reference": "unique-ref-123",
  "gatewayReference": "gw-ref-abc",
  "gatewayName": "stripe",
  "amount": 100.00,
  "currency": "USD",
  "status": "succeeded",
  "paymentMethod": "card",
  "description": "Payment for order #123",
  "metadata": {"orderId": "123"},
  "created": "2025-06-02T10:00:00Z",
  "updated": "2025-06-02T10:05:00Z"
}

{
  "id": "p1q2r3s4-5678-1234-9abc-def012345678",
  "tenantId": "t1u2v3w4-5678-1234-9abc-def012345678",
  "userId": "u1v2w3x4-5678-1234-9abc-def012345678",
  "walletId": "w1x2y3z4-5678-1234-9abc-def012345678",
  "reference": "unique-ref-123",
  "gatewayReference": "gw-ref-abc",
  "gatewayName": "stripe",
  "amount": 100.00,
  "currency": "USD",
  "status": "succeeded",
  "paymentMethod": "card",
  "description": "Payment for order #123",
  "metadata": {"orderId": "123"},
  "created": "2025-06-02T10:00:00Z",
  "updated": "2025-06-02T10:05:00Z"
}

12. Get Payment by Reference

GET /api/v1/admin/payments/by-reference/{reference}

Returns a payment by its reference (requires userId).

Response: PaymentDto

_See PaymentDto fields below._

13. Get Payment by ID

GET /api/v1/admin/payments/{id}

Returns payment details by ID (requires userId).

Response: PaymentDto

_See PaymentDto fields below._

Gateway Management (`/api/v1/admin/gateways`)

GET /api/v1/admin/gateways
List all gateway configs (search & pagination)
GET /api/v1/admin/gateways/{id}
Get gateway config by ID
POST /api/v1/admin/gateways
Create a new gateway config (CreateGatewayConfigDto payload)
PUT /api/v1/admin/gateways/{id}
Update gateway config (CreateGatewayConfigDto payload)
DELETE /api/v1/admin/gateways/{id}
Delete gateway config

Bank Management (`/api/v1/admin/banks`)

GET /api/v1/admin/banks
List all banks (search & pagination)
GET /api/v1/admin/banks/{id}
Get bank by ID
POST /api/v1/admin/banks
Create a new bank (CreateBankDto payload)
PUT /api/v1/admin/banks/{id}
Update bank (BankDto payload)
DELETE /api/v1/admin/banks/{id}
Delete bank

Payment Management (`/api/v1/admin/payments`)

GET /api/v1/admin/payments
List payments for a user (filter via PaymentFilterDto, pagination)
GET /api/v1/admin/payments/by-reference/{reference}
Get payment by reference (requires userId)
GET /api/v1/admin/payments/{id}
Get payment details by ID (requires userId)

Payments API

1. Create Payment

POST /api/v1/payments

Initiates a payment and returns a redirect URL for the payment gateway.

Request Body: PaymentRequest

| Field | Type | Description | |-----------------|-----------|------------------------------------| | tenantId | UUID | Tenant identifier | | userId | UUID | User identifier | | walletId | UUID | Wallet identifier | | reference | String | Unique payment reference | | gatewayName | String | Name of the payment gateway | | gatewayReference| String | Reference from the gateway | | amount | Decimal | Payment amount | | currency | String | Currency code (e.g., "USD") | | paymentMethod | String | Payment method (e.g., "card") | | description | String | Payment description | | idempotencyKey | String | Idempotency key for safe retries |

Example Request

{
  "tenantId": "uuid",
  "userId": "uuid",
  "walletId": "uuid",
  "reference": "unique-ref-123",
  "gatewayName": "stripe",
  "gatewayReference": null,
  "amount": 100.00,
  "currency": "USD",
  "paymentMethod": "card",
  "description": "Payment for order #123",
  "idempotencyKey": "idemp-key-xyz"
}

Response: PaymentInitResponse

| Field | Type | Description | |------------------|---------|---------------------------------------------| | paymentUrl | String | URL to redirect user to payment gateway | | gatewayReference | String | Reference from the payment gateway | | status | String | Status of the payment initiation |

Example Response

{
  "paymentUrl": "https://checkout.stripe.com/pay/cs_test_...",
  "gatewayReference": "gw-ref-abc",
  "status": "pending"
}

2. Payment Webhook

POST /api/v1/payments/webhooks/{gateway}

Handles webhook notifications from payment gateways.

Headers

| Name | Description | |---------------------|---------------------------| | Stripe-Signature | Signature for verification|

Example Request

POST /api/v1/payments/webhooks/stripe
Stripe-Signature: whsec_...

{ ...raw Stripe event payload... }

Response

204 No Content (on success)

3. List Payment Gateways

GET /api/v1/gateways

Returns a paginated list of enabled payment gateways, with flexible filtering by supported currencies and payment methods.

Query Parameters: - currencies (optional, List): Filter gateways supporting any of the provided currency codes (e.g. ?currencies=USD&currencies=NGN) - methods (optional, List): Filter gateways supporting any of the provided payment methods (e.g. ?methods=card&methods=bank_transfer)

Example Request:

GET /api/v1/gateways?currencies=USD&currencies=NGN&methods=card

Response: List of GatewayConfigDto

| Field | Type | Description | |----------------------|---------------------|---------------------------------------------| | id | UUID | Gateway config ID | | name | String | Gateway name | | description | String | Gateway description | | enabled | Boolean | Whether gateway is enabled | | priority | Integer | Priority for selection | | imageUrl | String | Logo URL for the gateway | | gatewayUrl | String | Gateway API URL | | apiKey | String | API key (masked in response) | | secretKey | String | Secret key (masked in response) | | webhookSecret | String | Webhook secret (masked in response) | | supportedCurrencies | List | Supported currency codes | | supportedMethods | List | Supported payment methods | | environment | String | Environment (e.g., production, sandbox) | | credentials | Map | Extra credentials | | metadata | Map | Extra metadata | | created | Instant | Created timestamp | | updated | Instant | Updated timestamp | | createdBy | String | Creator identifier | | updatedBy | String | Updater identifier |

Example Response

[
  {
    "id": "uuid",
    "name": "stripe",
    "description": "Stripe payment gateway",
    "isEnabled": true,
    "logoUrl": "https://.../stripe.png",
    "gatewayUrl": "https://api.stripe.com",
    "apiKey": "****",
    "secretKey": "****",
    "webhookSecret": "****",
    "supportedCurrencies": ["USD", "NGN"],
    "supportedMethods": ["card"],
    "environment": "production",
    "credentials": {"accountId": "acct_..."},
    "metadata": {"priority": "1"}
  }
]

Bank API

1. List Banks

GET /api/v1/banks

Returns a paginated list of banks. Supports optional search via q query param and pagination.

Query Parameters: - q (optional): Search query string - page (optional): Page number - size (optional): Page size (default: 10)

Response: Paginated List of BankDto

| Field | Type | Description | |---------------|--------|---------------------------------------------| | id | UUID | Bank ID | | name | String | Bank name | | code | String | Bank code | | country | String | Country code | | currency | String | Currency code | | logoUrl | String | URL to the bank's logo | | swiftCode | String | SWIFT/BIC code | | routingNumber | String | Routing number | | sortCode | String | Sort code | | iban | String | IBAN | | address | String | Bank address | | metadata | Map | Additional metadata | | created | Date | Created timestamp | | updated | Date | Updated timestamp |

Example Response

{
  "content": [
    {
      "id": "uuid",
      "name": "Guaranty Trust Bank",
      "code": "058",
      "country": "NG",
      "currency": "NGN",
      "logoUrl": "https://banks.ng/gtb.png",
      "swiftCode": "GTBINGLA",
      "routingNumber": null,
      "sortCode": null,
      "iban": null,
      "address": "635 Akin Adesola St, Victoria Island, Lagos",
      "metadata": {"tier": "1"},
      "created": "2025-06-02T10:00:00Z",
      "updated": "2025-06-02T10:00:00Z"
    }
  ],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 10
  },
  "totalElements": 1,
  "totalPages": 1
}

2. Get Bank by ID

GET /api/v1/banks/{id}

Returns a single bank record by its ID.

Response: BankDto

| Field | Type | Description | |---------------|--------|---------------------------------------------| | id | UUID | Bank ID | | name | String | Bank name | | code | String | Bank code | | country | String | Country code | | currency | String | Currency code | | logoUrl | String | URL to the bank's logo | | swiftCode | String | SWIFT/BIC code | | routingNumber | String | Routing number | | sortCode | String | Sort code | | iban | String | IBAN | | address | String | Bank address | | metadata | Map | Additional metadata | | created | Date | Created timestamp | | updated | Date | Updated timestamp |

Example Response

{
  "id": "uuid",
  "name": "Guaranty Trust Bank",
  "code": "058",
  "country": "NG",
  "currency": "NGN",
  "logoUrl": "https://banks.ng/gtb.png",
  "swiftCode": "GTBINGLA",
  "routingNumber": null,
  "sortCode": null,
  "iban": null,
  "address": "635 Akin Adesola St, Victoria Island, Lagos",
  "metadata": {"tier": "1"},
  "created": "2025-06-02T10:00:00Z",
  "updated": "2025-06-02T10:00:00Z"
}

📦 Payloads & Field Explanations

PaymentVerificationResponse

| Field | Type | Description | |------------------|---------|---------------------------------------------| | gatewayReference | String | Reference from the payment gateway | | paymentReference | String | Internal payment reference | | paymentStatus | String | Payment status (e.g., succeeded, failed) | | failureReason | String | Reason for failure (if any) | | isSignatureValid | Boolean | Whether the webhook signature is valid |

WebhookPayload

| Field | Type | Description | |------------------|---------|---------------------------------------------| | rawBody | String | Raw webhook payload | | signatureHeader | String | Signature header from gateway | | headers | Map | All headers | | gatewayName | String | Gateway name | | gatewayReference | String | Reference from the gateway |

PaymentDto

| Field | Type | Description | |------------------|---------|---------------------------------------------| | id | UUID | Payment ID | | tenantId | UUID | Tenant ID | | userId | UUID | User ID | | walletId | UUID | Wallet ID | | reference | String | System-generated payment reference | | gatewayReference | String | Reference from the payment gateway | | gatewayName | String | Gateway name | | amount | Decimal | Payment amount | | currency | String | Currency code | | status | String | Payment status | | paymentMethod | String | Payment method | | description | String | Description | | metadata | Map | Gateway-specific metadata | | created | Date | Created timestamp | | updated | Date | Updated timestamp |

BankDto

| Field | Type | Description | |---------------|--------|---------------------------------------------| | id | UUID | Bank ID | | name | String | Bank name | | code | String | Bank code | | country | String | Country code | | currency | String | Currency code | | logoUrl | String | URL to the bank's logo | | swiftCode | String | SWIFT/BIC code | | routingNumber | String | Routing number | | sortCode | String | Sort code | | iban | String | IBAN | | address | String | Bank address | | metadata | Map | Additional metadata | | created | Date | Created timestamp | | updated | Date | Updated timestamp |

CreateBankDto

| Field | Type | Description | |---------------|--------|---------------------------------------------| | name | String | Bank name | | code | String | Bank code (unique, e.g., SWIFT, NUBAN, etc) | | country | String | Country code (ISO 3166-1 alpha-2, e.g., NG) | | currency | String | Currency code (e.g., NGN, USD, GBP) | | logoUrl | String | URL to the bank's logo | | swiftCode | String | SWIFT/BIC code (optional) | | routingNumber | String | Routing number (optional) | | sortCode | String | Sort code (optional) | | iban | String | IBAN (optional) | | address | String | Bank address (optional) | | metadata | Map | Additional metadata (optional) |

🏗 Architecture

Spring Boot for REST APIs
JPA/Hibernate for persistence
RabbitMQ for messaging
OpenFeign for service-to-service calls
Lombok for boilerplate reduction
Micrometer & Loki for observability

🖇️ Payment Flow Sequence Diagram

sequenceDiagram
    participant Client
    participant PaymentService
    participant Gateway (e.g. Stripe)
    participant WalletService

    Client->>PaymentService: POST /api/v1/payments (PaymentRequest)
    PaymentService->>Gateway: Initiate payment (API call)
    Gateway-->>PaymentService: Payment URL, gatewayReference
    PaymentService-->>Client: PaymentInitResponse (paymentUrl)
    Client->>Gateway: Complete payment (redirect)
    Gateway-->>PaymentService: Webhook (payment status)
    PaymentService->>WalletService: Credit wallet (if succeeded)
    WalletService-->>PaymentService: Transaction result
    PaymentService-->>Gateway: 204 No Content (webhook ack)

Hold "Alt" / "Option" to enable pan & zoom

🧪 Testing

Run all tests:

./gradlew test

Test reports are generated in build/reports/tests/test/index.html.

🛠 Troubleshooting

Port already in use: Change the server.port in your environment config.
Database connection issues: Ensure your DB is running and credentials are correct in your environment config.
RabbitMQ not connecting: Check Docker container status and credentials.
Gradle issues: Run ./gradlew clean build to clear caches.

🤝 Contributing

Fork the repo
Create a feature branch
Commit your changes
Open a pull request

📄 License

MIT

Payments Service

🌟 Table of Contents

📝 Overview

🚀 Features

⚡️ Setup Instructions

Prerequisites

1. Clone the Repository

2. Start Dependencies (RabbitMQ, etc.)

3. Configure Environment

4. Build the Project

5. Run the Service

📚 API Endpoints

🛡️ Admin API Endpoints

1. Create Gateway

2. Update Gateway

3. Delete Gateway

4. List Gateways

5. Get Gateway by ID

6. Create Bank

7. Update Bank

8. Delete Bank

9. List Banks

10. Get Bank by ID

11. List Payments

12. Get Payment by Reference

13. Get Payment by ID

Gateway Management (/api/v1/admin/gateways)

Bank Management (/api/v1/admin/banks)

Payment Management (/api/v1/admin/payments)

Payments API

1. Create Payment

2. Payment Webhook

Response

3. List Payment Gateways

Bank API

1. List Banks

2. Get Bank by ID

📦 Payloads & Field Explanations

🏗 Architecture

🖇️ Payment Flow Sequence Diagram

🧪 Testing

🛠 Troubleshooting

🤝 Contributing

📄 License

Gateway Management (`/api/v1/admin/gateways`)

Bank Management (`/api/v1/admin/banks`)

Payment Management (`/api/v1/admin/payments`)