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

Copy Markdown View Source

PayPal as a provider: one-time payments with PayPal Orders (v2), subscriptions with billing plans, reading a payment, refunds and webhooks. A mishka_installer plugin: supervise it to install it.

children = [MishkaPay.Providers.PayPal]

Keys

A site's MishkaPay.Credentials for "paypal":

  • :publishable_key: the app's client id; :secret_key: its secret. Mishka Pay gets an OAuth token with them and keeps it until shortly before it expires (MishkaPay.Helpers.TokenCache).
  • :webhook_secret: the id of the webhook in the PayPal app (WH-...): PayPal checks each message's signature itself, given that id.
  • :mode: :test talks to PayPal's sandbox, :live to PayPal.

How a payment goes

  • checkout/2 creates an Order (intent: CAPTURE) with the items and totals, the return and cancel URLs, and the reference (with the checkout's owner, when it names one) as its custom_id; the idempotency key (PayPal-Request-Id) comes from the reference. The buyer approves it on PayPal's page and comes back to the return URL with the Order id in its token parameter.
  • PayPal takes the money only when an approved Order is captured. fetch_checkout/2 and fetch_payment/2 capture an approved Order before they answer, with a key from the Order, so the return page, a webhook and a sync may all ask and it is captured once.
  • The payment's id is the Order's id. refund/2 refunds its capture, in full or in part, as often as the site's refund rule allows (MishkaPay.ProviderKit).
  • A checkout in mode: :subscription sells one recurring price: it makes a catalog product and a billing plan for it (the price every interval, after a free trial of :trial_days), then the subscription, with idempotency keys from the price and the reference. The buyer approves it on PayPal's page and comes back to the return URL with its id (I-...) in subscription_id; that id is also the checkout's id.
  • A subscription's bills are its transactions (list_invoices/2 by :subscription_id), and its next bill is the plan's price on its next billing time. PayPal cancels a subscription at once (at: :now): a cancel at the period's end, taking one back, a customer's bills and one bill by id are refused.
  • raw_request/2 calls any path of PayPal's REST API with the site's OAuth token, a write's body as JSON and its reference (with the method and path) as PayPal-Request-Id, and answers PayPal's JSON as it is ({} for an empty answer). PayPal has no API version or expand option: either one is refused before any request.
  • verify_webhook/3 asks PayPal to check the message (verify-webhook-signature) and answers it as a MishkaPay.Event naming its Order, or its subscription (a renewal's sale names it as its billing agreement).

What it refuses before any request

A currency PayPal does not take, an amount with decimals in a currency PayPal takes whole (HUF, JPY, TWD), a price by a provider id (PayPal has no stored prices on this path), a subscription checkout with more than one price, and a checkout that asks PayPal to sell as the merchant of record. Metadata has no place on a PayPal Order and is left out.

Errors

A refused card is MishkaPay.Errors.Declined, anything else PayPal refuses MishkaPay.Errors.Rejected. Both keep PayPal's debug id (the PayPal-Debug-Id header) as :request_id and the error's information_link as :doc_url, for PayPal's support and the log; their messages never show them.

config :mishka_pay, MishkaPay.Providers.PayPal, base_url: "http://localhost:..." points it at another address, such as a test server.

Tested against a stand-in that answers in PayPal's shapes, and against PayPal's own sandbox (mix test --only paypal_live).

Summary

Functions

Returns a specification to start this module under a supervisor.

Callback implementation for MishkaInstaller.Event.Hook.enable/0.

Callback implementation for MishkaInstaller.Event.Hook.get/0.

Optional. See MishkaInstaller.Event.Hook.health_check/0. Override to report health.

Callback implementation for MishkaInstaller.Event.Hook.register/0.

Callback implementation for MishkaInstaller.Event.Hook.restart/0.

Callback implementation for MishkaInstaller.Event.Hook.start/0.

Callback implementation for MishkaInstaller.Event.Hook.stop/0.

Types

error_return()

@type error_return() ::
  {:error, [%{action: atom(), field: atom(), message: String.t()}]}

okey_return()

@type okey_return() :: {:ok, struct() | map() | module() | [any()]}

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

config()

@spec config() :: keyword()

config(key)

@spec config(atom()) :: any()

enable()

@spec enable() :: okey_return() | error_return()

Callback implementation for MishkaInstaller.Event.Hook.enable/0.

get()

@spec get() :: keyword()

Callback implementation for MishkaInstaller.Event.Hook.get/0.

health_check()

@spec health_check() :: :ok | {:degraded, term()} | {:error, term()}

Optional. See MishkaInstaller.Event.Hook.health_check/0. Override to report health.

on_dependency_error(error)

@spec on_dependency_error(term()) :: term()

Optional. See MishkaInstaller.Event.Hook.on_dependency_error/1. Override to react.

register()

@spec register() :: okey_return() | error_return()

Callback implementation for MishkaInstaller.Event.Hook.register/0.

restart()

@spec restart() :: okey_return() | error_return()

Callback implementation for MishkaInstaller.Event.Hook.restart/0.

start()

@spec start() :: okey_return() | error_return()

Callback implementation for MishkaInstaller.Event.Hook.start/0.

start_link(args \\ [])

stop()

@spec stop() :: okey_return() | error_return()

Callback implementation for MishkaInstaller.Event.Hook.stop/0.

unregister()

@spec unregister() :: okey_return() | error_return()

Callback implementation for MishkaInstaller.Event.Hook.unregister/0.