Skip to content

Commit b1e3e91

Browse files
malwarebomalwarebo
committed
chore: cleanup and organize docs
1 parent dc6a57c commit b1e3e91

3 files changed

Lines changed: 380 additions & 349 deletions

File tree

‎README.md‎

Lines changed: 16 additions & 349 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,9 @@ GRANT ALL PRIVILEGES ON DATABASE conductor TO conductor_user;
4444
psql -U conductor_user -d conductor -f config/db/schema.sql
4545
```
4646

47+
> [!TIP]
48+
> Want to automate the database setup? See the [Development Guide](docs/DEVELOPMENT.md#database-setup-script) for a handy script.
49+
4750
### 3. Configure the app
4851

4952
**Option 1: Using Environment Variables (Recommended for Production)**
@@ -81,56 +84,6 @@ cp config/config.example.json config/config.json
8184

8285
**⚠️ Security Note**: For production deployments, it is advised to use environment variables for API keys and database passwords.
8386

84-
## Database Setup Script
85-
86-
Want to automate the database setup? Here's a handy script in `/scripts`:
87-
88-
```bash
89-
#!/bin/bash
90-
91-
set -e
92-
93-
DB_NAME="conductor"
94-
DB_USER="conductor_user"
95-
DB_PASSWORD="your_password_here"
96-
97-
echo "Creating database and user..."
98-
if sudo -u postgres psql << EOF
99-
CREATE DATABASE $DB_NAME;
100-
CREATE USER $DB_USER WITH PASSWORD '$DB_PASSWORD';
101-
GRANT ALL PRIVILEGES ON DATABASE $DB_NAME TO $DB_USER;
102-
EOF
103-
then
104-
echo "Database and user created successfully"
105-
else
106-
echo "Failed to create database and user"
107-
exit 1
108-
fi
109-
110-
echo ""
111-
echo "Running schema migration..."
112-
if psql -U $DB_USER -d $DB_NAME -f config/db/schema.sql 2>&1 | tee /tmp/schema_output.log | grep -q "ERROR"; then
113-
echo ""
114-
echo "Schema migration failed with errors:"
115-
grep "ERROR" /tmp/schema_output.log
116-
rm -f /tmp/schema_output.log
117-
exit 1
118-
else
119-
echo "Schema migration completed successfully"
120-
rm -f /tmp/schema_output.log
121-
fi
122-
123-
echo ""
124-
echo "Database setup complete!"
125-
```
126-
127-
Make it executable and run:
128-
129-
```bash
130-
chmod +x setup_db.sh
131-
./setup_db.sh
132-
```
133-
13487
## Running the App
13588

13689
Start the server:
@@ -169,46 +122,6 @@ docker-compose up --build
169122

170123
The app will be available at `http://localhost:8080`
171124

172-
## API Endpoints
173-
174-
Note: This section need to be migrated to it is own separate page.
175-
176-
### Payments
177-
178-
- `POST /v1/charges` - Create a new charge
179-
- `POST /v1/refunds` - Create a refund
180-
181-
### Subscriptions
182-
183-
- `POST /v1/plans` - Create a subscription plan
184-
- `GET /v1/plans` - List all plans
185-
- `GET /v1/plans/:id` - Get plan details
186-
- `PUT /v1/plans/:id` - Update plan
187-
- `DELETE /v1/plans/:id` - Delete plan
188-
- `POST /v1/subscriptions` - Create a subscription
189-
- `GET /v1/subscriptions` - List subscriptions (requires customer_id parameter)
190-
- `GET /v1/subscriptions/:id` - Get subscription details
191-
- `PUT /v1/subscriptions/:id` - Update subscription
192-
- `DELETE /v1/subscriptions/:id` - Cancel subscription
193-
194-
### Disputes
195-
196-
- `POST /v1/disputes` - Create a dispute
197-
- `GET /v1/disputes` - List disputes (requires customer_id parameter)
198-
- `GET /v1/disputes/:id` - Get dispute details
199-
- `PUT /v1/disputes/:id` - Update dispute
200-
- `POST /v1/disputes/:id/evidence` - Submit evidence
201-
- `GET /v1/disputes/stats` - Get dispute statistics
202-
203-
### Fraud Detection
204-
205-
- `POST /v1/fraud/analyze` - Analyze transaction for fraud risk
206-
- `GET /v1/fraud/stats` - Get fraud detection statistics
207-
208-
### System
209-
210-
- `GET /v1/health` - Health check
211-
212125
## Authentication
213126

214127
All API endpoints (except health check) require authentication using an API key. You can provide the API key in two ways:
@@ -227,203 +140,6 @@ All API endpoints (except health check) require authentication using an API key.
227140

