Integrating Paddle
Auth: API key · Partner program: not required · Setup time: about 10 minutes · Last verified: 2026-05-15
Merchant-of-record (MoR) for SaaS — Paddle is the legal seller. It handles VAT / sales-tax computation, collection, and remittance across 200+ jurisdictions; the merchant gets a single payout net of tax + Paddle fee.
Auth model
Section titled “Auth model”Bearer-token. Generate an API key under Developer Tools → Authentication in the Paddle dashboard. Sandbox + live use different keys against different hosts (sandbox-api.paddle.com vs api.paddle.com).
Required adapter quirks (read this!)
Section titled “Required adapter quirks (read this!)”Charge.amountis gross-of-tax. What the customer paid — the canonical convention for merchant-of-record adapters.Invoice.taxcarries the VAT / sales-tax that Paddle remits on the merchant’s behalf. Net-to-merchant =total - tax - paddle_fee, computed downstream if the consumer needs it.Charge.gateway = 'paddle'. Same biller convention as Chargebee / Recurly.metadata.processoris typically unset (Paddle abstracts the underlying processor entirely — the merchant doesn’t pick one).- Money is integer minor units as strings. Paddle returns
{ amount: "1000", currency_code: "USD" }= $10.00. The adapter parses the string to an integer. JPY / KRW (zero-decimal currencies) work correctly. - Transactions double as invoices. Paddle Billing’s
Transactionresource carries both the payment and the invoice data; the adapter surfaces it through bothChargeandInvoicerouters. Don’t be surprised ifCharge.id == Invoice.id.
Webhooks
Section titled “Webhooks”Configure under Developer Tools → Notifications. HMAC-SHA-256 of ${timestamp}:${rawBody} keyed with the endpoint secret; signature ships in Paddle-Signature as ts=…,h1=….
References
Section titled “References”- API reference: https://developer.paddle.com/api-reference/overview
- Webhooks + signature verification: https://developer.paddle.com/webhooks/signature-verification
- Merchant of Record overview: https://www.paddle.com/blog/what-is-merchant-of-record
opensteward.dev ·Plans and free license ·Terms ·Privacy ·support@opensteward.dev
© 2026 Falco Consulting AB. Built from open-steward/opensteward@a3961d8. This site sets no cookies, runs no analytics and loads nothing from other sites, except platform logos from Brandfetch on the Platforms page.