MishkaPay.Providers.PayPal.Mapper (Mishka Pay v0.0.1)

Copy Markdown View Source

Mishka Pay's structs to PayPal's request bodies, and PayPal's answers (Orders v2, captures, refunds, catalog products, billing plans, subscriptions and their transactions, webhook events) back to Mishka Pay's structs. Pure: no request is made here.

Summary

Functions

The Order's capture, the payment PayPal took, or nil before it is captured.

An Order read back on its own, as a checkout: what PayPal filled in and the reference.

The checkout with PayPal's answer: the Order's id, its approval page and status.

PayPal keeps one caller field, custom_id (127 characters at most): the reference alone, or, when the checkout names its owner, both as r=<reference>&o=<owner>, read back by reference/1 and owner/1. Nil when the checkout has neither.

A PayPal webhook event as a MishkaPay.Event, naming the Order it concerns (the Order itself, or the Order a capture or refund belongs to) or the subscription. live? says whose keys checked it.

One of a subscription's transactions (GET /v1/billing/subscriptions/{id}/transactions) as a MishkaPay.Invoice: what one bill took, when.

The body of POST /v2/checkout/orders: one purchase unit with the items and their total, the reference as custom_id, and the return and cancel URLs for the buyer.

The owner in a custom_id/1, nil when the checkout named none.

An Order as a MishkaPay.Payment: its id is the payment's id; its capture says whether it was paid, and the capture's refunds how much went back.

The body of POST /v1/billing/plans: the price's amount charged every interval, with no end, after a free trial of the checkout's :trial_days when it has one. A quantity is allowed, so the plan charges the amount for each one.

The body of POST /v1/catalogs/products: the product a subscription's plan sells.

The reference in a custom_id/1.

The refund with PayPal's answer: its id, status, amount and time.

The body of POST /v2/payments/captures/{id}/refund: the amount when it is not the whole.

A subscription read with its plan (?fields=plan) as a MishkaPay.Subscription: its one price from the plan's regular cycle, the period from its last and next bill, and :trialing while the plan's trial runs.

A subscription made or read back, as its checkout: the buyer approves it on PayPal's page and comes back with its id in subscription_id; once approved the checkout is complete and names it.

The body of POST /v1/billing/subscriptions: the plan, the quantity, the reference as custom_id, the buyer's email when known, and the return and cancel URLs.

The next bill of an active subscription read with its plan: the plan's price for each one of its quantity, on its next billing time. Nil when PayPal will not bill it again.

Functions

capture(order)

@spec capture(map()) :: map() | nil

The Order's capture, the payment PayPal took, or nil before it is captured.

checkout(order)

@spec checkout(map()) :: MishkaPay.Checkout.t()

An Order read back on its own, as a checkout: what PayPal filled in and the reference.

checkout(order, checkout)

@spec checkout(map(), MishkaPay.Checkout.t()) :: MishkaPay.Checkout.t()

The checkout with PayPal's answer: the Order's id, its approval page and status.

custom_id(checkout)

@spec custom_id(MishkaPay.Checkout.t()) :: String.t() | nil

PayPal keeps one caller field, custom_id (127 characters at most): the reference alone, or, when the checkout names its owner, both as r=<reference>&o=<owner>, read back by reference/1 and owner/1. Nil when the checkout has neither.

event(event, live?)

@spec event(map(), boolean()) ::
  {:ok, MishkaPay.Event.t()} | {:error, Splode.Error.t()}

A PayPal webhook event as a MishkaPay.Event, naming the Order it concerns (the Order itself, or the Order a capture or refund belongs to) or the subscription. live? says whose keys checked it.

invoice(transaction, subscription_id)

@spec invoice(map(), String.t()) ::
  {:ok, MishkaPay.Invoice.t()} | {:error, Splode.Error.t()}

One of a subscription's transactions (GET /v1/billing/subscriptions/{id}/transactions) as a MishkaPay.Invoice: what one bill took, when.

order_params(checkout)

@spec order_params(MishkaPay.Checkout.t()) :: map()

The body of POST /v2/checkout/orders: one purchase unit with the items and their total, the reference as custom_id, and the return and cancel URLs for the buyer.

owner(custom_id)

@spec owner(String.t() | nil) :: String.t() | nil

The owner in a custom_id/1, nil when the checkout named none.

payment(order)

@spec payment(map()) :: {:ok, MishkaPay.Payment.t()} | {:error, Splode.Error.t()}

An Order as a MishkaPay.Payment: its id is the payment's id; its capture says whether it was paid, and the capture's refunds how much went back.

plan_params(product_id, price, checkout)

@spec plan_params(String.t(), MishkaPay.Price.t(), MishkaPay.Checkout.t()) :: map()

The body of POST /v1/billing/plans: the price's amount charged every interval, with no end, after a free trial of the checkout's :trial_days when it has one. A quantity is allowed, so the plan charges the amount for each one.

product_params(price)

@spec product_params(MishkaPay.Price.t()) :: map()

The body of POST /v1/catalogs/products: the product a subscription's plan sells.

reference(custom_id)

@spec reference(String.t() | nil) :: String.t() | nil

The reference in a custom_id/1.

refund(answer, refund)

@spec refund(map(), MishkaPay.Refund.t()) ::
  {:ok, MishkaPay.Refund.t()} | {:error, Splode.Error.t()}

The refund with PayPal's answer: its id, status, amount and time.

refund_params(refund)

@spec refund_params(MishkaPay.Refund.t()) :: map()

The body of POST /v2/payments/captures/{id}/refund: the amount when it is not the whole.

subscription(sub)

@spec subscription(map()) ::
  {:ok, MishkaPay.Subscription.t()} | {:error, Splode.Error.t()}

A subscription read with its plan (?fields=plan) as a MishkaPay.Subscription: its one price from the plan's regular cycle, the period from its last and next bill, and :trialing while the plan's trial runs.

subscription_checkout(sub, checkout \\ nil)

@spec subscription_checkout(map(), MishkaPay.Checkout.t() | nil) ::
  MishkaPay.Checkout.t()

A subscription made or read back, as its checkout: the buyer approves it on PayPal's page and comes back with its id in subscription_id; once approved the checkout is complete and names it.

subscription_params(plan_id, price, checkout)

@spec subscription_params(String.t(), MishkaPay.Price.t(), MishkaPay.Checkout.t()) ::
  map()

The body of POST /v1/billing/subscriptions: the plan, the quantity, the reference as custom_id, the buyer's email when known, and the return and cancel URLs.

upcoming_invoice(sub)

@spec upcoming_invoice(map()) ::
  {:ok, MishkaPay.Invoice.t()} | {:error, Splode.Error.t()} | nil

The next bill of an active subscription read with its plan: the plan's price for each one of its quantity, on its next billing time. Nil when PayPal will not bill it again.