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,:v2or:v1(Stripe's Accounts v2 or its Customers); left out, the tenant's:customer_apisetting (:v2by 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, aMishkaPay.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
Functions
A sample %MishkaPay.Customer{} populated from defaults + type-based fallbacks.
Types
@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.
| Field | Type | Required | Default | Description | Derives |
|---|---|---|---|---|---|
:provider | String.t() | nil | no | sanitize(trim) validate(string, not_empty) | ||
:tenant | term() | nil | no | |||
:id | String.t() | nil | no | sanitize(trim) validate(string, not_empty) | ||
:email | String.t() | nil | no | sanitize(trim, downcase) validate(string, email_r) | ||
:name | String.t() | nil | no | sanitize(trim) validate(string, not_empty, max_len=250) | ||
:phone | String.t() | nil | no | sanitize(trim) validate(string, not_empty, max_len=30) | ||
:address | MishkaPay.Address.t() | nil | no | |||
:api | :v2 | :v1 | nil | no | validate(enum=Atom[v2::v1])<br>validator {MishkaPay.ConnectedAccount, :api} | ||
:reference | String.t() | nil | no | sanitize(trim) validate(string, not_empty, max_len=200) | ||
:metadata | map() | nil | no | %{} | validate(map)<br>validator {MishkaPay.Checkout, :metadata} | |
:default_payment_method | String.t() | nil | no | validate(string) | ||
:created_at | DateTime.t() | nil | no | validate(struct) | ||
:balance_transaction | MishkaPay.Customer.BalanceTransaction.t() | nil | no | One 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_id | MishkaPay.Customer.TaxId.t() | nil | no | A 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_method | MishkaPay.Customer.PaymentMethod.t() | nil | no | A 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. |