# 4Geeks API

Base URL: `https://api.4geeks.io`

## Authentication

All API requests require authentication using an API Key passed via the `X-Api-Key` header:

```
X-Api-Key: sk_test_your_api_key_here
```

Alternatively, use HTTP Basic Authentication (RFC 7617) where credentials are `<api_key>:` Base64 encoded:

```
Authorization: Basic <base64_encoded_credentials>
```

- Test keys start with `sk_test_`
- Live keys start with `sk_live_`
- API keys do not expire; rotate them from the dashboard if compromised

## Endpoints

### Payments

| Method | Endpoint | Description | Auth |
|--------|----------|-------------|------|
| POST | `/v1/payments/session` | Create a checkout session (server-to-server). Returns session_id and checkout_url. | Yes |
| GET | `/v1/payments/session/{session_id}` | Get checkout session details. No auth required (session_id acts as secure token). | No |
| POST | `/v1/payments/intent` | Create a PaymentIntent using a session_id. Returns client_secret for frontend SDK. | No |
| POST | `/v1/payments/subscription` | Create a Subscription via PaymentIntent. Returns first invoice PaymentIntent client_secret. | No |
| POST | `/v1/payments/` | Create a Hosted Checkout Session. Returns payment ID and redirect URL. | Yes |
| GET | `/v1/payments/` | List payments with pagination. Query params: status, test, limit, offset. | Yes |
| GET | `/v1/payments/{id}` | Get a specific payment by ID. | Yes |
| GET | `/v1/payments/internal` | List all payments (internal use). Same query params as List Payments. | Yes |

### Customers

| Method | Endpoint | Description | Auth |
|--------|----------|-------------|------|
| POST | `/v1/customers` | Create a new customer. Body: email (required), name, description, phone. | Yes |
| GET | `/v1/customers` | List customers with pagination. Query params: limit, offset. | Yes |

### Payment Links

| Method | Endpoint | Description | Auth |
|--------|----------|-------------|------|
| POST | `/v1/payment-links` | Create a shareable payment link. Body: amount (cents), currency, description. | Yes |
| GET | `/v1/payment-links` | List payment links with pagination. Query params: limit, offset. | Yes |

### Subscriptions

| Method | Endpoint | Description | Auth |
|--------|----------|-------------|------|
| POST | `/v1/subscriptions` | Create a subscription. Body: customer_id, plan_id. | Yes |
| GET | `/v1/subscriptions` | List subscriptions with pagination. Query params: limit, offset. | Yes |

### Products

| Method | Endpoint | Description | Auth |
|--------|----------|-------------|------|
| POST | `/v1/products` | Create a product. Body: name (required), description, active. | Yes |
| GET | `/v1/products` | List products with pagination. Query params: limit, offset. | Yes |

### Plans

| Method | Endpoint | Description | Auth |
|--------|----------|-------------|------|
| POST | `/v1/plans` | Create a subscription plan. Body: product_id, amount (cents), currency, interval. | Yes |
| GET | `/v1/plans` | List plans with pagination. Query params: limit, offset. | Yes |

### Refunds

| Method | Endpoint | Description | Auth |
|--------|----------|-------------|------|
| POST | `/v1/refunds` | Create a refund. Body: payment_id (required), amount (cents, optional for full refund), reason. | Yes |
| GET | `/v1/refunds` | List refunds with pagination. Query params: limit, offset. | Yes |

## Common Response Patterns

### Success Responses

- **200 OK**: Standard success for GET and most POST requests
- **201 Created**: Resource successfully created (checkout sessions, payment intents)
- **202 Accepted**: Action required (hosted checkout returns redirect URL)

### Error Responses

- **400 Bad Request**: Missing required fields or invalid format
- **401 Unauthorized**: Invalid, missing, or malformed API Key
- **404 Not Found**: Resource not found or no API keys initialized
- **422 Validation Error**: Request body validation failed

### Error Response Format

```json
{
    "code": 400,
    "title": "Invalid request",
    "content": "Error description",
    "type": "danger"
}
```

### Pagination

List endpoints support pagination with `limit` (default: 10) and `offset` (default: 0) query parameters. Response includes:

```json
{
    "items": [...],
    "total_items": 42,
    "limit": 10,
    "offset": 0
}
```

## Sandbox Environment

- Sandbox is free, unlimited, and has no deadline
- Use Test API Keys (`sk_test_...`) for sandbox
- Sandbox data is separate from Production data
- Access the Console dashboard to view transactions, events, and inspect payloads

## Code Examples

### cURL

```bash
curl -X POST 'https://api.4geeks.io/v1/customers' \
  -H 'X-Api-Key: sk_test_your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{"email": "customer@example.com", "name": "John Doe"}'
```

### Python

```python
import requests

response = requests.post(
    'https://api.4geeks.io/v1/customers',
    headers={'X-Api-Key': 'sk_test_your_api_key_here'},
    json={'email': 'customer@example.com', 'name': 'John Doe'}
)
print(response.json())
```

### JavaScript

```javascript
const response = await fetch('https://api.4geeks.io/v1/customers', {
    method: 'POST',
    headers: {
        'X-Api-Key': 'sk_test_your_api_key_here',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        email: 'customer@example.com',
        name: 'John Doe'
    })
});
const data = await response.json();
console.log(data);
```

## Security Best Practices

- Store API keys in environment variables, never in code
- Do not commit keys to version control
- Use `.env` files with `.gitignore`
- Rotate keys every 3-6 months
- Regenerate immediately if exposed

## Full Documentation

Complete documentation with guides, FAQs, and additional resources: https://docs.4geeks.io/en/api/