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:
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
endpublishable_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.
{: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.
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
endThe 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.
{: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_collectionandinvoice; 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
- Capabilities by provider: the full Stripe and PayPal table.
- Take a one-time payment: the options Stripe adds.
- Errors and telemetry:
Errors.Unsupportedin detail.