Mishka Pay's Ash layer as a resource extension: a host's resource, in its own domain and data layer, says what it keeps, and gets the attributes, identities, calculations, actions, code interface and webhook listener of that kind.
defmodule MyApp.Pay.Subscription do
use Ash.Resource,
domain: MyApp.Pay,
data_layer: AshPostgres.DataLayer,
extensions: [MishkaPay.Ash.Resource]
mishka_pay do
kind :subscription
end
postgres do
table "pay_subscriptions"
repo MyApp.Repo
end
endThe application supervises the listeners of the domain's resources:
children = [MishkaPay.Providers.Stripe, MyApp.Pay.Keys] ++ MishkaPay.Ash.listeners(MyApp.Pay)A host owns the tables, the domain, the policies and the notifiers. Anything the host defines
itself is kept: an attribute, identity, calculation, action, relationship or code interface of
the same name is never added again, so a host can change one (such as the :tenant
attribute's type). A resource without its own primary key gets uuid_v7_primary_key :id, and
every kind gets the primary :read and :inserted_at/:updated_at timestamps.
Every action asks the provider before its transaction starts, writes what the provider
answered and, with announce? true, fires mishka_pay:<kind>:changed with the provider's
struct and the row after it. The host's Ash notifiers (such as Ash.Notifier.PubSub) see the
actions as usual, so an open screen can show a change live. Errors come back as Ash errors
(MishkaPay.Ash.to_ash_error/1).
A host that keeps tenants apart adds Ash multitenancy on its own attribute: each action then
reads the provider keys of its Ash tenant, and each listener syncs a webhook's row in the
webhook's own tenant (see MishkaPay.Ash.Tenant). The inbox stays global.
:inbox
Every checked provider event is stored once and worked by an AshOban job, with retries, so a
slow or failing step never loses an event and the provider gets its answer at once. The
extension adds AshOban to the resource; add the mishka_pay_inbox queue to Oban and the
resource's domain to AshOban.config/2 like any AshOban resource.
It holds the event's provider, tenant, id, type, object, payment, subscription, dispute, mode
and time (see MishkaPay.Event), its :status (:pending, :processed, :failed), the
:last_error (kept from each failed try, while it is still tried again) and when it was
processed. An identity on provider and event id keeps each event once, however often the
provider sends it.
:receivestores it (a second delivery finds the first) and starts the:processtrigger.:processfiresmishka_pay:event:process(MishkaPay.Events.event_process/0) with the event, outside the database transaction, in a task that cannot take the job down. A listener that sets:failed, raises, exits or runs pastconfig :mishka_pay, event_process_timeout:(30 seconds) leaves the event pending, its reason noted by:note_error: AshOban tries again, ten times in all.- After the last try,
:failmarks it:failedwith the reason, for a person to look at.
The trigger's worker and scheduler are <Resource>.MishkaPayWorker and
<Resource>.MishkaPayScheduler. Its listener stores each event MishkaPay.Webhook checked.
:payment
Holds the provider and its payment id, the tenant, the :status (see MishkaPay.Payment),
the :amount, :amount_refunded and :currency (the :money and :money_refunded
calculations give them as Money), the caller's :reference from the checkout, the buyer
(:customer_id, :customer_email, :customer_name), the card (:card_brand,
:card_last4), why the last try failed (:failure_code, :failure_message), whether the
buyer's bank asked for it back (:disputed), when the provider made it and when it was last
synced. An identity on provider and payment id keeps one row per payment.
:synctakes:provider,:payment_idand:tenant, reads the payment (MishkaPay.fetch_payment/3) and writes it, creating the row the first time; the tenant is kept from that first time, so a later sync never moves a payment to another tenant. Events may come twice or in any order: every sync writes the payment as it is now.:start_checkout(generic) opens a checkout (MishkaPay.checkout/1) from its:checkoutmap and answers theMishkaPay.Checkoutwith the page to send the buyer to. The row comes later, from the webhook of the payment the buyer makes.:refundrefunds the payment through its provider (MishkaPay.refund/1), in full or by:amount, with an optional:reasonand:reference, then syncs the row and keeps theMishkaPay.Refundin the record's:refundmetadata. How often a payment may be refunded is the tenant's runtime setting (MishkaPay.Credentials,:refunds). When the refund went through but the payment cannot be read again, the row counts the refund itself and the next sync brings the provider's word.
Its listener syncs the payment each inbox event concerns.
:subscription
Holds the provider and its subscription id, the tenant, the :status (see
MishkaPay.Subscription), the :plan (its items' names), what each period costs (:amount,
:currency, with the :money calculation) and how often (:interval, :interval_count),
how many (:quantity), the end of the period paid for (:current_period_end), whether it ends
then (:cancel_at_period_end), :canceled_at, :trial_end, a pause (:pause_behavior,
:resumes_at), the buyer, the caller's :reference, when the provider made it and when it was
last synced. A subscription starts with a checkout in mode: :subscription.
:synctakes:provider,:subscription_idand:tenantand writes what the provider says (MishkaPay.fetch_subscription/3).:cancelcancels it (MishkaPay.cancel_subscription/4),at: :period_end(the default) or:now;:resumetakes back a cancel set for the period's end (MishkaPay.resume_subscription/3).:changechanges its plan (:price_id) or quantity, with every option ofMishkaPay.Subscription.Changeas arguments (MishkaPay.change_subscription/1).:pausepauses collecting its payments (behavior:andresumes_at:, seeMishkaPay.pause_collection/4);:resume_collectioncollects again.
:customer
Holds the provider and its customer id, the tenant, :email, :name, :phone, the caller's
:reference (the host's own user id), :metadata, the :default_payment_method, when the
provider made it, when it was last synced, and :deleted_at once the provider deleted it.
:registermakes the customer at its provider (MishkaPay.create_customer/1) from:provider,:tenant,:email,:name,:phone,:referenceand:metadata, on:api(:v2or:v1) when given, else the tenant's:customer_api(at Stripe an account with the customer configuration,acct_..., by default). The same:referenceand fields registered twice within a day are one customer and one row.:synctakes:provider,:customer_idand:tenant(MishkaPay.fetch_customer/3). A customer the provider deleted keeps its row, with:deleted_atset.:editchanges:email,:name,:phoneor:metadataat the provider (MishkaPay.update_customer/1).:removedeletes the customer at the provider for good (MishkaPay.delete_customer/3), as a person's erase request asks, and keeps the row with:deleted_atset (at Stripe a customer made on Accounts v2 is closed). A host that must erase its own copy too destroys the row after. Acustomer.deletedwebhook marks the row the same way.:portal(generic) takes the row's:idand a:return_url(and the provider's:configuration) and answers aMishkaPay.PortalSession: redirect the buyer to its:url, where they manage their cards, invoices and subscriptions.
:dispute
Holds the provider and its dispute id, the tenant, the payment and charge it takes back, the
:amount and :currency (with the :money calculation), its :status (see
MishkaPay.Dispute), the bank's :reason, when evidence is due (:evidence_due_by), whether
evidence was sent (:has_evidence, :submission_count), whether the payment can still be
refunded (:refundable), when the provider made it and when it was last synced.
:synctakes:provider,:dispute_idand:tenant(MishkaPay.fetch_dispute/3).:submit_evidencesends:evidence(the provider's own field names, string to string), and to the bank at once withsubmit: true(MishkaPay.update_dispute/1).:acceptaccepts the loss (MishkaPay.accept_dispute/3).
Its listener syncs the dispute of each charge.dispute.* event.
Options
:kind- Required. What the resource keeps::inbox(each checked webhook event),:payment,:subscription,:customeror:dispute; or what a site manages from its admin::product,:price,:coupon,:promotion_code,:payment_linkor:invoice(MishkaPay.Ash.Object.Spec). Valid values are :inbox, :payment, :subscription, :customer, :dispute, :product, :price, :coupon, :promotion_code, :payment_link, :invoice:actions(list ofatom/0) - Only these actions of the kind, besides the primary:read. Every action of the kind when left out. An:inboxneeds all of its own.:listen?(boolean/0) - Makes<Resource>.MishkaPayListener, the webhook listener that keeps the resource current.MishkaPay.Ash.listeners/1lists them for the application's children. The default value istrue.:announce?(boolean/0) - Firesmishka_pay:<kind>:changedafter each write the provider answered. The inbox announces nothing either way. The default value istrue.:code_interface?(boolean/0) - Defines a code interface function for each action it adds, such asMyApp.Pay.Subscription.cancel!(row, %{at: :now}). The inbox's:receiveisreceive_event. The default value istrue.:tenant_from(atom/0) - The host's own attribute that holds the tenant, such as:site_id(an attribute, or the source attribute of abelongs_to :site), for a host that keeps sites apart without Ash multitenancy. Each create action writes its tenant there too; the row's:tenantstill picks the provider keys. With Ash multitenancy on that attribute, Ash fills it and this is not needed. Not for an:inbox, which stays global.:belongs_to_user- A:userbelongs_to relationship to the host's user resource, on:user_id, or on another attribute with{MyApp.Accounts.User, attribute: :owner_id}. A payment or a subscription gets its user from the checkout's owner, which:start_checkouttakes from the actor and every sync writes again (MishkaPay.Ash.Owner); a customer's:registertakes it as an input. It may be nil, for a sale with no owner.:resync_after(pos_integer/0) - Hours after which a row still open at its provider is read again by an hourly AshOban trigger running:resync, in case a webhook never came: a pending or authorized payment, a subscription that has not ended, an open dispute, a draft or open bill. Runs on the inbox's queue,mishka_pay_inbox. Off unless given.:keep_events_for- For an:inbox: how many days a processed event is kept before its daily:forgettrigger deletes it, or:forever. Failed and pending events are always kept. The default value is30.
MishkaPay.Ash.Resource.Info reads them back.
mishka_pay
What Mishka Pay keeps in this resource: its kind, and which of the kind's actions,
listener, announcements, code interface and user relationship it gets.
Examples
mishka_pay do
kind :subscription
actions [:sync, :cancel]
belongs_to_user MyApp.Accounts.User
end
Options
| Name | Type | Default | Docs |
|---|---|---|---|
kind | :inbox | :payment | :subscription | :customer | :dispute | :product | :price | :coupon | :promotion_code | :payment_link | :invoice | What the resource keeps: :inbox (each checked webhook event), :payment, :subscription, :customer or :dispute; or what a site manages from its admin: :product, :price, :coupon, :promotion_code, :payment_link or :invoice (MishkaPay.Ash.Object.Spec). | |
actions | list(atom) | Only these actions of the kind, besides the primary :read. Every action of the kind when left out. An :inbox needs all of its own. | |
listen? | boolean | true | Makes <Resource>.MishkaPayListener, the webhook listener that keeps the resource current. MishkaPay.Ash.listeners/1 lists them for the application's children. |
announce? | boolean | true | Fires mishka_pay:<kind>:changed after each write the provider answered. The inbox announces nothing either way. |
code_interface? | boolean | true | Defines a code interface function for each action it adds, such as MyApp.Pay.Subscription.cancel!(row, %{at: :now}). The inbox's :receive is receive_event. |
tenant_from | atom | The host's own attribute that holds the tenant, such as :site_id (an attribute, or the source attribute of a belongs_to :site), for a host that keeps sites apart without Ash multitenancy. Each create action writes its tenant there too; the row's :tenant still picks the provider keys. With Ash multitenancy on that attribute, Ash fills it and this is not needed. Not for an :inbox, which stays global. | |
belongs_to_user | atom | {atom, keyword} | A :user belongs_to relationship to the host's user resource, on :user_id, or on another attribute with {MyApp.Accounts.User, attribute: :owner_id}. A payment or a subscription gets its user from the checkout's owner, which :start_checkout takes from the actor and every sync writes again (MishkaPay.Ash.Owner); a customer's :register takes it as an input. It may be nil, for a sale with no owner. | |
resync_after | pos_integer | Hours after which a row still open at its provider is read again by an hourly AshOban trigger running :resync, in case a webhook never came: a pending or authorized payment, a subscription that has not ended, an open dispute, a draft or open bill. Runs on the inbox's queue, mishka_pay_inbox. Off unless given. | |
keep_events_for | pos_integer | :forever | 30 | For an :inbox: how many days a processed event is kept before its daily :forget trigger deletes it, or :forever. Failed and pending events are always kept. |