Hosted payment page checkout integration

1. Documentation Type

Configuration and technical documentation.

2. Suggested Location in Sitemap

Suggested path: Configuration > Checkout > Hosted payment page checkout integration.

If the support site later adds a broader payment-method configuration branch, move the generic payment-method setup guidance there and keep this article focused on the hosted-payment checkout contract.

3. Article(s)

Title

Hosted payment page checkout integration

Content

This article is for implementation partners who configure redirect-based payment methods and need to align their hosted payment provider with the OrderCentral checkout flow.

Use this article when a buyer must leave the storefront to complete payment on an external payment page and then return to OrderCentral so checkout can apply the payment result.

When to use hosted payment page checkout

Use a hosted payment page integration when the payment provider owns the payment form, authentication, or confirmation step and the buyer must complete payment outside the storefront.

This pattern is appropriate when:

• the provider requires a redirect to its own payment page
• the provider returns the buyer to the storefront after payment is completed, failed, or cancelled
• your implementation needs OrderCentral checkout to resume with a supported payment result

Use embedded or non-hosted payment options instead when the entire payment experience stays inside the checkout page.

Prerequisites

Before you test a hosted payment method, confirm the following:

• the payment method is active and available in the buyer's storefront context
• the payment provider can return the buyer to the storefront checkout page
• your hosted payment return implementation can supply the checkout return context for the order and payment
• sandbox credentials are available for success, failure, and cancellation scenarios

Configure the payment method metadata

Hosted payment behavior depends on the payment method configuration in Payment Method custom metadata.

The key setting is the Hosted Payment Page checkbox on the payment method record. When this setting is enabled, OrderCentral treats the method as a hosted-payment flow and keeps checkout in a hosted-payment waiting state until the return outcome is applied.

Use these steps:

1. Open Salesforce Setup.
2. Open the Payment Method custom metadata records used by the storefront.
3. Open the record for the hosted payment provider.
4. Confirm that the payment method is active and visible for the intended storefront context.
5. Turn on Hosted Payment Page.
6. Save the metadata record.

Keep any provider-specific credentials, routing, and external callback setup in the payment-provider implementation that owns the hosted flow. This article covers the OrderCentral-side contract that checkout expects.

How checkout behaves before redirect and after return

At a functional level, the hosted payment checkout sequence works like this:

1. Checkout initializes the draft order, shipment, and payment context.
2. The buyer selects the hosted payment method in the payment step.
3. OrderCentral creates the order and switches checkout into the hosted-payment redirect state.
4. The buyer completes the payment on the external hosted payment page.
5. The provider returns the buyer to the storefront checkout page.
6. The return implementation publishes the payment outcome back into checkout.
7. Checkout applies the returned status and shows the resulting confirmation state.

OrderCentral uses the returned order and payment context to reconnect the hosted payment outcome to the checkout session. In Experience Cloud page state, the supported return parameters are:

• c__orderId
• c__paymentId

OrderCentral does not require one provider-specific full URL pattern in documentation. Use the storefront checkout page URL for your site and make sure the return flow preserves the order and payment identifiers when the buyer comes back.

Supported payment status messages

Hosted payment return handling listens for the exposed PaymentStatusUpdate__c Lightning Message Channel.

The supported payload fields are:

• status: required. Supported values are success, failed, and cancelled.
• message: optional. Use this for a buyer-facing status message when the provider returns an error or cancellation explanation.

Example payload:

{
    "status": "failed",
    "message": "Payment was declined by the provider."
}

Treat this message-channel payload as the supported hosted-payment return contract. Your implementation can publish it directly or through a small bridge component, but the values sent into checkout must follow this contract.

Expected outcomes for each status

After the buyer returns from the hosted payment page, checkout applies the status and updates the buyer-facing result.

Billing address behavior

The checkout payment-step experience now has billing-address information from the checkout draft. If billing data is collected or prefilled before the hosted payment step, the hosted payment implementation can use that billing-address context during initialization or provider handoff.

Document this as supported behavior for hosted payment implementations. Do not treat it as a guarantee about internal controller classes or DTO structure.

Validation checklist for sandbox testing

Use this checklist before releasing a hosted payment method:

1. Confirm that the payment method is selectable in checkout.
2. Verify that the payment method record has Hosted Payment Page enabled.
3. Start checkout and place an order with the hosted payment method.
4. Verify that checkout enters the hosted-payment redirect state and sends the buyer to the external payment page.
5. Return from the provider with c__orderId and c__paymentId and confirm that checkout resumes correctly.
6. Run a success scenario and verify that checkout shows the expected confirmation outcome.
7. Run a failed scenario and verify that checkout shows a clear failure message instead of a paid state.
8. Run a cancelled scenario and verify that checkout shows a cancellation warning instead of a paid state.
9. Switch between payment methods before placing the order and confirm that the selected payment method remains aligned with the payment record.
10. Confirm that the billing address available in the payment step matches the expected buyer data.