Paddle: instellen en beheren

Werkwijze bij de provider

Agovena gebruikt Paddle Billing overlay checkout met een order-based inline price. Het ordertotaal en de valuta worden als non-catalog price naar Paddle gestuurd. Voor een Agovena-product is geen aparte koppeling met een Paddle product-ID of price-ID nodig.

Elke gegenereerde price krijgt bij Paddle een minimum- en maximumquantity van 1. De overlay kan het aantal op de Agovena-invoice daardoor niet vermenigvuldigen.

Een gewone order gebruikt een eenmalige inline price. Een automatische subscription met één subscribable orderregel krijgt een inline billing_cycle. Paddle maakt daarna de subscription aan en beheert de terugkerende transacties zelf. Core bewaart het Paddle subscription-ID en synchroniseert de lifecycle via provider-events.

Payment methods

Paddle blijft eigenaar van de checkout, net zoals Stripe Checkout en Mollie Checkout. Agovena opent Paddle's one-page overlay met betaalmethodes zoals card, ideal, bancontact, paypal en relevante lokale methodes.

De eerste lijst gebruikt country metadata voor duidelijke lokale methodes. Voordat een gekozen methode wordt gebruikt, roept Agovena Paddle's transaction preview aan met het orderbedrag, de valuta en het billing address. Paddle's available_payment_methods-response is leidend voor beschikbaarheid op basis van land, valuta, product en accountinstellingen. Een niet-beschikbare methode wordt geweigerd voordat de betaalbare transaction wordt aangemaakt.

Voor een gekozen methode bindt Agovena de methode aan de server-created transaction en opent Paddle's overlay met allowedPaymentMethods. Paddle beheert de betaaloppervlakte en de daadwerkelijke betaalverwerking. De instelling Ingeschakelde betaalmethodes bepaalt welke afzonderlijke opties Agovena aanbiedt; de transactioncontext van Paddle blijft leidend.

Vereisten

Agovena Core ^0.0.1. Deze uitbreiding declareert geen extra pakketafhankelijkheid. Een provideraccount en toegang tot Paddle staan los van de pakketinstallatie.

De uitbreiding is productierijp voor de ondersteunde Paddle Billing-werkwijze, op voorwaarde dat het provideraccount, de publieke HTTPS-oorsprong, de webhookdestination en de credentials bij dezelfde Paddle-omgeving horen. Sandbox- en live-accountgoedkeuring blijven operationele voorwaarden.

Het pakket instellen

Een Paddle API-key maken

1. Open het Paddle Dashboard en open Authentication.
2. Controleer dat Test mode actief is zolang je de sandboxintegratie instelt.
3. Kies op het tabblad API keys voor New API key.

4. Geef de key een herkenbare naam, zoals Agovena test of Agovena production.
5. Stel een vervaldatum in en schakel rotatie in wanneer je account die opties toont.
6. Kies alleen de rechten die nodig zijn voor de Paddle-handelingen die je gebruikt. Voor subscriptions zijn subscription read/write-rechten nodig; voor adjustments zijn de bijbehorende adjustment-rechten nodig.

7. Kopieer de key rechtstreeks naar de beschermde Extension-instellingen. Publiceer de key nooit in screenshots, commits, issue trackers of chat.

Een Paddle client-side token maken

Het client-side token staat los van de server-side API-key. Het initialiseert Paddle.js op de publieke hosted-checkoutlauncher.

1. Laat Test mode actief voor een Sandbox-token, of schakel naar live mode voor een live-token.
2. Open het tabblad Client-side tokens.
3. Kies New Client-side token, geef het token een herkenbare naam en maak het aan.
4. Kopieer de tokenwaarde direct. Gebruik het test_-token met Sandbox mode en het live_-token met live mode.

Het client-side token is bedoeld voor Paddle.js en is niet de server-side API-key. Vul het dus niet in bij het veld API-key. Publiceer de volledige waarde nooit in screenshots, commits, issue trackers of chat.

Paddle instellen in Admin

