MishkaPay.PaymentIntent (Mishka Pay v0.0.1)

Copy Markdown View Source

A payment the site's own page takes with the provider's card form (Stripe Elements), without a checkout page: made on the server with MishkaPay.create_payment_intent/1, its :client_secret handed to that buyer's browser, where the provider's script shows the form and confirms it. Read with MishkaPay.fetch_payment_intent/3, changed before it is paid with MishkaPay.update_payment_intent/1, confirmed on the server with MishkaPay.confirm_payment_intent/4 (a saved payment method), and ended with MishkaPay.cancel_payment_intent/3. A guarded_struct.

Once paid it is a payment like any other: MishkaPay.fetch_payment/3 reads it by the same :id, refunds take it, and its webhooks sync the Ash payment row.

What the caller gives:

  • :provider, :tenant: which provider, with whose keys.
  • :amount (required to make one): a Money, or %{amount: "19.99", currency: "USD"}.
  • :customer_id: the provider customer who pays (MishkaPay.create_customer/1).
  • :payment_method_id: a payment method the customer saved, to charge it without the form.
  • :capture: :automatic (the default) takes the money when it is confirmed, the provider's recommended way (Stripe's automatic_async); :automatic_sync the older way (Stripe's automatic); :manual holds it, read as :requires_capture, until MishkaPay.capture_payment/4 takes it or MishkaPay.cancel_payment_intent/3 lets it go.
  • :setup_future_usage: :off_session keeps the payment method on the customer for later charges without the buyer, :on_session for later payments the buyer makes.
  • :automatic_payment_methods: true (the default) offers the payment methods turned on in the provider's dashboard; false offers cards only.
  • :description, :metadata: kept with it.
  • :reference: the caller's own id for the sale; it makes the idempotency key, so the same reference never makes two, and it comes back on the payment. :owner: who it is for in the caller's app, as on a checkout.

What the provider fills in:

  • :id (pi_... at Stripe), :client_secret: what the provider's script in the buyer's browser takes. Send it only to that buyer's page.
  • :status: :requires_payment_method (waits for the form), :requires_confirmation, :requires_action (the buyer must pass a check, such as 3D Secure), :processing, :requires_capture (held), :succeeded or :canceled.
  • :amount_received, :failure_code and :failure_message (why the last try failed), :created_at.

A change (:id given) names only what it changes.

Summary

Types

t()

The struct that builder/1 returns.

Functions

A sample %MishkaPay.PaymentIntent{} populated from defaults + type-based fallbacks.

The statuses a payment intent can have.

Types

t()

@type t() :: %MishkaPay.PaymentIntent{
  amount: Money.t() | nil,
  amount_received: Money.t() | nil,
  automatic_payment_methods: boolean() | nil,
  capture: (:automatic | :automatic_sync | :manual) | nil,
  client_secret: String.t() | nil,
  created_at: DateTime.t() | nil,
  customer_id: String.t() | nil,
  description: String.t() | nil,
  failure_code: String.t() | nil,
  failure_message: String.t() | nil,
  id: String.t() | nil,
  metadata: map() | nil,
  owner: String.t() | nil,
  payment_method_id: String.t() | nil,
  provider: String.t(),
  reference: String.t() | nil,
  setup_future_usage: (:on_session | :off_session) | nil,
  status: atom() | nil,
  tenant: term() | nil
}

The struct that builder/1 returns.

FieldTypeRequiredDefaultDescriptionDerives
:providerString.t()yessanitize(trim) validate(not_nil_value, string, not_empty)
:tenantterm() | nilno
:idString.t() | nilnosanitize(trim) validate(string, not_empty)
:amountMoney.t() | nilnovalidator {MishkaPay.Money, :field}
:customer_idString.t() | nilnosanitize(trim) validate(string, not_empty)
:payment_method_idString.t() | nilnosanitize(trim) validate(string, not_empty)
:capture:automatic | :automatic_sync | :manual | nilnovalidate(enum=Atom[automatic::automatic_sync::manual])<br>validator {MishkaPay.Checkout, :capture}
:setup_future_usage:on_session | :off_session | nilnovalidate(enum=Atom[on_session::off_session])<br>validator {MishkaPay.PaymentIntent, :usage}
:automatic_payment_methodsboolean() | nilnovalidate(boolean)
:descriptionString.t() | nilnosanitize(trim) validate(string, max_len=1000)
:referenceString.t() | nilnosanitize(trim) validate(string, not_empty, max_len=200)
:ownerString.t() | nilnosanitize(trim) validate(string, not_empty, max_len=200)
:metadatamap() | nilno%{}validate(map)<br>validator {MishkaPay.Checkout, :metadata}
:client_secretString.t() | nilnovalidate(string)
:statusatom() | nilnovalidate(enum=Atom[requires_payment_method::requires_confirmation::requires_action::processing::requires_capture::succeeded::canceled])
:amount_receivedMoney.t() | nilnovalidator {MishkaPay.Money, :field}
:failure_codeString.t() | nilnovalidate(string)
:failure_messageString.t() | nilnovalidate(string)
:created_atDateTime.t() | nilnovalidate(struct)

Functions

builder(attrs_or_input, error \\ false)

enforce_keys()

enforce_keys(field)

example()

A sample %MishkaPay.PaymentIntent{} populated from defaults + type-based fallbacks.

keys()

keys(field)

statuses()

@spec statuses() :: [atom()]

The statuses a payment intent can have.