# Payment Gateway Driver Contract

The subscription engine talks only to this abstraction. Provider-specific request signing, URLs, response fields and webhook verification stay inside each gateway driver.

## Required operations

```php
interface PaymentGatewayInterface
{
    public function key(): string;
    public function capabilities(): GatewayCapabilities;

    public function createPayment(
        GatewayCreatePaymentRequest $request
    ): GatewayCreatePaymentResult;

    public function checkStatus(
        GatewayStatusRequest $request
    ): GatewayStatusResult;

    public function verifyWebhook(
        array $headers,
        string $rawBody
    ): GatewayWebhookResult;
}
```

Refund creation, saved payment methods and recurring mandates are capability interfaces rather than mandatory methods because providers differ.

## Canonical create request

```text
merchant_reference        ShasPOS invoice public number/ID
customer_name
customer_email
customer_phone
amount                     exact decimal string
currency                   ISO 4217
summary
description
return_url
cancel_url
idempotency_key
metadata
```

## Canonical create result

```text
gateway
provider_request_id
provider_reference
checkout_url
status
raw_response_reference
expires_at
```

Raw provider secrets are never returned.

## Canonical status

Provider states are normalized into:

```text
PENDING
APPROVED
REJECTED
PARTIALLY_REFUNDED
REFUNDED
REVERSED
EXPIRED
CANCELED
UNKNOWN
```

The adapter also returns provider-native status for diagnostics.

## Canonical webhook result

```text
authentic                  signature/auth verification result
gateway_event_id
event_type
provider_request_id
merchant_reference
status
amount
currency
refund_summary
occurred_at
raw_payload_hash
```

The billing service, not the gateway driver, decides subscription/invoice effects.

## ShasPay mapping

- Driver: `SHASPAY` / `ShasPayGateway`.
- Authentication: HMAC Signed.
- Create payment: ShasPay create-payment endpoint.
- Inquiry: request number or application reference lookup.
- Webhook authentication: HMAC over the exact raw JSON body using the independent webhook secret.
- Application reference type: `shaspos_subscription_invoice`.
- Application reference ID: internal subscription invoice ID.
- Idempotency: one stable key per ShasPOS invoice payment attempt.
- Hosted checkout URL returned to Flutter; Flutter contains no API key, API secret or webhook secret.
- Return/cancel URL never changes billing state by itself.