01cloud Payments

01cloud-payments is a Go-based billing and payment service for managing payment gateways, invoices, transactions, thresholds, and billing workflows.

It is designed as a standalone HTTP service with PostgreSQL persistence and Swagger-powered API documentation, making it easier to integrate into a larger SaaS or platform stack.

Features

• Multi-gateway payment support with Stripe integration and helper utilities for PayPal and PayU
• Invoice, invoice-item, transaction, payment-history, and payment-setting APIs
• Promo-code and payment-threshold workflows
• Scheduled billing and payment reminder endpoints
• Swagger/OpenAPI docs served by the application
• Unit tests for controllers and models

Tech Stack

• Go
• Gin
• GORM
• PostgreSQL
• Swagger / Swaggo
• Docker

Quick Start

Prerequisites

• Go 1.15 or newer
• PostgreSQL
• Docker, if you want to use the containerized workflow

Local Setup

1. Clone the repository.
2. Create a local environment file:

cp .env.sample .env

3. Update the database and integration settings in .env.
4. Start the API locally:

make run-dev

The service runs on http://localhost:8080 by default.

Docker Build

Build the runtime image:

docker build -t 01cloud-payments .

Run the container:

docker run --rm -p 8080:8080 --env-file .env 01cloud-payments

Development

Run tests:

make test-dev

Run formatting and verification:

make format
make fmtcheck
make vet
make lint

Run the public CI-equivalent checks locally:

make ci

Configuration

Use .env.sample as the source of truth. Important variables include:

• DB_HOST, DB_PORT, DB_DRIVER, DB_USER, DB_PASSWORD, DB_NAME
• PAYMENT_API
• PAYMENT_SUCCESS_UI_URL, PAYMENT_FAILED_UI_URL
• EXCHANGE_RATES_API_KEY
• BASE_URL, API_SECRET
• INVOICE_PATH, EMAIL_TEMPLATE_PATH
• HOST_URL, EMAIL_LOGO_URL
• SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD, SMTP_FROM_ADDRESS

API Usage

Fetch exchange rates:

curl -X GET http://localhost:8080/payment/rates

Initialize a Stripe payment:

curl -X GET "http://localhost:8080/payment/init/stripe?amount=25" \
  -H "x-user-id: 1"

Swagger UI:

http://localhost:8080/payment/swagger/index.html

Project Structure

• cmd/server: application entrypoint and generated Swagger docs
• internal/controllers: HTTP handlers and route wiring
• internal/models: database models and persistence logic
• internal/util: config, email, and payment utility helpers
• pkg: shared response and formatting helpers

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening issues or pull requests.

Security

Please report vulnerabilities privately as described in SECURITY.md.

License

This project is currently licensed under Apache 2.0. See LICENSE.