228141
**Note**: Replace `your_api_key_here` with your actual API key. For development, you can use any string with at least 10 characters.
229142

230-
## API Examples
231-
232-
Here are some real examples of how to use the API. The system automatically routes your requests to the right payment provider based on the currency!
233-
234-
### Creating Charges
235-
236-
#### Basic charge with Stripe (USD)
237-
238-
```bash
239-
curl -X POST http://localhost:8080/v1/charges \
240-
-H "Content-Type: application/json" \
241-
-H "X-API-Key: your_api_key_here" \
242-
-d '{
243-
"customer_id": "cus_123456789",
244-
"amount": 2500,
245-
"currency": "USD",
246-
"payment_method": "pm_123456789",
247-
"description": "Payment for order #12345"
248-
}'
249-
```
250-
251-
#### Charge with metadata using Xendit (IDR)
252-
253-
```bash
254-
curl -X POST http://localhost:8080/v1/charges \
255-
-H "Content-Type: application/json" \
256-
-H "X-API-Key: your_api_key_here" \
257-
-d '{
258-
"customer_id": "customer_123",
259-
"amount": 500000,
260-
"currency": "IDR",
261-
"payment_method": "pm_xendit_123",
262-
"description": "Premium subscription payment",
263-
"metadata": {
264-
"order_id": "ORD-2024-001",
265-
"user_id": "user_456",
266-
"product_type": "subscription",
267-
"billing_cycle": "monthly"
268-
}
269-
}'
270-
```
271-
272-
#### Charge using Razorpay (INR)
273-
274-
```bash
275-
curl -X POST http://localhost:8080/v1/charges \
276-
-H "Content-Type: application/json" \
277-
-H "X-API-Key: your_api_key_here" \
278-
-d '{
279-
"customer_id": "customer_india_123",
280-
"amount": 100000,
281-
"currency": "INR",
282-
"description": "Payment for order #67890",
283-
"metadata": {
284-
"order_id": "ORD-2024-IN-001",
285-
"payment_method_preference": "upi"
286-
}
287-
}'
288-
```
289-
290-
Note: Razorpay uses an Order → Payment flow. The response will include `requires_action: true` with the order ID in `client_secret`. Use Razorpay.js on the frontend to complete the payment.
291-
292-
#### High-value charge with Stripe (EUR)
293-
294-
```bash
295-
curl -X POST http://localhost:8080/v1/charges \
296-
-H "Content-Type: application/json" \
297-
-d '{
298-
"customer_id": "cus_europe_789",
299-
"amount": 9999,
300-
"currency": "EUR",
301-
"payment_method": "pm_europe_456",
302-
"description": "Annual enterprise license",
303-
"metadata": {
304-
"license_type": "enterprise",
305-
"duration": "annual",
306-
"seats": 100,
307-
"region": "EU"
308-
}
309-
}'
310-
```
311-
312-
### Creating Refunds
313-
314-
#### Simple refund
315-
316-
```bash
317-
curl -X POST http://localhost:8080/v1/refunds \
318-
-H "Content-Type: application/json" \
319-
-H "X-API-Key: your_api_key_here" \
320-
-d '{
321-
"payment_id": "ch_123456789",
322-
"amount": 2500,
323-
"currency": "USD",
324-
"reason": "Customer requested refund"
325-
}'
326-
```
327-
328-
#### Partial refund with metadata
329-
330-
```bash
331-
curl -X POST http://localhost:8080/v1/refunds \
332-
-H "Content-Type: application/json" \
333-
-d '{
334-
"payment_id": "ch_123456789",
335-
"amount": 1000,
336-
"currency": "USD",
337-
"reason": "Partial refund for damaged item",
338-
"metadata": {
339-
"refund_type": "partial",
340-
"damage_reported": true,
341-
"customer_service_agent": "agent_123"
342-
}
343-
}'
344-
```
345-
346-
### Managing Subscriptions
347-
348-
#### Create a subscription plan
349-
350-
```bash
351-
curl -X POST http://localhost:8080/v1/plans \
352-
-H "Content-Type: application/json" \
353-
-d '{
354-
"name": "Premium Plan",
355-
"description": "Premium features with priority support",
356-
"amount": 2999,
357-
"currency": "USD",
358-
"billing_period": "monthly",
359-
"pricing_type": "fixed",
360-
"trial_days": 7,
361-
"features": ["priority_support", "advanced_analytics", "api_access"]
362-
}'
363-
```
364-
365-
#### Create a subscription
366-
367-
```bash
368-
curl -X POST http://localhost:8080/v1/subscriptions \
369-
-H "Content-Type: application/json" \
370-
-d '{
371-
"customer_id": "cus_123456789",
372-
"plan_id": "plan_premium_001",
373-
"quantity": 1,
374-
"trial_days": 7,
375-
"payment_method_id": "pm_123456789",
376-
"metadata": {
377-
"marketing_source": "website",
378-
"referral_code": "WELCOME10"
379-
}
380-
}'
381-
```
382-
383-
### Handling Disputes
384-
385-
#### Create a dispute
386-
387-
```bash
388-
curl -X POST http://localhost:8080/v1/disputes \
389-
-H "Content-Type: application/json" \
390-
-d '{
391-
"customer_id": "cus_123456789",
392-
"transaction_id": "ch_123456789",
393-
"amount": 2500,
394-
"currency": "USD",
395-
"reason": "fraudulent",
396-
"evidence": {
397-
"customer_communication": "Customer claims unauthorized charge"
398-
},
399-
"due_by": "2024-02-15T23:59:59Z"
400-
}'
401-
```
402-
403-
#### Submit evidence for a dispute
404-
405-
```bash
406-
curl -X POST http://localhost:8080/v1/disputes/disp_123/evidence \
407-
-H "Content-Type: application/json" \
408-
-d '{
409-
"type": "customer_communication",
410-
"description": "Email from customer confirming receipt",
411-
"files": ["https://example.com/evidence1.pdf"],
412-
"metadata": {
413-
"evidence_type": "email",
414-
"customer_email": "customer@example.com"
415-
}
416-
}'
417-
```
418-
419-
### System Health
420-
421-
#### Check if the system is healthy
422-
423-
```bash
424-
curl -X GET http://localhost:8080/v1/health
425-
```
426-
427143
## How Currency Routing Works
428144

