Provider guides

Tebex: configuration and operations

Connect custom Agovena order items to Tebex Checkout.

On this page

Provider workflow

Agovena sends custom order items to Tebex Checkout without local product-to-package mapping. Each item contains its name, price, quantity and Agovena metadata. The provider-hosted Tebex checkout owns the available payment methods and is opened by redirect. Agovena exposes one checkout option, tebex:tebex, with the official Tebex icon-mark SVG asset.

The adapter supports signed webhook processing, basket-to-payment reconciliation, full refunds and provider-managed recurring payments for one custom subscription item. The implementation does not collect card details or render a local payment form.

Verification status

The adapter is production-ready for the documented Agovena integration scope and covered by Agovena's focused provider test suite. Tebex Checkout API approval, provider configuration and Sandbox/live operation remain merchant responsibilities before accepting real customer orders.

Before accepting real customer orders, verify the provider account, Checkout API approval, currency, hosted checkout, validation webhook, payment webhooks, refunds, recurring renewals, cancellation and resume behavior. Code coverage and fake API tests are not a substitute for provider verification.

Requirements

Agovena Core ^0.0.1. The manifest declares no additional package dependency. Provider accounts and external service access are separate from package installation.

Tebex may require prior approval for the custom Checkout API. Use the official Tebex Contact Sales form when approval or account guidance is required. Do not select an inaccurate project category to bypass provider review.

Set up the package

Configure these extension settings:

Field	Required	Secret
`project_id`	Yes	No
`secret_key`	Yes	Yes
`webhook_secret`	Yes	Yes

No product-to-Tebex package mapping is required. The adapter sends custom order items through Tebex's /checkout endpoint. This manifest has no sandbox toggle. Configure the provider's test workflow separately from any live account and keep credentials in protected settings only.

text

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

Tebex signs webhook requests through X-Signature. The endpoint also answers Tebex's signed validation.webhook handshake with the original webhook ID and does not store that handshake as a payment event.

Checkout boundaries

The provider-hosted checkout controls the payment methods available for the account, currency and customer context.
Agovena does not expose tebex:paypal, tebex:card or tebex:ideal as separate local methods.
Agovena validates the order currency and exact item total before creating the checkout. Orders whose taxes, shipping, discounts, fees or mixed currencies cannot be represented by the custom item payload are rejected instead of being sent with a different total.
The checkout redirect must point to a provider-owned HTTPS Tebex Checkout host.
The initial checkout reference is a basket identifier. Refunds require the real tbx- payment transaction obtained from a verified webhook or basket/status reconciliation.
Paid webhook validation checks order metadata, amount, currency, item identity, custom order-item metadata, quantity and item prices.

Subscription boundaries

Tebex recurring checkout supports exactly one subscription item with quantity one. The adapter rejects subscription orders with unsupported intervals or a configured trial. One-time items cannot be mixed with the subscription item.

Tebex cancellation is modeled as period-end cancellation. Immediate cancellation is not sent as if it were supported. Tebex recurring webhooks remain authoritative for cancellation, renewal, overdue, expired and resumed states. A chargeback is not treated as a refund; it remains pending for manual reconciliation when Core has no dedicated chargeback state.

Refund and failure handling

The adapter supports full refunds only. A refund must use the original payment amount and currency. Partial refund requests are rejected because this integration does not expose a partial amount to Tebex.

Refund webhooks validate the transaction, amount, currency and refund status. Refund Pending remains processing until a verified webhook or status synchronization confirms completion. Unknown provider statuses and mismatched financial data are deferred for reconciliation instead of being marked approved or failed automatically.

If a checkout or refund request has an unknown transport outcome, Agovena preserves the local reconciliation state and avoids blindly treating a retry as safe. Provider-side idempotency behavior must still be verified in Tebex Sandbox before relying on it operationally.