1. Open Admin > Extensions en activeer Paddle.
2. Vul de Paddle Billing API-key in bij API key.
3. Vul het Paddle.js client-side token in bij Client-side token. Gebruik een test_-token in Sandbox mode en een live_-token in live mode.
4. Vul het signing secret van de Paddle notification destination in bij Webhook secret.
5. Laat Sandbox mode ingeschakeld zolang je Paddle-sandboxgegevens gebruikt.
6. Selecteer zodra de verbinding beschikbaar is de afzonderlijke methodes onder Ingeschakelde betaalmethodes. Paddle kan een methode nog steeds verwijderen voor een specifieke transaction, land, valuta, product, account of device.
7. Stel de Paddle Default payment link in op de publieke launcher-URL hieronder.
8. Sla de instellingen op en controleer de verbindingsstatus. Webhookverwerking staat altijd aan; een ondersteunde modus om webhooks uit te schakelen bestaat niet.

Er is geen veld price_map. Agovena maakt inline prices uit orderdata. Een wijziging van productnaam, SKU of intern product-ID vereist dus geen aparte Paddle-mapping.

Refunds

Paddle gebruikt de Adjustments API voor refunds. Agovena ondersteunt:

• volledige refunds via een full adjustment;
• gedeeltelijke refunds via een partial adjustment op het Paddle transaction line-item;
• bedragen in de kleinste valuta-eenheid, met de transactievaluta;
• idempotency keys voor herhaalbare refundrequests.

Een partial refund kan alleen worden uitgevoerd wanneer de Paddle transaction een geldig line-item-ID teruggeeft. De adjustment is asynchroon: gebruik de adjustment.updated webhook of transaction status reconciliation om de definitieve providerstatus te verwerken. Een geslaagde API-response is niet automatisch bewijs dat de refund definitief is goedgekeurd. Rejected en reversed adjustments blijven failed; onbekende uitkomsten blijven pending voor reconciliatie.

Subscriptions

Voor een automatische Agovena-subscription geldt:

1. De order bevat één subscribable item.
2. De checkout gebruikt renewal_mode=automatic.
3. Agovena stuurt een inline Paddle price met billing_cycle.
4. Paddle maakt een automatisch geïnde subscription aan en factureert toekomstige periods zelf.
5. Agovena slaat het Paddle subscription-ID op zodra de transaction of webhook dat levert.
6. subscription.created, subscription.updated, subscription.canceled en subscription-gerelateerde transaction-events synchroniseren de Core subscription projection.

De Core scheduler maakt voor provider-managed Paddle subscriptions geen tweede renewal order en probeert geen Stripe/Mollie-achtige off-session charge. Paddle is de billing source of truth voor die subscription.

Annuleren aan het einde van de period en onmiddellijk annuleren gebruiken de officiële Paddle subscription endpoints. Een lokale resume van een geplande period-end cancellation verwijdert de Paddle scheduled_change; het gebruikt niet de Paddle resume endpoint voor paused subscriptions.

Gemengde orders met meerdere producten worden niet stilzwijgend als één recurring Paddle price verstuurd. Gebruik voor Paddle automatic subscriptions één duidelijke subscribable orderregel.

Webhookvereisten

Registreer dit publieke HTTPS-endpoint als Paddle webhook destination:

POST https://shop.example.com/webhooks/payments/paddle

Paddle kan niet rechtstreeks naar localhost of 127.0.0.1 leveren. Kies in Paddle Webhook als notification type en kopieer het signing secret van precies deze destination naar Webhook secret. Agovena ondersteunt geen uitschakeling van webhookverwerking, omdat betrouwbare lifecycleverwerking van betalingen, refunds en subscriptions hiervan afhankelijk is.

De webhook is vereist voor een productierijpe checkout. Agovena kan GET /transactions/{transaction_id} gebruiken als initiële statuscontrole, maar webhookverwerking is nodig voor betrouwbare:

• subscription creation, updates, cancellations en payment failures;
• toekomstige Paddle-managed renewal transactions;
• asynchronous refund adjustment status;
• replay- en signature-verificatie.

Polling van een transaction is een bruikbare fallback voor een initiële checkout, maar vervangt deze subscription- en refund-events niet.

