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::testtalks to PayPal's sandbox,:liveto PayPal.
How a payment goes
checkout/2creates 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 itscustom_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 itstokenparameter.- PayPal takes the money only when an approved Order is captured.
fetch_checkout/2andfetch_payment/2capture 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/2refunds its capture, in full or in part, as often as the site's refund rule allows (MishkaPay.ProviderKit). - A checkout in
mode: :subscriptionsells 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-...) insubscription_id; that id is also the checkout's id. - A subscription's bills are its transactions (
list_invoices/2by: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/2calls 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) asPayPal-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/3asks PayPal to check the message (verify-webhook-signature) and answers it as aMishkaPay.Eventnaming 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.
Optional. See MishkaInstaller.Event.Hook.on_dependency_error/1. Override to react.
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.
Callback implementation for MishkaInstaller.Event.Hook.unregister/0.
Types
Functions
Returns a specification to start this module under a supervisor.
See Supervisor.
@spec config() :: keyword()
@spec enable() :: okey_return() | error_return()
Callback implementation for MishkaInstaller.Event.Hook.enable/0.
@spec get() :: keyword()
Callback implementation for MishkaInstaller.Event.Hook.get/0.
Optional. See MishkaInstaller.Event.Hook.health_check/0. Override to report health.
Optional. See MishkaInstaller.Event.Hook.on_dependency_error/1. Override to react.
@spec register() :: okey_return() | error_return()
Callback implementation for MishkaInstaller.Event.Hook.register/0.
@spec restart() :: okey_return() | error_return()
Callback implementation for MishkaInstaller.Event.Hook.restart/0.
@spec start() :: okey_return() | error_return()
Callback implementation for MishkaInstaller.Event.Hook.start/0.
@spec stop() :: okey_return() | error_return()
Callback implementation for MishkaInstaller.Event.Hook.stop/0.
@spec unregister() :: okey_return() | error_return()
Callback implementation for MishkaInstaller.Event.Hook.unregister/0.