MishkaPay.Customer (Mishka Pay v0.0.1)

Copy Markdown View Source

A buyer the provider keeps: who they are, so a returning buyer pays without typing their details again and their payments, invoices and subscriptions hang off one record. A guarded_struct.

At Stripe a customer is an account with the customer configuration (Accounts v2, acct_..., the default) or a Customer (/v1/customers, cus_...), as the call's :api or the tenant's :customer_api (MishkaPay.Credentials) says. Every call that takes a customer id takes either kind.

Made with MishkaPay.create_customer/1, changed with MishkaPay.update_customer/1, read with MishkaPay.fetch_customer/3 and MishkaPay.list_customers/3. A host keeps the customer's :id on its own user or account.

What the caller gives:

  • :provider, :tenant: which provider, with whose keys.
  • :api: which of the provider's APIs makes it, :v2 or :v1 (Stripe's Accounts v2 or its Customers); left out, the tenant's :customer_api setting (:v2 by default). A read answers the API it was read with: a customer is read, changed and deleted with the API its id belongs to.
  • :email, :name, :phone: the buyer's details.
  • :address: where the buyer lives, a MishkaPay.Address (their billing address).
  • :default_payment_method: the payment method future invoices are paid with (pm_...), one the customer already keeps.
  • :reference: the host's own id for the buyer (a user id); it makes the idempotency key, so the same reference never makes two customers, and it comes back on the customer.
  • :metadata: extra pairs, string keys to string values.

What the provider fills in: :id, :created_at.

In a checkout, customer: %{id: "acct_..."} (or "cus_...") sells to a known customer and customer: %{email: "..."} fills in the email for a new buyer: one or the other (MishkaPay.Checkout).

Summary

Types

t()

The struct that builder/1 returns.

Functions

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

Types

t()

@type t() :: %MishkaPay.Customer{
  address: MishkaPay.Address.t() | nil,
  api: (:v2 | :v1) | nil,
  balance_transaction: MishkaPay.Customer.BalanceTransaction.t() | nil,
  created_at: DateTime.t() | nil,
  default_payment_method: String.t() | nil,
  email: String.t() | nil,
  id: String.t() | nil,
  metadata: map() | nil,
  name: String.t() | nil,
  payment_method: MishkaPay.Customer.PaymentMethod.t() | nil,
  phone: String.t() | nil,
  provider: String.t() | nil,
  reference: String.t() | nil,
  tax_id: MishkaPay.Customer.TaxId.t() | nil,
  tenant: term() | nil
}

The struct that builder/1 returns.

FieldTypeRequiredDefaultDescriptionDerives
:providerString.t() | nilnosanitize(trim) validate(string, not_empty)
:tenantterm() | nilno
:idString.t() | nilnosanitize(trim) validate(string, not_empty)
:emailString.t() | nilnosanitize(trim, downcase) validate(string, email_r)
:nameString.t() | nilnosanitize(trim) validate(string, not_empty, max_len=250)
:phoneString.t() | nilnosanitize(trim) validate(string, not_empty, max_len=30)
:addressMishkaPay.Address.t() | nilno
:api:v2 | :v1 | nilnovalidate(enum=Atom[v2::v1])<br>validator {MishkaPay.ConnectedAccount, :api}
:referenceString.t() | nilnosanitize(trim) validate(string, not_empty, max_len=200)
:metadatamap() | nilno%{}validate(map)<br>validator {MishkaPay.Checkout, :metadata}
:default_payment_methodString.t() | nilnovalidate(string)
:created_atDateTime.t() | nilnovalidate(struct)
:balance_transactionMishkaPay.Customer.BalanceTransaction.t() | nilnoOne change of a customer's balance at the provider: store credit given, a debit added, or credit used on a bill. Made with MishkaPay.adjust_customer_balance/5 and listed with MishkaPay.list_customer_balance/4. A guarded_struct.
:tax_idMishkaPay.Customer.TaxId.t() | nilnoA business buyer's tax id kept on a provider customer (txi_... at Stripe), such as an EU VAT number. The provider prints it on the customer's invoices, and a provider that counts the tax (Stripe Tax) may then charge no VAT and note a reverse charge. A guarded_struct.
:payment_methodMishkaPay.Customer.PaymentMethod.t() | nilnoA payment method a customer saved at the provider (pm_... at Stripe), such as a card, so a later invoice or subscription charges it without the buyer typing it again. A guarded_struct the provider fills in.

Functions

builder(attrs_or_input, error \\ false)

enforce_keys()

enforce_keys(field)

example()

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

keys()

keys(field)