Keur vóór het toevoegen van de destination het publieke checkoutdomein goed onder Website approval in het Paddle Dashboard. Keur exact de productie- of sandbox-hostnaam goed die Paddle Checkout opent. Domeingoedkeuring staat los van de webhookdestination, maar beide zijn nodig voor een complete hosted-checkoutconfiguratie.

De adapter controleert de Paddle-Signature-header tegen de oorspronkelijke body en vergelijkt betaalde transaction-events met order, payment, valuta, totaal en line item.

Hosted checkout en lokale tunnels

Paddle voegt _ptxn toe aan de Default payment link die de transaction API teruggeeft. De Paddle-extension levert de Paddle.js-launcher op:

https://demo.agovena.com/paddle/checkout

Stel die exacte URL in bij Paddle Sandbox > Checkout settings > Default payment link voor het demo-Sandboxaccount. De launcher laadt Paddle.js en opent de transaction die met _ptxn wordt aangeduid. Gebruik hiervoor niet de Agovena-cartroute als Paddle Default payment link.

De launcher gebruikt Paddle's inline one-page checkout voor vaste Agovena-orders. Hij geeft de gekozen betaalmethode van de transaction door aan Paddle, schakelt het toevoegen van kortingen en btw-nummers uit en stuurt geslaagde, mislukte, payment-error- of gesloten checkouts naar de betalingsstatuspagina van Agovena. Mislukte checkout-events tonen een failed-status in plaats van onterecht pending. Een retryable Paddle-transaction blijft door de provider beheerd en wordt server-side verder gereconcilieerd totdat hij betaald is of een terminale status bereikt. Inline checkout toont de quantity-controls van Paddle's overlay-checkout niet. De launcher volgt de actieve storefronttaal en het light/dark theme; de omliggende frame gebruikt Agovena's surface-, border-, radius- en responsive spacing-tokens. De cross-origin iframe-inhoud blijft eigendom van Paddle en kan niet met Agovena-CSS worden gerestyled. Paddle bepaalt nog steeds zelf of bijvoorbeeld Apple Pay beschikbaar is op het apparaat van de klant en voor de transaction.

Voor lokale ontwikkeling is gewone localhost niet genoeg voor een volledige Paddle-test. Je browser kan http://localhost:8000 openen, maar Paddle-servers kunnen geen webhooks naar je computer sturen. Start een publieke HTTPS-tunnel, bijvoorbeeld:

cloudflared tunnel --url http://127.0.0.1:8000
# of
ngrok http 8000

Gebruik de gegenereerde HTTPS-oorsprong voor zowel de Default payment link (https://your-tunnel.example/paddle/checkout) als het webhookendpoint (https://your-tunnel.example/webhooks/payments/paddle). Stel de publieke applicatie-URL in op diezelfde oorsprong. Een configuratie die alleen localhost gebruikt wordt bewust niet als productierijp geaccepteerd, omdat webhookverwerking dan niet kan worden geverifieerd.

Demo-Sandboxchecklist

Voor demo.agovena.com:

1. Keur demo.agovena.com goed onder Paddle Website approval.
2. Stel https://demo.agovena.com/paddle/checkout in als Sandbox Default payment link.
3. Stel https://demo.agovena.com/webhooks/payments/paddle in als Paddle Webhook destination.
4. Gebruik samen een Sandbox API-key, een test_ client-side token en het Sandbox webhook secret.
5. Voer php artisan agovena:verify-providers paddle uit op de demo-deployment.
6. Test een eenmalige EUR-order. Gebruik voor Bancontact een Belgisch billing address en controleer of Bancontact door het Paddle-Sandboxaccount is ingeschakeld.

Meng Sandbox- en livecredentials nooit en gebruik livecredentials nooit met Sandbox mode. Gebruik tijdens de demotest geen livebetalingen.

Configuratiecontract

Bewaar geheime waarden alleen in beschermde instellingen, nooit in productbeschrijvingen, URLs of gedeelde voorbeelden.

Bronnen

• Pakketmanifest
• Paddle gateway source
• Paddle API: custom items, prices and products
• Paddle API: refunds
• Paddle API: transaction preview en beschikbare betaalmethodes
• Paddle hosted checkout URL-parameters
• Paddle API: subscriptions
• Paddle API: webhooks

Bekijk het pakket