Payment lifecycle handlers

1. Documentation Type

Technical documentation.

2. Suggested Location in Sitemap

Proposed new path: Technical > Checkout and payment > Custom payment methods > Payment lifecycle handlers.

If the support site keeps implementation-partner Apex extension guidance separate from general support content, place this article in that partner or developer branch and cross-link it from hosted-payment setup documentation instead of placing it in a buyer-facing checkout section.

3. Article(s)

Title

Payment lifecycle handlers for custom payment methods

Content

This article is for Apex developers and implementation partners who extend OrderCentral payment behavior with custom payment handler classes.

Use this article when a payment method needs more than checkout initialization and basic payment handling. The lifecycle handler interface adds payment-method validation during method selection, deferred capture during order creation, and reverse-capture handling when OrderCentral must roll back a payment after an order failure.

This guidance is intentionally limited to the payment-handler extension seam used by implementation projects. It does not document unrelated internal classes as a general-purpose public API.

When to implement the payment lifecycle handler interface

Use the base payment handler contract when your payment method only needs to:

initialize payment data for checkout
return the next payment action for the checkout UI
handle the immediate payment-processing step

Implement the lifecycle interface in addition to the base handler contract when your payment method must also:

decide whether the method is currently valid for the buyer and order total
perform financial capture only after checkout creates the order
reverse a completed capture if order creation later fails
keep deferred or hosted payment flows aligned with OrderCentral order status expectations

In practice, a custom handler that participates in the full checkout lifecycle should implement both IPaymentHandler and IPaymentLifecycleHandler.

What the lifecycle interface adds beyond a basic payment handler

The base payment handler contract contains two methods:

initialize(PaymentContext context)
handle(Payment payment, PaymentContext context)

The lifecycle interface adds three more methods:

validate(PaymentContext context)
capture(Payment payment, PaymentContext context)
reverseCapture(Payment payment, PaymentContext context)

These extra methods let OrderCentral check whether a payment method should be available before the buyer selects it, defer capture until the order is being created, and attempt compensation if the payment was captured but the order transaction fails afterward.

How OrderCentral resolves a custom handler

OrderCentral resolves the payment handler from the payment method metadata configuration.

Use these implementation rules:

Set the payment method metadata Handler__c field to the Apex class name for the custom handler.
Make sure the class can be instantiated with a no-argument constructor.
Make sure the class implements IPaymentHandler.
Add IPaymentLifecycleHandler only when the method must participate in validation, capture, or reverse-capture behavior.

If Handler__c is blank, invalid, or cannot be instantiated, OrderCentral falls back to DefaultPaymentHandler. That fallback prevents checkout from failing at handler lookup time, but it also means your custom lifecycle behavior will not run.

Lifecycle stages and where they occur

The payment lifecycle is split across checkout initialization, payment processing, order creation, and failure recovery.

Stage	When it runs	Handler method	What OrderCentral uses it for
Checkout initialization	When checkout prepares the payment payload for the selected method	`initialize`	Builds the initial `Payment` payload and `PaymentAction` returned to the checkout UI
Immediate processing	When checkout submits a payment-processing request before order creation	`handle`	Performs the method's immediate processing step and updates the payment record status
Payment-method validation	When OrderCentral resolves the available payment methods for the current buyer and total	`validate`	Determines whether a payment method should remain enabled in checkout
Deferred capture	During order creation when OrderCentral captures the payment tied to the shopping cart	`capture`	Finalizes the payment after the order payload has been assembled
Reverse capture	If payment capture succeeded but the surrounding order flow fails and rollback is required	`reverseCapture`	Attempts compensation so payment and order state do not diverge

What data each lifecycle stage receives

Custom handlers receive PaymentContext and, for handling or capture stages, a Payment DTO.

PaymentContext includes:

account: the buyer account in scope for the checkout
totalAmount: the amount currently being evaluated or captured

Payment includes:

paymentId: the OrderCentral payment record identifier when available
paymentMethodCode: the selected payment method code when available
externalId: the provider-specific external reference when one has already been stored
totalAmount: the amount being handled or captured

The service layer uses CapturePaymentRequest to assemble the deferred-capture call. That request carries the shopping cart, total amount, network, account, and current web order. Custom handlers do not receive that request object directly. They receive the normalized Payment and PaymentContext values produced by the service layer.

