# apexl/io-payment

Gateway-agnostic payment + subscription + tokenisation contracts for [Cygnus](https://gitlab.apexl/cygnus/io-boilerplate). Bring your own gateway adapter package.

## V3 vs V1

This is the **V3** branch (`v3` branch, releases tagged `v3.0.x`). V3 is a clean architectural break from V1:

- **V1** (master branch, `v1.0.x`): Stripe + PayPal + GoCardless adapters bundled in-package; project-specific controllers / services / WooCommerce integration; tied to `apexl/io ^1.0`.
- **V3** (this branch, `v3.0.x`): contracts + DTOs + entities only. Gateway adapters split into separate packages. Project-specific code lives in the consuming project (Hermes, etc.). Requires `apexl/io ^3.6` + PHP 8.4.

V1 stays maintained for legacy projects (GlobalSim Cygnus V1 stack). V3 is the platform-layer foundation for Hermes + future Cygnus V3 projects.

## Installation

```bash
composer require apexl/io-payment apexl/io-payment-stripe
```

`apexl/io-payment` ships the contracts; you also install at least one adapter (`apexl/io-payment-stripe`, `apexl/io-payment-paypal`, `apexl/io-payment-gocardless`, or `apexl/io-payment-revolut`). Adapters are `suggest`-listed — none are direct dependencies.

## Adapter authoring

A gateway adapter implements `PaymentGatewayInterface` plus one or more capability sub-interfaces:

```
PaymentGatewayInterface              core identity + configure()
  HostedCheckoutInterface              createCheckoutSession / lookupCheckoutSession
  SubscriptionGatewayInterface         createSubscription / cancelSubscription / changeSubscriptionPlan / lookupSubscription
  PaymentMethodGatewayInterface        listPaymentMethods / attachPaymentMethod / detachPaymentMethod / setDefaultPaymentMethod
  WebhookHandlerInterface              parseWebhook
  RefundableGatewayInterface           refund
  BillingPortalInterface               createBillingPortalSession
```

Consumers use `instanceof` to gate features per-adapter.

All adapter methods take + return strongly-typed DTOs (`CheckoutSessionRequest`, `WebhookEvent`, `SubscriptionResult`, etc.) — no associative arrays.

## Schema

Migrations install five tables — all gateway-agnostic:

- `payments` — every capture attempt
- `payment_logs` — append-only audit
- `payment_tokens` — saved card / wallet / bank refs (no PAN)
- `payment_webhook_log` — idempotency + replay
- `payment_provider_refs` — entity-to-gateway-ref map

## Releases

- `v3.0.1` — initial V3 release. Contracts + DTOs + entities + schema. No adapters in-package.

## Licence

MIT. See LICENSE.
