Providerhandleidingen
PayPal: instellen en beheren
Koppel PayPal Checkout Orders en opgeslagen recurring-autorisaties aan Agovena-betalingen.
Op deze pagina
Werkwijze bij de provider
PayPal wordt als één checkoutoptie aangeboden met het officiële, extension-owned PayPal SVG-icoon. Storefront-orders openen de officiële PayPal JS SDK-popup-overlay. De SDK beheert de goedkeuring en de betaalinterface; Agovena ontvangt onApprove, onCancel en onError en stuurt de klant terug naar de betaalstatuspagina. De browsercallback is geen betalingsbewijs. De signed webhook- en reconciliatieflow van Agovena blijft leidend. Niet-storefront/API-clients behouden de directe PayPal-approvalredirect.
Eenmalige orders gebruiken PayPal Checkout Orders v2. Automatische recurring producten gebruiken PayPal Vault via dezelfde Orders v2-checkout. Bij de eerste goedgekeurde capture vraagt Agovena store_in_vault = ON_SUCCESS aan. De resulterende providertoken wordt encrypted opgeslagen en latere renewal-orders gebruiken vault_id en stored_credential. Agovena Core plant de renewals. Er is geen vooraf aangemaakte PayPal Billing Plan nodig.
Refunds ondersteunen volledige en gedeeltelijke capture-refunds, ook van recurring charges. De adapter bewaart de provider capture-referentie voordat een refund wordt toegestaan. Pending, failed, dubbele en onbekende outcomes blijven aan de Agovena-refund gekoppeld voor reconciliatie.
Vereisten
Agovena Core ^0.0.1. Configureer een PayPal-applicatie, een geregistreerde webhook en de bijbehorende Sandbox- of liveomgeving. Provideraccountgoedkeuring, webhookdelivery en live transactieverwerking blijven verantwoordelijkheden van de deployment.
Lokale adapter-, API-contract- en lifecycletests dekken de implementatie. Een echte PayPal-checkout, webhookdelivery, refund, recurring renewal en merchant approval moeten per deployment worden geverifieerd en worden hier niet als uitgevoerd geclaimd.
Het pakket instellen
Stel client_id, het geheime client_secret en webhook_id in vanuit dezelfde PayPal-applicatie en omgeving. sandbox staat standaard aan. Registreer de Agovena-betaalwebhook bij die applicatie. Een webhook-ID identificeert het geregistreerde endpoint en is niet het clientgeheim of een lokaal verzonnen ondertekeningssleutel.
Maak voor automatische renewals een subscribable product capability. De eerste automatische checkout vraagt een merchant vault authorization aan. Latere renewals gebruiken de encrypted authorization die de PayPal-extension bewaart. Er is geen subscription_plan_id en geen product-level PayPal-planinstelling.
Providerspecifieke grenzen
Gebruik https://shop.example.com/webhooks/payments/paypal voor het endpoint, met de hostname van je installatie. Behoud PAYPAL-AUTH-ALGO, PAYPAL-CERT-URL, PAYPAL-TRANSMISSION-ID, PAYPAL-TRANSMISSION-SIG en PAYPAL-TRANSMISSION-TIME. De adapter accepteert alleen HTTPS PayPal API-certificaathosts en laat PayPal het volledige event controleren.
Ondersteunde payment-events zijn onder meer CHECKOUT.ORDER.APPROVED, PAYMENT.CAPTURE.*, PAYMENT.SALE.* en PayPal Vault-token-events. Capture-payloads worden gecontroleerd op bedrag en valuta van de Agovena-payment wanneer PayPal die gegevens meestuurt. Vault deletion-events trekken de lokale herbruikbare authorization in. Onbekende outcomes worden niet automatisch als Paid, Refunded of Failed opgeslagen.
Configuratiecontract
| Veld | Type | Verplicht | Geheim | Standaard |
|---|---|---|---|---|
client_id |
string |
Ja | Nee | Leeg |
client_secret |
string |
Ja | Ja | Leeg |
webhook_id |
string |
Ja | Nee | Leeg |
sandbox |
boolean |
Nee | Nee | true |
Werking en foutafhandeling
Een providerredirect is geen betalingsbewijs. Een payment wordt pas Paid na een geverifieerd PayPal-event waarvan het bedrag compatibel is. Een recurring authorization wordt pas opgeslagen na een succesvolle vaultrespons bij de capture.
Refunds gebruiken capture-ID’s voor zowel initiële als recurring Orders v2-payments. Muterende PayPal-requests krijgen Agovena’s idempotency key mee als PayPal-Request-Id. Een transportfout of malformed providerresponse laat de payment of refund in reconciliatie staan in plaats van blind opnieuw te proberen.
Configureer de webhook afzonderlijk voor Sandbox en live. Publiceer geen client secrets, webhookdata, autorisatieheaders, vault-ID’s of betaalgegevens van kopers.