Black Friday
Skip to documentation content

Developer Reference

Extend online payment gateways through Pro’s contract

The current online-gateway interface and manager are shipped in Pro, even though their PHP namespace is shared with Core. An extension must not assume those classes exist when only Free is installed or infer entitlement from interface existence.

The current online-gateway interface and manager are shipped in Pro, even though their PHP namespace is shared with Core. An extension must not assume those classes exist when only Free is installed or infer entitlement from interface existence.

The interface is KimoraPro\HotelBooking\Contracts\PaymentGatewayInterface, API version 1.0.0. Its methods are id, name, isConfigured, supportsCurrency, createPayment, parseReturn and parseWebhook. createPayment accepts a PaymentRequest and returns PaymentInitiationResult; return/webhook normalization returns GatewayNotification.

Register with the owner

The retained action is hb_payment_gateways_register, receiving the registry and manager. Registry registration accepts the adapter plus optional presentation metadata. The gateway ID is stable/lowercase and unique. Do not rename the action to a guessed canonical prefix.

Implement provider authentication, request signing and payload verification in the adapter. Use the supplied core idempotency key in PaymentRequest metadata. Do not query live room prices or accept a posted browser amount as the payment amount.

Preserve financial authority

The owner pipeline creates the local attempt from saved booking amounts and applies verified settlement to the ledger. The adapter does not write booking/payment-status or ledger rows directly. Browser return text is not authoritative: verify signature/readback and source reference, merchant/environment, amount and currency before normalizing success.

Webhook parsing uses the unmodified raw body and provided headers. Duplicate, delayed and out-of-order events must converge on the owner identity; a successful request or latest failed attempt must not fabricate or erase settled money.

Refunds are a separate contract

Payment collection support does not automatically supply a refund-execution adapter. Native PayPal/Stripe operations and the narrow Woo refund bridge have their own ownership, approval/readback and idempotence requirements. Do not route Woo-owned money through a native adapter or add an automatic refund to cancellation hooks.

Build a third-party extension with synthetic offline tests and separately authorized sandbox evidence. Missing Pro/entitlement must remain a safe unavailable state, not an instruction to patch the gate. See refund ownership.

Was this article helpful?

Your feedback helps us improve the documentation.