MishkaPay.CreditNote (Mishka Pay v0.0.1)

Copy Markdown View Source

A credit note: the tax-correct way to take back part or all of a finalized bill, instead of changing it. Made with MishkaPay.create_credit_note/1 (try it first with MishkaPay.preview_credit_note/1), read with MishkaPay.fetch_credit_note/3, listed with MishkaPay.list_credit_notes/3 and MishkaPay.list_credit_note_lines/4, and ended with MishkaPay.void_credit_note/3. A guarded_struct.

What the caller gives:

  • :provider, :tenant: which provider, with whose keys.
  • :invoice_id: the finalized bill it credits (MishkaPay.Invoice).
  • What it credits, one of them: an :amount of the whole bill, or :lines, each a MishkaPay.CreditNote.Lines (a line of the bill, or a line of its own).
  • :reason: :duplicate, :fraudulent, :order_change or :product_unsatisfactory.
  • Where the money goes, on a paid bill: :refund_amount back to the buyer's card, :credit_amount onto the customer's balance (taken off their next bills), :out_of_band_amount given back outside the provider. Together they make the note's amount. On an open bill the note lowers what is still due instead.
  • :memo: text on the note the buyer sees.
  • :reference: the caller's own id for it; it makes the idempotency key, so the same reference never credits twice, and it comes back on it.
  • :metadata: extra pairs, string keys to string values.

Every amount is in the bill's currency.

What the provider fills in: :id (cn_... at Stripe), :number, :status (:issued or :void), :type (:pre_payment when the bill was open, :post_payment when it was paid, :mixed), :customer_id, :amount (all of it, tax included), :amount_tax, the :lines, :refund_ids (the refunds it made), :pdf_url, :voided_at and :created_at. A preview answers the same, from a note not made.

Lines

Each of :lines is a MishkaPay.CreditNote.Lines, a sub_field of this struct: what the note takes back of the bill. MishkaPay.list_credit_note_lines/4 answers them too. What the caller gives, one of two kinds:

  • a line of the bill: :invoice_line_id (a MishkaPay.Invoice.Lines id, il_... at Stripe), with a :quantity of it to credit, or an :amount (a part of the line's amount);
  • a line of its own: a :name and a :unit_amount (the credit for one), with a :quantity (1 unless given).

What the provider fills in: :id (cnli_... at Stripe), :type (:invoice_line or :custom) and :amount, the line's whole credit.

Summary

Types

t()

The struct that builder/1 returns.

Functions

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

Types

t()

@type t() :: %MishkaPay.CreditNote{
  amount: Money.t() | nil,
  amount_tax: Money.t() | nil,
  created_at: DateTime.t() | nil,
  credit_amount: Money.t() | nil,
  customer_id: String.t() | nil,
  id: String.t() | nil,
  invoice_id: String.t() | nil,
  lines: [MishkaPay.CreditNote.Lines.t()] | nil,
  memo: String.t() | nil,
  metadata: map() | nil,
  number: String.t() | nil,
  out_of_band_amount: Money.t() | nil,
  pdf_url: String.t() | nil,
  provider: String.t(),
  reason:
    (:duplicate | :fraudulent | :order_change | :product_unsatisfactory) | nil,
  reference: String.t() | nil,
  refund_amount: Money.t() | nil,
  refund_ids: list() | nil,
  status: (:issued | :void) | nil,
  tenant: term() | nil,
  type: (:pre_payment | :post_payment | :mixed) | nil,
  voided_at: DateTime.t() | nil
}

The struct that builder/1 returns.

FieldTypeRequiredDefaultDescriptionDerives
:providerString.t()yessanitize(trim) validate(not_nil_value, string, not_empty)
:tenantterm() | nilno
:idString.t() | nilnovalidate(string)
:invoice_idString.t() | nilnosanitize(trim) validate(string, not_empty)
:customer_idString.t() | nilnovalidate(string)
:amountMoney.t() | nilnovalidator {MishkaPay.Money, :field}
:lines[MishkaPay.CreditNote.Lines.t()] | nilnovalidate(list)
:reason:duplicate | :fraudulent | :order_change | :product_unsatisfactory | nilnovalidate(enum=Atom[duplicate::fraudulent::order_change::product_unsatisfactory])<br>validator {MishkaPay.CreditNote, :reason}
:refund_amountMoney.t() | nilnovalidator {MishkaPay.Money, :field}
:credit_amountMoney.t() | nilnovalidator {MishkaPay.Money, :field}
:out_of_band_amountMoney.t() | nilnovalidator {MishkaPay.Money, :field}
:memoString.t() | nilnosanitize(trim) validate(string, not_empty, max_len=5000)
:referenceString.t() | nilnosanitize(trim) validate(string, not_empty, max_len=200)
:metadatamap() | nilno%{}validate(map)<br>validator {MishkaPay.Checkout, :metadata}
:numberString.t() | nilnovalidate(string)
:status:issued | :void | nilnovalidate(enum=Atom[issued::void])
:type:pre_payment | :post_payment | :mixed | nilnovalidate(enum=Atom[pre_payment::post_payment::mixed])
:amount_taxMoney.t() | nilnovalidator {MishkaPay.Money, :field}
:refund_idslist() | nilno[]validate(list)
:pdf_urlString.t() | nilnovalidate(string)
:voided_atDateTime.t() | nilnovalidate(struct)
:created_atDateTime.t() | nilnovalidate(struct)

Functions

builder(attrs_or_input, error \\ false)

enforce_keys()

enforce_keys(field)

example()

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

keys()

keys(field)