Wallet Disbursement API

A Go-based API for wallet balance disbursements designed for the Indonesian market. This project implements a simple, yet robust system that allows users to withdraw funds from their wallet to bank accounts or e-wallets.

Features

• IDR (Indonesian Rupiah) currency support
• Multiple disbursement methods:
  • Bank transfers (BCA, Mandiri, BNI, BRI, etc.)
  • E-wallets (GoPay, OVO, DANA, LinkAja, ShopeePay)
• Transaction fee calculation based on disbursement method
• Comprehensive validation including:
  • Minimum withdrawal amount (Rp 10,000)
  • Maximum withdrawal amount (Rp 50,000,000)
  • Sufficient balance checks
• Transaction reference ID generation
• PostgreSQL database for data persistence

Technology Stack

• Language: Go (Golang)
• Database: PostgreSQL
• External packages:
  • github.com/google/uuid - For generating unique reference IDs
  • github.com/lib/pq - PostgreSQL driver

Setup Instructions

Prerequisites

• Go 1.16 or higher
• PostgreSQL 12 or higher
• Docker (optional, for containerized database)

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/wallet-disbursement-api.git
   cd wallet-disbursement-api

2. Initialize Go module (if starting from scratch):

   go mod init wallet-disbursement-api

3. Install dependencies:

   go get github.com/lib/pq
   go get github.com/google/uuid

Database Setup

Using Docker:

1. Start PostgreSQL container:

   docker run --name postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_USER=postgres -e POSTGRES_DB=wallet_db -p 5432:5432 -d postgres:14

2. Run migrations:

   # Copy migrations to container
   docker cp internal/database/migrations/001_initial_schema.sql postgres:/tmp/
   
   # Execute migrations
   docker exec postgres psql -U postgres -d wallet_db -f /tmp/001_initial_schema.sql

Using Local PostgreSQL:

1. Create database:

   psql -U postgres -c "CREATE DATABASE wallet_db;"

2. Run migrations:

   psql -U postgres -d wallet_db -f internal/database/migrations/001_initial_schema.sql

Running the Application

1. Build and run:

   go build -o wallet-api ./cmd/api
   ./wallet-api

   Or use go run:

   go run cmd/api/main.go

2. The API will be available at: http://localhost:8080

API Documentation

Disbursement Endpoint

Endpoint: POST /api/disbursements

Request Body:

{
  "user_id": 1,
  "amount": 1000000.00,
  "disbursement_method_id": 1,
  "description": "Penarikan ke rekening BCA"
}

Parameters:

• user_id (required): ID of the user requesting disbursement
• amount (required): Amount to withdraw in IDR
• disbursement_method_id (optional): ID of the disbursement method to use
• description (optional): Transaction description

Success Response (200 OK):

{
  "success": true,
  "reference_id": "fb8e642c-6a9d-4b5c-8749-e7dda4f76326",
  "amount": 1000000.00,
  "currency": "IDR",
  "status": "processing",
  "fee": 6500.00,
  "remaining_balance": 8993500.00,
  "method": "bank_transfer",
  "provider": "BCA",
  "account_number": "1234567890",
  "created_at": "2023-07-21T15:30:45Z"
}

Error Response (400 Bad Request):

{
  "success": false,
  "error": {
    "code": "insufficient_balance",
    "message": "Saldo dompet tidak mencukupi"
  }
}

Possible Error Codes:

• invalid_user_id: User ID is not a positive integer
• invalid_amount: Amount is not a positive number
• user_not_found: User does not exist
• wallet_not_found: Wallet does not exist for this user
• method_not_found: Disbursement method not found
• insufficient_balance: Wallet has insufficient balance
• minimum_amount: Amount is below minimum (Rp 10,000)
• maximum_amount: Amount exceeds maximum (Rp 50,000,000)
• daily_limit_exceeded: Daily withdrawal limit exceeded
• internal_error: An internal server error occurred

Database Schema

The database consists of the following tables:

users

• id: User identifier
• name: User's full name
• email: User's email address
• nik: National ID number (KTP)
• phone: Phone number
• created_at: Record creation timestamp
• updated_at: Record update timestamp

wallets

• id: Wallet identifier
• user_id: Reference to users.id
• balance: Current wallet balance
• currency: Currency code (IDR)
• created_at: Record creation timestamp
• updated_at: Record update timestamp

disbursement_methods

• id: Method identifier
• user_id: Reference to users.id
• type: Method type (bank_transfer or e_wallet)
• provider: Bank name or e-wallet provider
• account_number: Account number or identifier
• account_holder_name: Name of account holder
• bank_code: Bank code (for bank transfers)
• is_default: Whether this is the default method
• created_at: Record creation timestamp
• updated_at: Record update timestamp

disbursements

• id: Disbursement identifier
• reference_id: Unique reference ID for the transaction
• user_id: Reference to users.id
• wallet_id: Reference to wallets.id
• disbursement_method_id: Reference to disbursement_methods.id
• amount: Disbursement amount
• currency: Currency code (IDR)
• status: Transaction status (pending, processing, completed, failed)
• description: Transaction description
• fee: Transaction fee amount
• created_at: Record creation timestamp
• updated_at: Record update timestamp