# `ShopifexWeb.PaymentController`
[🔗](https://github.com/ericdude4/shopifex/blob/main/lib/shopifex_web/controllers/payment_controller.ex#L1)

Controller behaviour for Shopify billing, plan selection, and charge verification.

Use this module inside your application's payment controller:

```elixir
defmodule MyAppWeb.PaymentController do
  use MyAppWeb, :controller
  use ShopifexWeb.PaymentController
end
```

### Billing Flow

1. Merchant hits a pay-walled action guarded by `Shopifex.Plug.PaymentGuard`.
2. If no valid grant exists, the merchant is redirected to `/payment/show-plans`.
3. Selecting a plan sends a POST to `/payment/select-plan`, which creates a Shopify
   charge (`appSubscriptionCreate` or `appPurchaseOneTimeCreate`) and binds the charge
   cryptographically via `bind_charge/4`.
4. The merchant approves the charge in Shopify and is redirected back to `/payment/complete`.
5. `complete_payment/2` validates the signed charge binding, verifies that the charge is
   active in Shopify via `verify_charge/3`, creates the `Grant` record, and invokes
   `after_payment/5`.

### Custom Select-Plan Actions

If your application defines a custom action to initiate charges (instead of the standard
`select_plan/2`), you must call `ShopifexWeb.PaymentController.bind_charge/4` before
redirecting the merchant to Shopify's confirmation URL.

# `after_payment`
*optional* 

```elixir
@callback after_payment(
  Plug.Conn.t(),
  Ecto.Schema.t(),
  Ecto.Schema.t(),
  Ecto.Schema.t(),
  String.t()
) :: Plug.Conn.t()
```

An optional callback called after a payment is completed. By default, this function
redirects the user to the app index within their Shopify admin panel.

## Example

    def after_payment(conn, shop, plan, grant, redirect_after) do
      # send yourself an e-mail about payment

      # follow default behaviour.
      super(conn, shop, plan, grant, redirect_after)
    end

# `create_charge`
*optional* 

```elixir
@callback create_charge(shop :: map(), plan :: map()) :: {:ok, map()} | {:error, term()}
```

Creates a charge in Shopify for the given plan.

# `render_plans`
*optional* 

```elixir
@callback render_plans(
  conn :: Plug.Conn.t(),
  guard_identifier :: String.t(),
  redirect_after :: String.t()
) ::
  Plug.Conn.t()
```

Display the available payment plans for the user to select.

# `test_charge?`
*optional* 

```elixir
@callback test_charge?(shop :: Ecto.Schema.t(), plan :: map()) :: boolean()
```

Given a shop and plan, return boolean for whether the charge should be created as
a test charge.

# `verify_charge`
*optional* 

```elixir
@callback verify_charge(shop :: map(), plan :: map(), charge_id :: String.t() | integer()) ::
  :ok | {:error, term()}
```

Verifies that the charge has been approved and is active in Shopify before granting access.

# `bind_charge`

```elixir
@spec bind_charge(
  shop :: map(),
  plan :: map(),
  charge_id :: String.t() | integer(),
  redirect_after :: String.t()
) :: :ok
```

Cryptographically binds a pending charge to `{shop, plan, redirect_after}` and
stores it under `charge_id` in the configured `:redirect_after_agent`.

Custom `select_plan` actions must call this function before redirecting the
merchant to Shopify's confirmation URL.

---

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