# WHMCS

> Ein Zahlungsgateway für WHMCS: Kunden bezahlen Rechnungen mit Bitcoin oder USDC/USDT direkt in Ihre Wallet, ein signierter Webhook verbucht die Zahlung.

Das Modul von Perly Pay bringt Krypto in die Rechnungen von WHMCS. Der Kunde klickt auf **Mit Krypto bezahlen**; der offene Betrag wird zu einer Rechnung in Perly Pay, bezahlt über der WHMCS-Seite oder auf einer eigenen Seite; ein signierter Webhook verbucht die Zahlung in WHMCS. WHMCS 8, PHP 8.1+ mit curl. Über Composer müssen Sie nichts installieren: Das [PHP-SDK](https://pay.perly.io/docs/sdks.md) ist schon enthalten.

> **Hinweis:** Perly Pay stellt Rechnungen in USD oder EUR aus. Für Kunden mit anderer Währung wählen Sie im Gateway bei **Convert To For Processing** USD oder EUR; die Zahlung wird trotzdem in der Währung der Rechnung selbst verbucht. Ohne das sehen solche Kunden einen Hinweis, eine andere Zahlungsart zu wählen.

## Installation

1. **Zip holen** — Das Modul ist auf dem Weg in den WHMCS Marketplace. Bis es dort ist, [schreiben Sie uns](https://pay.perly.io/de/contact) für `perly-pay-whmcs.zip`.
2. **Hochladen** — Entpacken Sie es über Ihren WHMCS-Ordner. Hinzu kommen `modules/gateways/perlypay.php`, `modules/gateways/callback/perlypay.php` und `modules/gateways/perlypay/`.
3. **Aktivieren** — Configuration → Apps & Integrations → Payment Gateways (oder Setup → Payment Gateways), **Perly Pay** aktivieren.

## Einstellungen

| Feld | Was hinein gehört |
| --- | --- |
| Geheimer Schlüssel | Dashboard → Developers → API keys. `sk_test_…` für den [Testmodus](https://pay.perly.io/docs/test-mode.md), `sk_live_…` für echtes Geld. |
| Signatur-Secret des Webhooks | `whsec_…`, vom Webhook, den Sie für dieses WHMCS hinzufügen (unten). |
| Zahlungsseite | **Overlay** öffnet den Checkout über der Rechnung (pay.js). **Weiterleitung** schickt den Kunden auf seine Seite. Auf Handys öffnet sich immer die Seite selbst. |
| Währungen | USD und EUR oder nur eine davon. |

1. **Schlüssel einfügen** — Speichern und im Schlüsselfeld auf **Verbindung testen** klicken: Sie sehen, ob der Schlüssel funktioniert, seinen Modus und ob der Webhook dieses WHMCS in Perly Pay existiert.
2. **Webhook hinzufügen** — Fügen Sie unter Dashboard → Developers → Webhooks die Adresse aus den Einstellungen hinzu, `https://your-whmcs/modules/gateways/callback/perlypay.php`, mit den Rechnungs- und Erstattungsereignissen. Setzen Sie ihr Secret ein und speichern Sie.
3. **Overlay erlauben** — Fügen Sie unter Dashboard → Settings die Adresse Ihres WHMCS bei **Sites that may embed the checkout** hinzu. Ohne das bietet das Overlay an, den Checkout in einem neuen Tab zu öffnen.

## Testen

Öffnen Sie mit einem Schlüssel `sk_test_…` eine unbezahlte Rechnung im Kundenbereich und klicken Sie auf **Mit Krypto bezahlen**. Bezahlen Sie mit Test-Coins oder über die API – die ID der Rechnung steht auf der Zahlungsseite:

```bash
curl -X POST https://pay.perly.io/api/v1/invoices/inv_…/simulate \
  -H "Authorization: Bearer $PERLY_PAY_SECRET_KEY" -H "Content-Type: application/json" -d '{}'
```

Nach wenigen Sekunden wird die Rechnung in WHMCS **Paid**. Billing → Gateway Log zeigt Netzwerk, Betrag und Link zur Transaktion.

## Wie Rechnungen den Zahlungen folgen

| In Perly Pay | In WHMCS |
| --- | --- |
| Bezahlt, Absender geprüft (`invoice.fulfilled`) | Eine Zahlung über den Betrag, der dem Kunden berechnet wurde, in der Währung der Rechnung, mit der Zahlungs-ID von Perly Pay (`pay_…`). WHMCS markiert die Rechnung als Paid und erledigt den Rest wie immer. |
| Gesehen, teilweise bezahlt, bezahlt und noch in Prüfung | Eine Zeile im Gateway Log. Keine Zahlung. |
| Zur [Prüfung](https://pay.perly.io/docs/screening.md) angehalten | Eine Zeile im Gateway Log mit Grund. Entscheiden Sie in Perly Pay. |
| Abgelaufen oder storniert | Eine Zeile im Gateway Log. Ein neuer Klick auf den Button erstellt eine neue Rechnung. |
| Erstattung eröffnet, bereit, gesendet, bestätigt | Eine Zeile im Gateway Log: was wohin zu senden ist. |

Ein erneuter Klick auf den Button nimmt die offene Rechnung, solange der offene Betrag gleich ist. Jede Zahlung wird einmal verbucht, egal wie oft der Webhook kommt, und nur für Rechnungen dieses WHMCS.

## Erstattungen

Erstatten Sie die Transaktion in WHMCS wie immer: Das Modul eröffnet eine [Erstattung](https://pay.perly.io/docs/refunds.md) in Perly Pay in der Coin, mit der bezahlt wurde (denselben Anteil bei einer Teilerstattung). Perly Pay bittet den Kunden per E-Mail um eine Adresse und prüft sie; das Gateway Log sagt, was wohin zu senden ist. Sie senden aus Ihrer Wallet und fügen die Transaktions-ID in Perly Pay ein – Perly Pay hält nie Geld.

## Live gehen

- Schalten Sie in Perly Pay den Live-Modus ein und verbinden Sie die öffentlichen Schlüssel Ihrer Wallet.
- Fügen Sie einen Schlüssel `sk_live_…` ein. Live-Schlüssel und -Webhooks sind von den Test-Pendants getrennt: Fügen Sie die Callback-Adresse im Live-Modus noch einmal hinzu und setzen Sie ihr Secret ein.
- Fügen Sie die https-Adresse Ihres WHMCS im Live-Modus bei **Sites that may embed the checkout** hinzu.
- Bezahlen Sie eine kleine echte Rechnung und erstatten Sie sie.