Take payments with PayPal

v0.0.1

Mishka Pay, the Elixir payment SDK, has a PayPal adapter that takes one-time payments and subscriptions through the same calls as Stripe. It is ready for production, with fewer features than the Stripe provider. This guide shows the keys, a checkout, how the buyer returns and how a payment is captured, a subscription, and what PayPal refuses. Sites in Mishka CMS choose PayPal per site, by answering PayPal keys for that site.

Before you begin

  • Mishka Pay installed. See Get Started.
  • A PayPal REST app with a client id, a secret and a webhook id (WH-...). Use PayPal's sandbox first.
  • The settings to check before going live, for the day the site moves to live PayPal keys (mode: :live).

Answer the PayPal keys

Add a clause for "paypal" to the site's keys plugin:

elixir
def credentials("paypal", site_id) do
  case MyApp.Sites.payment_settings(site_id) do
    %{
      paypal_client_id: id,
      paypal_secret: secret,
      paypal_webhook_id: webhook
    } ->
      %{
        publishable_key: id,
        secret_key: secret,
        webhook_secret: webhook,
        mode: :test
      }

    _no_keys ->
      nil
  end
end

publishable_key is the app's client id, secret_key its secret and webhook_secret the webhook id. mode is the sandbox (:test) or :live. PayPal has no shared signing secret, so webhook_secrets is ignored, and webhooks are verified by PayPal's own API.

Take a payment

The call is the one you already use. Only the provider changes.

elixir
{:ok, checkout} =
  MishkaPay.checkout(%{
    provider: "paypal",
    tenant: site.id,
    items: [
      %{
        name: "Elixir ebook",
        amount: %{amount: "19.99", currency: "USD"}
      }
    ],
    success_url: url(~p"/thanks"),
    cancel_url: url(~p"/cart"),
    reference: order.id
  })

redirect(conn, external: checkout.url)

A PayPal checkout is a PayPal Order. The buyer comes back to success_url with the Order id in the token parameter, not a Stripe-style placeholder. The reference and the checkout's owner travel together in PayPal's one caller field, custom_id, which holds 127 characters at most. A longer value is refused before any request.

Capture on return

Read the Order back with fetch_checkout("paypal", order_id, tenant). If the buyer approved it, Mishka Pay captures it at that moment, once, whoever reads it first. The payment's id is the Order's id, and :amount_captured is what the capture took.

elixir
def thanks(conn, %{"token" => order_id}) do
  {:ok, checkout} =
    MishkaPay.fetch_checkout("paypal", order_id, site.id)

  {:ok, payment} =
    MishkaPay.fetch_payment("paypal", order_id, site.id)

  # give access when payment.status is :paid
end

The capture takes PayPal a few seconds. In a LiveView, read the checkout off the request path with start_async/3, never while the page mounts.

Sell a subscription

A subscription is a checkout in mode: :subscription with exactly one item that has an interval, and trial_days for a free trial. The buyer returns with the subscription id (I-...) in subscription_id.

elixir
{:ok, checkout} =
  MishkaPay.fetch_checkout("paypal", subscription_id, site.id)

{:ok, subscription} =
  MishkaPay.fetch_subscription(
    "paypal",
    subscription_id,
    site.id
  )

MishkaPay.list_invoices("paypal", site.id,
  subscription_id: subscription_id
)

MishkaPay.cancel_subscription(
  "paypal",
  subscription_id,
  site.id,
  at: :now
)

PayPal has no cancel at the period's end, so the default cancel and resume_subscription/3 are refused. Use at: :now.

Refund

Refunds work as for Stripe. The site's refunds setting decides whether a payment can be refunded once, or many times with a reference each. See Refund, hold and capture a payment.

What PayPal refuses

Each of these answers Errors.Unsupported with the operation named. Nothing is dropped silently.

  • A subscription with more than one price, listing or searching subscriptions, changing or pausing one, and schedules.
  • Invoices and invoice items, credit notes, tax rates, tax registrations and settings, fraud tools, intents for your own card form, and customers, saved cards and the portal.
  • Connect, transfers and payouts, coupons and promotion codes, payment links and the catalog.
  • Checkout options such as discounts, allow_promotion_codes, automatic_tax, customer_creation, locale, expires_at, billing_address, tax_id_collection and invoice; merchant of record; metadata; ending a checkout.
  • Currencies PayPal does not take, and decimals in HUF, JPY and TWD.

For anything PayPal's REST API offers that Mishka Pay does not model, MishkaPay.request/1 calls any PayPal path with the site's OAuth token, for example "/v2/checkout/orders/<id>". A write's body is JSON and its reference makes the PayPal-Request-Id. PayPal has no API version or expand, so options: with either is Errors.Invalid.

Test without PayPal

With no keys and no network, MishkaPay.Test.PayPal.stub!() answers as PayPal does: Orders, captures, refunds, plans, subscriptions and webhook checks. MishkaPay.Test.PayPal.order/3 and subscription/3 put one in a state such as "APPROVED" or "ACTIVE". A webhook passes the check when its paypal-transmission-sig header is "good". See Test code that takes payments.

Next steps