429145
The system is smart about routing your payments to the right provider:
@@ -434,65 +150,16 @@ The system is smart about routing your payments to the right provider:
434150

435151
Just specify the currency in your request, and the system automatically picks the best provider.
436152

437-
## Important Notes
438-
439-
### Amount Format
440-
441-
Always use the smallest currency unit:
442-
443-
- **USD/EUR**: cents (1000 = $10.00)
444-
- **IDR**: rupiah (50000 = Rp 50,000)
445-
- **SGD**: cents (1500 = S$15.00)
446-
- **INR**: paise (100000 = ₹1,000.00)
447-
448-
### Payment Methods
449-
450-
Make sure you're using valid payment method IDs from your chosen provider:
451-
452-
- Stripe: `pm_123456789`
453-
- Xendit: `pm_xendit_123`
454-
455-
### Customer IDs
456-
457-
Your customer IDs should match what's in your provider's system.
458-
459-
## Cache support
460-
461-
The Redis cache is ready to go and can be used to cache things like payment methods, customer info, and subscription details. Right now, the cache is set up but not actively caching. It's there for when you want to add caching to improve performance.
462-
463-
Here's how you might use the cache in a service:
464-
465-
```go
466-
type ExampleService struct {
467-
store Store
468-
cache *cache.RedisCache
469-
}
470-
471-
func NewExampleService(store Store, cache *cache.RedisCache) *ExampleService {
472-
return &ExampleService{
473-
store: store,
474-
cache: cache,
475-
}
476-
}
477-
478-
func (s *ExampleService) GetItem(ctx context.Context, id string) (*Item, error) {
479-
cacheKey := "item:" + id
480-
if cachedData, err := s.cache.Get(ctx, cacheKey); err == nil {
481-
var item Item
482-
if err := json.Unmarshal([]byte(cachedData), &item); err == nil {
483-
return &item, nil
484-
}
485-
}
486-
487-
item, err := s.store.GetItem(ctx, id)
488-
if err != nil {
489-
return nil, err
490-
}
491-
492-
if itemJSON, err := json.Marshal(item); err == nil {
493-
s.cache.Set(ctx, cacheKey, itemJSON)
494-
}
495-
496-
return item, nil
497-
}
498-
```
153+
> [!TIP]
154+
> For more details on smart routing, see the [Smart Routing Guide](docs/SMART_ROUTING.md).
155+
156+
## Documentation
157+
158+
| Document | Description |
159+
|----------|-------------|
160+
| [API Reference](docs/API_REFERENCE.md) | Endpoints, examples, authentication |
161+
| [Architecture](docs/ARCHITECTURE.md) | System design and diagrams |
162+
| [Smart Routing](docs/SMART_ROUTING.md) | How currency routing works |
163+
| [Fraud Detection](docs/FRAUD_DETECTION.md) | AI-powered fraud prevention |
164+
| [Security Guide](docs/SECURITY_GUIDE.md) | Security best practices |
165+
| [Development Guide](docs/DEVELOPMENT.md) | Database scripts, caching, dev tips |

0 commit comments

Comments
 (0)