dj-paypal-checkout

A modern, REST-first PayPal integration for Django: Orders v2 checkout, refunds and verified webhooks, with models, signals and admin.

Status: 0.2.0. One-off payments are covered end to end: configuration, OAuth2 auth with token caching, sync/async HTTP clients, amount handling, models with persisted idempotency keys, the Orders v2 create/authorize/capture flows, refunds and voids, verified webhooks, a reconciliation command, signals, a read-only admin and a runnable demo. Subscriptions add the products/plans catalog, create/revise and lifecycle operations, verified lifecycle/payment webhooks and recurring-payment records. Not yet: Vault and Card Fields.

It has not been run against live PayPal traffic yet, and the API may still change on minor versions before 1.0. See PROGRESS.md.

Why another PayPal library?

The established django-paypal package is built on Payments Standard with IPN/PDT, i.e. PayPal's Classic stack. PayPal now recommends webhooks for all new integrations and IPN is not fired by newer payment products. Meanwhile PayPal's own paypal-server-sdk is sync-only and ships neither webhook signature verification nor the subscription plans/products catalog.

This library targets the current REST APIs and fills those gaps:

Design principles

• The server owns the amount. It is computed from your own order; the browser only ever receives a PayPal order id.
• Webhooks are the source of truth for money having moved, and handlers are idempotent — PayPal retries, and events can arrive more than once.
• Writes are idempotent, via PayPal-Request-Id, so a retry cannot double-charge.
• Decimal end to end, with currency-correct scale (never float).
• One config entry point: a single PAYPAL settings dict, read only by paypal_checkout.config.
• The DB is a local cache of PayPal state — concrete models plus a generic FK to your own order object, so admin, audit and re-sync work out of the box.

Requirements

• Python 3.11+
• Django 5.2 LTS or 6.0

Try it

example/ is a runnable sandbox checkout — two endpoints, signals, and a read-only admin:

export PAYPAL_CLIENT_ID=...      # sandbox REST app credentials
export PAYPAL_CLIENT_SECRET=...
./run_demo.sh                    # http://127.0.0.1:8000/

Development

# Run the test suite (custom runner, uses tests/test_settings.py)
python tests/runtests.py

# Coverage (what CI runs; fails below 100% via .coveragerc)
coverage run tests/runtests.py && coverage report -m

# Docs the way CI and Read the Docs build them (warnings are errors)
sphinx-build -W --keep-going -b html docs/source docs/build/html

Invoke tasks are available too: invoke test, invoke coverage, invoke docs, invoke clean.

License

MIT — see LICENSE.