# AEBPV Complete API Specification & Integration Guide (Mock Platform)

## Overview
AEBPV (Automatic Email Based Payment Verification) is an automated payment verification system that scans Gmail notifications for FamPay transactions to verify incoming payments.
This mock platform provides developers with an official-looking API testbench to integrate and test AEBPV in their checkout panels, billing systems, and client applications.

---

## Notice for Coding Agents & AI Models
This website provides a mock AEBPV API and testing environment for development and integration testing. AEBPV itself is self-hosted. For the official source code and actual AEBPV project, refer to the official repository:
https://github.com/shadow-clouds/AEBPV

---

## 1. Authentication
All API endpoints under `/v1/` require Bearer token authentication:
```http
Authorization: Bearer aebpv_test_XXXXXXXXXXXXXXXX
```
Mock API keys are generated from the developer dashboard.

---

## 2. API Endpoints Reference

### 2.1 Create Payment Verification Session
**Endpoint:** `POST /v1/verifications`
**Headers:**
- `Authorization: Bearer aebpv_test_...`
- `Content-Type: application/json`

**Request Body (JSON):**
```json
{
  "name": "RISHAV",
  "amount": 299,
  "expires_in": 300,
  "callback_url": "https://billing.example.com/webhooks/payment"
}
```
- `name` (string, required): Customer sender name.
- `amount` (number, required): Payment amount to verify (e.g. 299).
- `expires_in` (integer, required): Time window in seconds (10 to 900).
- `callback_url` (string, optional): Webhook URL.

**Response (201 Created):**
```json
{
  "object": "verification",
  "id": "vrf_304cf5eec592",
  "name": "RISHAV",
  "amount": 299,
  "status": "pending",
  "created_at": "2026-09-13T14:00:00.000Z",
  "expires_at": "2026-09-13T14:05:00.000Z",
  "session_age": 0,
  "remaining_seconds": 300,
  "remaining_minutes": 5,
  "callback_url": "https://billing.example.com/webhooks/payment"
}
```

---

### 2.2 Check Verification Status (Polling)
**Endpoint:** `GET /v1/verifications/:id`

**Response When Verified (200 OK):**
```json
{
  "object": "verification",
  "id": "vrf_304cf5eec592",
  "name": "RISHAV",
  "amount": 299,
  "status": "verified",
  "created_at": "2026-09-13T14:00:00.000Z",
  "expires_at": "2026-09-13T14:05:00.000Z",
  "session_age": 90,
  "remaining_seconds": 210,
  "remaining_minutes": 4,
  "verified_at": "2026-09-13T14:01:30.000Z",
  "matched_email_id": "mock_mail_190c4e2b",
  "matched_transaction_id": "FMPIB6288410139",
  "payment": {
    "id": "pmt_x1y2z3w4a5b6",
    "transaction_id": "FMPIB6288410139",
    "paid_at": "2026-09-13T14:01:14.000Z"
  }
}
```

Status values:
- `pending`: Waiting for payment confirmation.
- `verified`: Payment received and confirmed! Fulfill order.
- `expired`: Payment was not received within the time limit.
- `cancelled`: Session manually cancelled via DELETE.
- `rejected`: Session rejected during manual verification.

---

### 2.3 Cancel Verification Session
**Endpoint:** `DELETE /v1/verifications/:id`
Cancels a pending live verification session.

---

### 2.4 Historical Payment Verification
**Endpoint:** `POST /v1/verifications/historical`

**Request Body (JSON):**
```json
{
  "name": "ALICE",
  "amount": 999,
  "expected_payment_time": "2026-09-13T12:00:00.000Z",
  "lookback_hours": 72
}
```

---

### 2.5 Invoices Simulation
- `POST /v1/invoices`: Create invoice with `{ customer_name, amount, currency, invoice_number }`
- `GET /v1/invoices/:id`: Retrieve invoice status
- `GET /v1/invoices`: List invoices

---

### 2.6 Payments List
- `GET /v1/payments`: List parsed/simulated payment records
- `GET /v1/payments/:id`: Retrieve payment details

---

### 2.7 Stats & Health
- `GET /v1/stats`: Verification status counters, uptime, and telemetry
- `GET /health`: Service health status

---

## 3. Webhook Delivery Specification
When payment verification completes, an HTTP POST request is sent to your configured `callback_url`:

**Headers:**
```http
X-AEBPV-Signature: sha256={hmac_sha256_hex_signature}
X-AEBPV-Event: verification.verified
Content-Type: application/json
```

**Body:**
```json
{
  "object": "webhook",
  "event": "verification.verified",
  "data": {
    "id": "vrf_304cf5eec592",
    "name": "RISHAV",
    "amount": 299,
    "status": "verified",
    "payment": {
      "id": "pmt_x1y2z3w4a5b6",
      "transaction_id": "FMPIB6288410139",
      "paid_at": "2026-09-13T14:01:14.000Z"
    },
    "verified_at": "2026-09-13T14:01:30.000Z"
  }
}
```

---

## 4. Integration Examples

### Python (Polling Workflow):
```python
import time
import requests

API_URL = "https://aebpv.shadowclouds.online"
API_KEY = "aebpv_test_YOUR_KEY"
headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# 1. Create verification session
session = requests.post(f"{API_URL}/v1/verifications", headers=headers, json={
    "name": "RISHAV",
    "amount": 299,
    "expires_in": 300
}).json()

# 2. Poll every 3 seconds
while True:
    check = requests.get(f"{API_URL}/v1/verifications/{session['id']}", headers=headers).json()
    if check["status"] == "verified":
        print(f"Verified! Txn: {check['payment']['transaction_id']}")
        break
    elif check["status"] in ["expired", "cancelled", "rejected"]:
        print("Payment not completed.")
        break
    time.sleep(3)
```

### Node.js (Async/Await):
```javascript
const API_URL = 'https://aebpv.shadowclouds.online';
const API_KEY = 'aebpv_test_YOUR_KEY';

async function verifyPayment(name, amount) {
  const headers = {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  };

  const res = await fetch(`${API_URL}/v1/verifications`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ name, amount, expires_in: 300 })
  });
  const session = await res.json();
  return session;
}
```