# Integration Guide

This guide explains how a solar merchant, installer marketplace, or small energy business can integrate Open Solar Payments.

## Integration Goals

An integration should allow a merchant application to:

- Create a Bitcoin/Lightning payment request from a quote, cart, order, or workorder.
- Generate a Lightning invoice using a configured backend.
- Show the customer a checkout URL or BOLT11 invoice.
- Track invoice status.
- Generate a receipt after payment.
- Connect confirmed payments to installer settlement records where relevant.

## Step 1: Choose a Lightning Backend

Recommended first backend:

```text
BTCPay Server
```

Possible future adapters:

```text
LNbits
Core Lightning
LND
Voltage-hosted node
Other provider-specific Lightning APIs
```

The merchant application should talk to Open Solar Payments, not directly to every provider-specific API. Provider-specific logic should stay inside adapters.

## Step 2: Configure Provider Secrets

Example environment variables:

```text
OPEN_SOLAR_PAYMENTS_PROVIDER=btcpay
BTCPAY_BASE_URL=https://pay.example.com
BTCPAY_STORE_ID=store_123
BTCPAY_API_KEY=...
BTCPAY_WEBHOOK_SECRET=...
```

Secrets should not be committed to public repositories.

## Step 3: Create a Payment Request

When a buyer accepts a solar quote or starts checkout, the merchant application creates a payment request.

Example:

```json
{
  "sourceType": "solar_quote",
  "sourceId": "quote_456",
  "customerRef": "customer_789",
  "description": "Deposit for 5kVA solar system",
  "amountSats": 185000,
  "displayAmount": {
    "amount": 250000,
    "currency": "NGN"
  }
}
```

The merchant application should store the returned `paymentRequestId` against the quote, order, or workorder.

## Step 4: Generate Invoice

The merchant application asks the module to generate a Lightning invoice:

```text
POST /payment-requests/:paymentRequestId/invoices
```

The response may include:

- BOLT11 invoice
- Checkout URL
- Expiry time
- Invoice status

The customer-facing app can display a QR code, copyable invoice text, or redirect to the checkout URL.

## Step 5: Poll or Subscribe to Status

The customer checkout page may poll:

```text
GET /invoices/:invoiceId/status
```

Expected customer-facing states:

```text
Waiting for payment
Payment received
Invoice expired
Payment failed
```

## Step 6: Handle Webhook Confirmation

The Lightning backend sends a webhook to:

```text
POST /webhooks/:provider/payment-confirmed
```

The module should:

- Verify the webhook.
- Normalize the event.
- Match the event to the invoice.
- Mark the invoice as paid.
- Mark the payment request as paid.
- Generate a receipt.
- Update settlement records where needed.

## Step 7: Generate Receipt

After confirmation, customers and admins can access:

```text
GET /receipts/:receiptId
```

The receipt should include:

- Receipt number
- Payment request reference
- Quote/order/workorder reference
- Amount in sats
- Display amount and currency
- Payment timestamp
- Merchant reference

## Step 8: Connect Installer Settlement

For installation payments, create or update settlement records:

```text
POST /settlements
GET /workorders/:workorderId/settlement
```

The merchant admin panel can then show:

- Paid deposit
- Outstanding balance
- Installer assigned
- Settlement status
- Receipt link
- Reconciliation status

## Suntecorb Integration Path

Suntecorb can integrate the module in five practical places:

1. Solar quote deposit
2. Product/component checkout
3. Installer booking deposit
4. Workorder balance payment
5. Admin reconciliation

## Minimal Merchant Integration

A smaller solar business does not need Suntecorb's full marketplace. A minimal integration can use only:

- `POST /payment-requests`
- `POST /payment-requests/:id/invoices`
- `GET /invoices/:id/status`
- `GET /receipts/:id`

This makes the module useful beyond Suntecorb.

## Recommended Public Repository Structure

```text
open-solar-payments/
  README.md
  docs/
    architecture.md
    api-spec.md
    data-model.md
    integration-guide.md
  packages/
    core/
    adapters/
      btcpay/
      lnbits/
    examples/
      suntecorb-reference/
  LICENSE
```

## Acceptance Criteria for First Integration

- A solar quote can create a payment request.
- A Lightning invoice can be generated.
- A user can see payment status.
- A paid invoice creates a receipt.
- A workorder payment creates or updates settlement state.
- Admins can reconcile paid workorders.
- The integration can be documented without exposing private Suntecorb source code.