# `PhoenixKitBilling.Providers.EveryPay`
[🔗](https://github.com/BeamLabEU/phoenix_kit_billing/blob/0.5.1/lib/phoenix_kit_billing/providers/everypay.ex#L1)

EveryPay payment provider implementation.

Implements the `PhoenixKitBilling.Providers.Provider` behaviour for the
EveryPay (EveryPay AS, Estonia/Baltics) Payment Gateway, API v4. It supports:

- Hosted payment page for one-time payments (`/payments/oneoff`)
- Charging saved card tokens for subscription renewals (`/payments/mit`)
- Refunds (`/payments/:reference/refund`)
- Server-side payment-status verification of callbacks

## Configuration

Configure EveryPay in your provider settings:

    # Via Admin UI: /admin/settings/billing/providers
    # Or via Settings API:
    PhoenixKit.Settings.update_setting("billing_everypay_enabled", "true")
    PhoenixKit.Settings.update_setting("billing_everypay_api_username", "...")
    PhoenixKit.Settings.update_setting("billing_everypay_api_secret", "...")
    PhoenixKit.Settings.update_setting("billing_everypay_account_name", "EUR3D1")
    PhoenixKit.Settings.update_setting("billing_everypay_mode", "test")

- `mode` is `"test"` (demo gateway) or `"live"` (production gateway).
- `account_name` is the EveryPay processing account; it also fixes the
  currency, so EveryPay one-off requests do not send a currency.

## Webhook / Callback Verification

EveryPay v4 callbacks are **not** HMAC-signed. Instead of trusting the
callback payload, this provider re-fetches the authoritative payment record
from the API (`GET /payments/:reference`) using HTTP Basic auth and
normalizes that. See `PhoenixKitBilling.Web.WebhookController.everypay/2`.

Configure the callback URL in the EveryPay merchant portal
(E-shop settings -> Callback URL):

    https://yourdomain.com/phoenix_kit/webhooks/billing/everypay

## Dependencies

Uses `Req` for HTTP requests (already a dependency of this package).

# `charge_payment_method`

Charges a saved EveryPay card token (merchant-initiated transaction).

Used for subscription renewals. The token is stored on the payment method as
`provider_payment_method_id` during a one-off payment with
`:save_payment_method` enabled.

## Options

- `:description` - Description for the charge
- `:invoice_uuid` - Associated invoice UUID (used as `order_reference`)

## Examples

    iex> charge_payment_method(payment_method, Decimal.new("99.00"), invoice_uuid: uuid)
    {:ok, %ChargeResult{provider_transaction_id: "abc-123", status: "succeeded"}}

# `create_checkout_session`

Creates an EveryPay one-off payment and returns the hosted payment page URL.

The invoice total (`invoice.total`) is charged in the currency fixed by the
configured processing account.

## Options

- `:success_url` - URL EveryPay redirects the customer back to (required).
  EveryPay uses a single `customer_url` for both success and cancel; the
  return page must verify the payment state.
- `:customer_ip` - Customer IP address (recommended for fraud scoring)
- `:customer_email` - Pre-fill / attach customer email
- `:locale` - Payment page locale (e.g. `"en"`, `"et"`)
- `:save_payment_method` - Request a reusable card token (default: false)

## Examples

    iex> create_checkout_session(invoice, success_url: "https://...")
    {:ok, %CheckoutSession{id: "abc-123", url: "https://.../payment?..."}}

# `create_refund`

Creates a refund for an EveryPay payment.

`provider_transaction_id` is the EveryPay `payment_reference`. Pass `nil` as
`amount` for a full refund.

## Examples

    iex> create_refund("abc-123", Decimal.new("10.00"), [])
    {:ok, %RefundResult{provider_refund_id: "abc-123", status: "refunded"}}

# `create_setup_session`

Not supported by EveryPay.

EveryPay has no zero-amount "save card" flow; a card token is obtained as a
side effect of a one-off payment when `:save_payment_method` is set. Returns
`{:error, :not_supported}`.

# `fetch_payment`

```elixir
@spec fetch_payment(String.t()) :: {:ok, map()} | {:error, term()}
```

Fetches the authoritative payment record from EveryPay.

Used by the webhook controller to verify callbacks server-side. Returns the
raw decoded payment map (string keys) on success.

## Examples

    iex> fetch_payment("abc-123")
    {:ok, %{"payment_reference" => "abc-123", "payment_state" => "settled", ...}}

# `get_payment_method_details`

Not supported by EveryPay.

EveryPay exposes no standalone payment-method API; card tokens are only
available on the originating payment. Returns `{:error, :not_supported}`.

# `handle_webhook_event`

Normalizes an EveryPay payment record (as returned by `fetch_payment/1`) into
a `WebhookEventData` struct for `PhoenixKitBilling.WebhookProcessor`.

The payment `payment_state` drives the normalized event type:

- `settled` -> `checkout.completed`
- `failed` / `abandoned` / `voided` -> `payment.failed`
- `refunded` / `partially_refunded` -> `refund.created`
- any other state -> `{:error, :unknown_event}` (ignored)

# `verify_webhook_signature`

EveryPay v4 callbacks are not signed; verification is done by re-fetching the
payment status server-side. Always returns `:ok`.

See `fetch_payment/1` and `PhoenixKitBilling.Web.WebhookController.everypay/2`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*