How validation affects payment-method selection

OrderCentral calls validate while preparing the payment methods for checkout.

If the handler returns valid = false, the payment method is disabled in the returned payment-method list. Use this method for deterministic eligibility checks that depend on buyer account data or the current amount.

Keep validate side-effect free. It should not perform capture, update account balances, or rely on a later rollback step.

How deferred capture works during checkout and order creation

OrderCentral does not always finalize payment during the initial payment step.

During order creation, CheckoutService builds a CapturePaymentRequest from the active shopping cart, shipment totals, account, and web order. PaymentService then:

Loads the payment record for the shopping cart.
Resolves the configured handler for that payment method.
Creates a Payment DTO from the payment record external identifier and capture amount.
Calls capture when the handler implements IPaymentLifecycleHandler.
Updates the OrderCentral payment status based on the capture result.
Relates the payment record to the web order when a web order is available in the capture request.

If capture returns failure, checkout stops order creation and raises an exception instead of leaving the order in a partially paid state.

When reverse capture runs

If payment capture succeeded but order creation later throws an exception, OrderCentral attempts a reverse capture.

This happens in the order controller error path after the failed order attempt is detected. The controller creates a new CapturePaymentRequest and calls reverseCapturePayment, which resolves the same handler and invokes reverseCapture.

Treat reverseCapture as a compensation step, not as a guarantee that external settlement can always be undone automatically. Your handler should return a clear failure result when the provider cannot reverse the capture, and it should be safe to call the method once per failed order attempt.

Built-in handler examples to model

OrderCentral currently includes two handlers that implement the lifecycle interface.

Built-in handler	What it demonstrates
Credit line	Uses `validate` to confirm the account has enough remaining credit. Uses `capture` to apply the captured amount to account outstanding balance.
Bank transfer	Demonstrates the minimum lifecycle shape when validation always succeeds and capture or reversal do not need extra business logic.

Use these built-in handlers as implementation patterns, not as templates to copy unchanged. Your custom handler should apply the same lifecycle responsibilities while preserving the financial rules of the external provider or internal payment method being integrated.

Relationship to hosted payment methods

Hosted payment page configuration and payment lifecycle handling solve different problems.

Hosted payment page settings control the buyer journey and redirect behavior.
The lifecycle handler controls server-side validation, capture timing, and rollback behavior.

If a hosted payment method already uses checkout redirect and return handling, only add the lifecycle interface when the method also needs OrderCentral-side validation, deferred capture, or reverse-capture logic after the hosted flow returns.

Keep the hosted-payment checkout contract documented in the hosted-payment article. Use this article for the Apex handler responsibilities behind that flow.

Implementation guardrails for custom handlers

Use these guardrails when building a custom lifecycle handler:

Keep validate fast and deterministic because checkout can call it while building the available payment-method list.
Keep capture aligned with OrderCentral payment status expectations: return success only when the payment is truly captured or confirmed for the intended stage.
Make reverseCapture safe for compensation scenarios after a failed order transaction.
Preserve consistent amount handling between handle, capture, and reverseCapture so the provider and OrderCentral do not disagree about the captured total.
Do not assume access to the full checkout DTO surface inside the handler. Use only the values supplied through Payment and PaymentContext unless your project has an approved extension pattern for additional context.
If account balances, credit limits, or other ledger values are affected, make sure the handler updates them only in the stage where that change should become final.

Testing and regression checklist for custom handlers

Use this checklist before promoting a custom payment handler:

Verify that the payment method metadata resolves the expected Apex class through Handler__c.
Verify that checkout still initializes the payment payload correctly when the custom handler is active.
Verify that validate disables the payment method when account or amount conditions are not met.
Verify that the method remains selectable when the same validation conditions are met.
Verify that immediate processing through handle returns the expected success or failure result and updates payment status correctly.
Verify that deferred capture succeeds during order creation when the payment should be finalized.
Verify that a failed capture blocks order creation and does not leave payment state half-complete.
Verify that reverse capture is attempted when capture succeeded but order creation later fails.
Verify that hosted payment methods still follow their expected redirect and return behavior when the lifecycle interface is added.
Verify multi-currency, account-context, and external-reference handling if your payment method depends on them.