# Safepoint API Documentation

## Overview
Welcome to the Safepoint Escrow API! The Safepoint API allows you to integrate secure escrow transactions, wallet management, virtual accounts, and user authentication into your own applications.

## Base URL
For local development: `http://localhost:8000` (or your configured local URL)
For production: Replace with your production domain

## Authentication
The API uses two main authentication methods:
1. **Bearer Token**: Authenticate using a Bearer token in the `Authorization` header
2. **API Key**: Authenticate using an `X-API-Key` header

## Table of Contents
- [Authentication Endpoints](#authentication-endpoints)
  - [Register User](#register-user)
  - [Login User](#login-user)
- [User API Endpoints](#user-api-endpoints)
  - [Register (User-Friendly)](#register-user-friendly)
  - [Login (User-Friendly)](#login-user-friendly)
  - [Get User Profile (User-Friendly)](#get-user-profile-user-friendly)
  - [Virtual Account](#virtual-account)
- [Profile Endpoints](#profile-endpoints)
  - [Get Profile](#get-profile)
  - [Update Profile](#update-profile)
- [Wallet Endpoints](#wallet-endpoints)
  - [Get Wallet Balance](#get-wallet-balance)
  - [Initiate Funding](#initiate-funding)
  - [Get Transaction History](#get-transaction-history)
- [Escrow Endpoints](#escrow-endpoints)
  - [Create Escrow](#create-escrow)
  - [Accept Escrow](#accept-escrow)
  - [Release Escrow](#release-escrow)
  - [Cancel Escrow](#cancel-escrow)
  - [Dispute Escrow](#dispute-escrow)
  - [List User Escrows](#list-user-escrows)
  - [Get Escrow Details](#get-escrow-details)
- [Admin Endpoints](#admin-endpoints)
  - [List Users](#list-users)
  - [List Escrows](#list-escrows)
  - [Get Fees](#get-fees)
  - [Update Fees](#update-fees)
  - [List Disputes](#list-disputes)
  - [List Withdrawals](#list-withdrawals)
  - [Get Analytics](#get-analytics)
  - [Get Audit Log](#get-audit-log)
  - [Expire Old Escrows](#expire-old-escrows)
- [Webhook Endpoints](#webhook-endpoints)
  - [WhoGoPay Webhook](#whogopay-webhook)


---

## Authentication Endpoints

### Register User
Create a new user account.

**Endpoint**: `POST /auth/register`

**Request Body**:
```json
{
  "email": "user@example.com",
  "username": "johndoe",
  "usertag": "@johndoe",
  "firstname": "John",
  "lastname": "Doe",
  "password": "securepassword",
  "pin": "1234",
  "phone_number": "08012345678"
}
```

**Response**:
```json
{
  "success": true,
  "message": "Registration successful",
  "user": {
    "id": 1,
    "email": "user@example.com",
    "username": "johndoe",
    "usertag": "@johndoe",
    "firstname": "John",
    "lastname": "Doe",
    "role": "USER"
  },
  "api_key": "your-api-key"
}
```


### Login User
Authenticate an existing user.

**Endpoint**: `POST /auth/login`

**Request Body**:
```json
{
  "email": "user@example.com",
  "password": "securepassword"
}
```

**Response**:
```json
{
  "success": true,
  "message": "Login successful",
  "user": {
    "id": 1,
    "email": "user@example.com",
    "username": "johndoe",
    "usertag": "@johndoe",
    "firstname": "John",
    "lastname": "Doe",
    "role": "USER"
  },
  "api_key": "your-api-key"
}
```


---

## User API Endpoints
These endpoints are designed for easy integration with mobile apps and other user-facing interfaces.

### Register (User-Friendly)
Create a new user account with app-compatible fields.

**Endpoint**: `POST /user/api/register`

**Request Body**:
```json
{
  "email": "user@example.com",
  "username": "johndoe",
  "usertag": "@johndoe",
  "firstname": "John",
  "lastname": "Doe",
  "password": "securepassword",
  "pin": "1234",
  "phonenumber": "08012345678"
}
```

**Response**:
```json
{
  "success": true,
  "message": "Registration successful",
  "user": {
    "id": 1,
    "email": "user@example.com",
    "username": "johndoe",
    "usertag": "@johndoe",
    "firstname": "John",
    "lastname": "Doe",
    "role": "USER"
  },
  "api_key": "your-api-key"
}
```


### Login (User-Friendly)
Authenticate an existing user.

**Endpoint**: `POST /user/api/login`

**Request Body**:
```json
{
  "email": "user@example.com",
  "password": "securepassword"
}
```

**Response**:
```json
{
  "success": true,
  "message": "Login successful",
  "data": {
    "user": {
      "id": 1,
      "email": "user@example.com",
      "username": "johndoe",
      "usertag": "@johndoe",
      "firstname": "John",
      "lastname": "Doe",
      "role": "USER"
    },
    "tokens": {
      "access": "access-token",
      "refresh": "refresh-token"
    }
  }
}
```


### Get User Profile (User-Friendly)
Get the authenticated user's profile.

**Endpoint**: `GET /user/api/user-profile`

**Headers**:
- `Authorization: Bearer <your-access-token>` or `X-API-Key: <your-api-key>`

**Response**:
```json
{
  "success": true,
  "message": "User profile retrieved",
  "data": {
    "id": 1,
    "email": "user@example.com",
    "username": "johndoe",
    "usertag": "@johndoe",
    "firstname": "John",
    "lastname": "Doe",
    "role": "USER",
    "wallet_available": 1000.00,
    "wallet_escrowed": 500.00
  }
}
```


### Virtual Account
Manage your virtual account for funding.

#### Get or Generate Virtual Account
Get your existing virtual account or generate a new one.

**Endpoint**: `POST /user/api/virtual-account`

**Headers**:
- `Authorization: Bearer <your-access-token>` or `X-API-Key: <your-api-key>`

**Response**:
```json
{
  "success": true,
  "message": "Dynamic account created successfully",
  "account": {
    "id": 1,
    "account_holder_id": "account-holder-id",
    "account_ref": "SF1_20250531123456_1234",
    "bank_name": "Example Bank",
    "bank_account_number": "1234567890",
    "bank_account_name": "WhoGoPay/John Doe",
    "currency": "NGN",
    "expiry_date": "2025-06-01T00:00:00.000Z"
  }
}
```

#### Get User's Virtual Accounts
List all your virtual accounts.

**Endpoint**: `GET /user/api/virtual-account`

**Headers**:
- `Authorization: Bearer <your-access-token>` or `X-API-Key: <your-api-key>`

**Response**:
```json
{
  "success": true,
  "accounts": [
    {
      "id": 1,
      "user_id": 1,
      "account_holder_id": "account-holder-id",
      "account_ref": "SF1_20250531123456_1234",
      "bank_name": "Example Bank",
      "bank_account_number": "1234567890",
      "bank_account_name": "WhoGoPay/John Doe",
      "currency": "NGN",
      "expiry_date": "2025-06-01T00:00:00.000Z"
    }
  ]
}
```


---

## Profile Endpoints

### Get Profile
Get the authenticated user's profile.

**Endpoint**: `GET /profile/get`

**Headers**:
- `X-API-Key: <your-api-key>`

**Response**:
```json
{
  "success": true,
  "user": {
    "id": 1,
    "email": "user@example.com",
    "username": "johndoe",
    "usertag": "@johndoe",
    "firstname": "John",
    "lastname": "Doe",
    "role": "USER",
    "email_verified": 0
  }
}
```


### Update Profile
Update the authenticated user's profile information.

**Endpoint**: `PUT /profile/update` or `POST /profile/update`

**Headers**:
- `X-API-Key: <your-api-key>`

**Request Body**:
```json
{
  "firstname": "John",
  "lastname": "Doe",
  "phone_number": "08012345678"
}
```

**Response**:
```json
{
  "success": true,
  "message": "Profile updated successfully",
  "user": {
    "id": 1,
    "email": "user@example.com",
    "username": "johndoe",
    "usertag": "@johndoe",
    "firstname": "John",
    "lastname": "Doe",
    "role": "USER"
  }
}
```


---

## Wallet Endpoints

### Get Wallet Balance
Get the current balance of the authenticated user's wallet.

**Endpoint**: `GET /wallet/balance`

**Headers**:
- `X-API-Key: <your-api-key>`

**Response**:
```json
{
  "success": true,
  "balance": 1000.00,
  "available": 1000.00,
  "escrowed": 0
}
```


### Initiate Funding
Initialize a funding request for your wallet.

**Endpoint**: `POST /wallet/fund`

**Headers**:
- `X-API-Key: <your-api-key>`

**Request Body**:
```json
{
  "amount": 1000.00,
  "payment_method": "whogopay"
}
```

**Response**:
```json
{
  "success": true,
  "funding_id": 1,
  "payment_reference": "SF_1_abc123def456",
  "amount": 1000.00,
  "virtual_account": {
    "account_name": "WhoGoPay/John Doe",
    "account_number": "1234567890",
    "bank_name": "Example Bank",
    "currency": "NGN",
    "account_reference": "SF1_20250531123456_1234"
  },
  "message": "Transfer funds to the virtual account to fund your wallet"
}
```


### Get Transaction History
Retrieve the user's transaction history.

**Endpoint**: `GET /wallet/history?limit=50&offset=0`

**Headers**:
- `X-API-Key: <your-api-key>`

**Query Parameters**:
- `limit`: (optional, default: 50, max: 100) Number of transactions to return
- `offset`: (optional, default: 0) Offset for pagination

**Response**:
```json
{
  "success": true,
  "transactions": [
    {
      "id": 1,
      "user_id": 1,
      "type": "CREDIT",
      "amount": 1000.00,
      "description": "Wallet funding",
      "created_at": "2025-05-31T12:00:00.000Z"
    }
  ],
  "total": 1
}
```


---

## Escrow Endpoints

### Create Escrow
Create a new escrow transaction.

**Endpoint**: `POST /escrow/create`

**Headers**:
- `X-API-Key: <your-api-key>`

**Request Body**:
```json
{
  "counterparty_username": "janedoe",
  "amount": 5000.00,
  "fee_payer": "ME"
}
```
**Notes on `fee_payer`**:
- `"ME"`: You (creator) pay all fees
- `"OTHER"`: Counterparty pays all fees
- `"BOTH"`: Split fees between creator and counterparty (using system-configured fee percentages)

**Response**:
```json
{
  "success": true,
  "escrow": {
    "id": 1,
    "creator_id": 1,
    "counterparty_id": 2,
    "amount": 5000.00,
    "fee_creator": 100.00,
    "fee_counterparty": 50.00,
    "state": "PENDING",
    "release_code": "ABC123",
    "expires_at": "2025-06-07T12:00:00.000Z"
  }
}
```


### Accept Escrow
Accept a pending escrow transaction as the counterparty.

**Endpoint**: `POST /escrow/accept`

**Headers**:
- `X-API-Key: <your-api-key>`

**Request Body**:
```json
{
  "escrow_id": 1
}
```

**Response**:
```json
{
  "success": true,
  "escrow": {
    "id": 1,
    "state": "ACCEPTED"
  }
}
```


### Release Escrow
Release the escrow funds to the counterparty.

**Endpoint**: `POST /escrow/release`

**Headers**:
- `X-API-Key: <your-api-key>`

**Request Body**:
```json
{
  "escrow_id": 1,
  "release_code": "ABC123"
}
```

**Response**:
```json
{
  "success": true,
  "escrow": {
    "id": 1,
    "state": "RELEASED"
  }
}
```


### Cancel Escrow
Cancel a pending or accepted escrow transaction.

**Endpoint**: `POST /escrow/cancel`

**Headers**:
- `X-API-Key: <your-api-key>`

**Request Body**:
```json
{
  "escrow_id": 1
}
```

**Response**:
```json
{
  "success": true,
  "escrow": {
    "id": 1,
    "state": "CANCELLED"
  }
}
```


### Dispute Escrow
Dispute an escrow transaction.

**Endpoint**: `POST /escrow/dispute`

**Headers**:
- `X-API-Key: <your-api-key>`

**Request Body**:
```json
{
  "escrow_id": 1,
  "reason": "Item is not as described"
}
```

**Response**:
```json
{
  "success": true,
  "escrow": {
    "id": 1,
    "state": "DISPUTED"
  }
}
```


### List User Escrows
List all escrows for the authenticated user.

**Endpoint**: `GET /escrow/list?status=PENDING`

**Headers**:
- `X-API-Key: <your-api-key>`

**Query Parameters**:
- `status`: (optional) Filter by escrow status (e.g., PENDING, ACCEPTED, DISPUTED)

**Response**:
```json
{
  "success": true,
  "escrows": [
    {
      "id": 1,
      "creator_id": 1,
      "counterparty_id": 2,
      "amount": 5000.00,
      "state": "PENDING",
      "created_at": "2025-05-31T12:00:00.000Z"
    }
  ]
}
```


### Get Escrow Details
Get the details of a specific escrow.

**Endpoint**: `GET /escrow/details?id=1`

**Headers**:
- `X-API-Key: <your-api-key>`

**Query Parameters**:
- `id`: (required) Escrow ID to retrieve

**Response**:
```json
{
  "success": true,
  "escrow": {
    "id": 1,
    "creator_id": 1,
    "counterparty_id": 2,
    "amount": 5000.00,
    "state": "PENDING",
    "created_at": "2025-05-31T12:00:00.000Z",
    "expires_at": "2025-06-07T12:00:00.000Z"
  }
}
```


---

## Admin Endpoints
**Requires Admin Role**

### List Users
List all users with optional search.

**Endpoint**: `GET /admin/users?page=1&limit=20&search=john`

**Headers**:
- `X-API-Key: <admin-api-key>`

**Query Parameters**:
- `page`: (optional, default: 1) Page number
- `limit`: (optional, default: 20) Number of users per page
- `search`: (optional) Search by username or email

**Response**:
```json
[
  {
    "id": 1,
    "email": "user@example.com",
    "username": "johndoe",
    "usertag": "@johndoe",
    "firstname": "John",
    "lastname": "Doe",
    "role": "USER"
  }
]
```


### List Escrows
List all escrows.

**Endpoint**: `GET /admin/escrows?page=1&limit=20&state=PENDING`

**Headers**:
- `X-API-Key: <admin-api-key>`

**Query Parameters**:
- `page`: (optional, default: 1) Page number
- `limit`: (optional, default: 20) Number of escrows per page
- `state`: (optional) Filter by escrow state

**Response**:
```json
[
  {
    "id": 1,
    "creator_id": 1,
    "counterparty_id": 2,
    "amount": 5000.00,
    "state": "PENDING"
  }
]
```


### Get Fees
Get current system fee configuration.

**Endpoint**: `GET /admin/fees`

**Headers**:
- `X-API-Key: <admin-api-key>`

**Response**:
```json
{
  "success": true,
  "fees": {
    "fee_creator": 0.02,
    "fee_counterparty": 0.01
  }
}
```


### Update Fees
Update system fee configuration.

**Endpoint**: `POST /admin/fees` or `PUT /admin/fees`

**Headers**:
- `X-API-Key: <admin-api-key>`

**Request Body**:
```json
{
  "fee_creator": 0.025,
  "fee_counterparty": 0.015
}
```

**Response**:
```json
{
  "success": true,
  "fees": {
    "fee_creator": 0.025,
    "fee_counterparty": 0.015
  }
}
```


### List Disputes
List all escrow disputes.

**Endpoint**: `GET /admin/disputes?page=1&limit=20&status=OPEN`

**Headers**:
- `X-API-Key: <admin-api-key>`

**Query Parameters**:
- `page`: (optional, default: 1) Page number
- `limit`: (optional, default: 20) Number of disputes per page
- `status`: (optional) Filter by dispute status

**Response**:
```json
[
  {
    "id": 1,
    "escrow_id": 1,
    "status": "OPEN"
  }
]
```


### List Withdrawals
List all withdrawal requests.

**Endpoint**: `GET /admin/withdrawals?page=1&limit=20&status=PENDING`

**Headers**:
- `X-API-Key: <admin-api-key>`

**Query Parameters**:
- `page`: (optional, default: 1) Page number
- `limit`: (optional, default: 20) Number of withdrawals per page
- `status`: (optional) Filter by withdrawal status

**Response**:
```json
[
  {
    "id": 1,
    "user_id": 1,
    "amount": 1000.00,
    "status": "PENDING"
  }
]
```


### Get Analytics
Get system-wide analytics.

**Endpoint**: `GET /admin/analytics`

**Headers**:
- `X-API-Key: <admin-api-key>`

**Response**:
```json
{
  "total_escrows": 100,
  "escrow_volume": 500000.00,
  "fees_collected": 5000.00,
  "active_users": 50,
  "disputed_escrows": 3,
  "expired_escrows": 5
}
```


### Get Audit Log
Get the system audit log.

**Endpoint**: `GET /admin/audit-log?limit=100`

**Headers**:
- `X-API-Key: <admin-api-key>`

**Query Parameters**:
- `limit`: (optional, default: 100) Number of log entries to return

**Response**:
```json
[
  {
    "id": 1,
    "user_id": 1,
    "action": "FUNDING_INITIATED",
    "entity_type": "wallet",
    "created_at": "2025-05-31T12:00:00.000Z"
  }
]
```


### Expire Old Escrows
Expire escrows that are past their expiration date.

**Endpoint**: `POST /admin/expire`

**Response**:
```json
{
  "success": true,
  "message": "Expired escrows processed"
}
```


---

## Webhook Endpoints

### WhoGoPay Webhook
Receive and process payment notifications from WhoGoPay.

**Endpoint**: `POST /webhook/whogopay`

**Request Body** (from WhoGoPay):
```json
{
  "transactionReference": "100004240917151537119432563324",
  "sessionId": "100004240917151537119432563324",
  "amount": 100,
  "paymentDate": "2024-09-17T15:16:06.3403184Z",
  "accountReference": "SF1_20250531123456_1234",
  "accountNumber": "1234567890",
  "accountName": "John Doe",
  "paymentDescription": "Transfer to John Doe",
  "paymentMethod": null,
  "paymentReference": "100004240917151537119432563324",
  "senderAccountNumber": "0987654321",
  "senderAccountName": "Sender Name",
  "senderBankName": "Sender Bank",
  "bankName": "WhoGoPay Bank",
  "metadata": {
    "sessionId": "100004240917151537119432563324",
    "paymentReference": "100004240917151537119432563324"
  }
}
```

**Response**:
```json
{
  "success": true,
  "message": "Wallet funded successfully"
}
```


---

## Error Handling
All API endpoints will return appropriate HTTP status codes and error messages. Common errors include:
- 400: Bad Request - Invalid input data
- 401: Unauthorized - Missing or invalid authentication
- 403: Forbidden - Insufficient permissions
- 404: Not Found - Endpoint does not exist
- 405: Method Not Allowed - Invalid HTTP method for endpoint
- 500: Internal Server Error - Server-side error

**Example Error Response**:
```json
{
  "success": false,
  "error": "Invalid amount"
}
```


## Rate Limiting
Currently, there is no rate limiting in place. This may change in future versions of the API.


## Changelog
- Initial API release with core authentication, wallet, and escrow functionality
- Added WhoGoPay integration for virtual accounts and payment webhooks
- Added system fee configuration for admins
- Added user-friendly API endpoints for mobile app integration