PhoenixKitBilling.Providers.EveryPay (PhoenixKitBilling v0.3.1)

Copy Markdown View Source

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).

Summary

Functions

charge_payment_method(payment_method, amount, opts)

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

create_checkout_session(invoice, opts)

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

create_refund(provider_transaction_id, amount, opts)

Creates a refund for an EveryPay payment.

create_setup_session(user, opts)

Not supported by EveryPay.

fetch_payment(payment_reference)

Fetches the authoritative payment record from EveryPay.

get_payment_method_details(provider_payment_method_id)

Not supported by EveryPay.

handle_webhook_event(payment)

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

verify_webhook_signature(payload, signature, secret)

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

Functions

charge_payment_method(payment_method, amount, opts)

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(invoice, opts)

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(provider_transaction_id, amount, opts)

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(user, opts)

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(payment_reference)

@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(provider_payment_method_id)

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(payment)

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(payload, signature, secret)

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.