ShopifexWeb.PaymentController behaviour (Shopifex v3.0.0)

Copy Markdown View Source

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

Use this module inside your application's payment controller:

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.

Summary

Callbacks

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.

Creates a charge in Shopify for the given plan.

Display the available payment plans for the user to select.

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

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

Functions

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

Callbacks

after_payment(t, t, t, t, t)

(optional)
@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(shop, plan)

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

Creates a charge in Shopify for the given plan.

render_plans(conn, guard_identifier, redirect_after)

(optional)
@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?(shop, plan)

(optional)
@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(shop, plan, charge_id)

(optional)
@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.

Functions

bind_charge(shop, plan, charge_id, redirect_after)

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