Providerhandleidingen

Tebex: instellen en beheren

Koppel custom Agovena-orderitems aan Tebex Checkout.

Op deze pagina

Werkwijze bij de provider

Agovena stuurt custom orderitems naar Tebex Checkout zonder lokale product-naar-package mapping. Elk item bevat de naam, prijs, quantity en Agovena-metadata. De provider-hosted Tebex-checkout beheert de beschikbare betaalmethoden en wordt via een redirect geopend. Agovena exposeert één checkoutoptie, tebex:tebex, met het officiële Tebex icon-mark SVG-asset.

De adapter ondersteunt ondertekende webhookverwerking, basket-naar-payment-reconciliatie, volledige refunds en provider-managed recurring payments voor één custom subscription-item. De integratie verzamelt geen kaartgegevens en bouwt geen lokaal betaalformulier.

Verificatiestatus

De adapter is production-ready voor de gedocumenteerde Agovena-integratiescope en wordt gedekt door Agovena’s gerichte provider-testsuite. Tebex Checkout API-goedkeuring, providerconfiguratie en Sandbox/live-operatie blijven verantwoordelijkheden van de merchant vóór echte klantbestellingen.

Controleer vóór echte klantbestellingen het provideraccount, de Checkout API-goedkeuring, valuta, hosted checkout, validation-webhook, payment-webhooks, refunds, recurring renewals, cancellation en resume. Codecoverage en fake-API-tests vervangen geen providerverificatie.

Vereisten

Agovena Core ^0.0.1. Het manifest noemt geen extra pakketafhankelijkheid. Een provideraccount en toegang tot de externe dienst staan los van de pakketinstallatie.

Tebex kan voorafgaande goedkeuring voor de custom Checkout API vereisen. Gebruik het officiële Tebex Contact Sales-formulier voor goedkeuring of accountadvies. Kies geen onjuiste projectcategorie om providercontrole te omzeilen.

Het pakket instellen

Configureer deze extensievelden:

Veld	Verplicht	Geheim
`project_id`	Ja	Nee
`secret_key`	Ja	Ja
`webhook_secret`	Ja	Ja

Een product-naar-Tebex-package mapping is niet nodig. De adapter stuurt custom orderitems via Tebexs /checkout endpoint. Dit manifest bevat geen sandboxschakelaar. Richt de testwerkwijze van de provider los van een liveaccount in en bewaar credentials alleen in beschermde instellingen.

Registreer het publieke HTTPS-endpoint:

text

https://store.example/webhooks/payments/tebex

Tebex ondertekent webhookrequests via X-Signature. Het endpoint beantwoordt ook Tebexs signed validation.webhook handshake met het oorspronkelijke webhook-ID en slaat deze handshake niet op als betaalevent.

Checkoutgrenzen

De provider-hosted checkout bepaalt de betaalmethoden die beschikbaar zijn voor account, valuta en klantcontext.
Agovena exposeert geen tebex:paypal, tebex:card of tebex:ideal als losse lokale methoden.
Agovena controleert de ordervaluta en het exacte itemtotaal vóór de checkout wordt aangemaakt. Orders waarvan tax, verzending, kortingen, fees of gemengde valuta niet veilig in de custom itempayload passen, worden geweigerd in plaats van met een afwijkend totaal verstuurd.
De checkoutredirect moet naar een provider-owned HTTPS Tebex Checkout-host verwijzen.
De eerste checkoutreferentie is een basket-ID. Refunds vereisen de echte tbx- payment transaction die uit een geverifieerde webhook of basket/status-reconciliatie komt.
Betaalde webhooks controleren ordermetadata, bedrag, valuta, itemidentiteit, custom order-itemmetadata, quantity en itemprijzen.

Subscriptiongrenzen

Tebex recurring checkout ondersteunt exact één subscription-item met quantity één. De adapter weigert subscriptions met niet-ondersteunde intervallen of een ingestelde trial. One-time items mogen niet met het subscription-item worden gemengd.

Tebex-cancellation wordt gemodelleerd als cancellation aan het einde van de periode. Immediate cancellation wordt niet verstuurd alsof deze wordt ondersteund. Tebex recurring-webhooks blijven leidend voor cancellation, renewal, overdue, expired en hervatte statussen. Een chargeback wordt niet als refund behandeld; deze blijft pending voor manual reconciliation wanneer Core geen aparte chargebackstatus heeft.

Refunds en foutafhandeling

De adapter ondersteunt alleen volledige refunds. Een refund moet het oorspronkelijke paymentbedrag en de oorspronkelijke valuta gebruiken. Deelrefunds worden geweigerd omdat deze integratie geen gedeeltelijk bedrag naar Tebex stuurt.

Refund-webhooks controleren transaction, bedrag, valuta en refundstatus. Refund Pending blijft processing totdat een geverifieerde webhook of statussynchronisatie de voltooiing bevestigt. Onbekende providerstatussen en afwijkende financiële data worden gedeferd voor reconciliatie en niet automatisch als approved of failed opgeslagen.

Bij een onbekende transportuitkomst van een checkout- of refundrequest bewaart Agovena de lokale reconciliatiestatus en behandelt het een retry niet blind als veilig. Provider-side idempotency moet nog in Tebex Sandbox worden geverifieerd voordat je hier operationeel op vertrouwt.