3DS Hosted Page

📘

This is feature is enabled by default for new projects created after 26/02/2026. If you project was created prior to this date, please check with your CSM that this has been enabled for you.

When you attempt an authorization via your backend for a server-to-server flow, a 3DS authentication may be required. This scenario could take place if the PSP returned a soft decline, meaning that the issuer requested for authentication, or if your ProcessOut routing rules were set to trigger 3DS.

We recommend utilizing our front-end SDKs to conduct payments so this can be seamlessly handled automatically. However, we understand that this may not always be possible. Therefore, we have a dedicated hosted page flow to handle the 3DS aspect for you.

This flow is useful when either a soft decline is returned from the payment service provider or your routing rules are defined to trigger 3DS on the transaction.

Pre-requisites

• To ensure the customer has a seamless experience, you must set the return_url parameter on the invoice object during creation. This will ensure we redirect the customer back to the context of your website.

API Response

ProcessOut will return the customer_action object as part of the API response when a 3DS is required.

1. Soft decline (card.needs-authentication)

You send an authorization request without a Trigger 3DS rule applied, but the gateway requires 3DS. This is called a soft decline and is returned with the error type card.needs-authentication.

Response — HTTP 410:

{
    "customer_action": {
        "type": "redirect",
        "value": "https://checkout.processout.com/test-proj_2v4UymiXdpycKiSFO1RV5ghdbBMCrkAr/iv_3F5uBCrkAruMuCDi3dEsfSmgOCfCzE58/hosted-payment-page/?source=card_gUe2HMPvQER1l8jy74sOLNaGjH51Alga&allow_fallback_to_sale=false&authenticate_only=false&authorize_only=true&preferred_scheme=",
        "metadata": null
    },
    "error_type": "card.needs-authentication",
    "message": "The test token that was used required 3-D Secure validation to pass.",
    "outcome": "failed",
    "success": false
}

2. 3DS applied from a Trigger 3DS rule

If you require 3DS via a Trigger 3DS rule, the response is returned with the transaction object.

Response — HTTP 206:

{
    "authorized": false,
    "captured": false,
    "customer_action": {
        "type": "redirect",
        "value": "https://checkout.processout.com/test-proj_2v4UymiXdpycKiSFO1RV5ghdbBMCrkAr/iv_3F5uWCrkAreGhxpHDH7o6RouDJZnCtrT/hosted-payment-page/?source=card_yS2jWf5Mpqgqs1Ol7yzJzhmRMe87WJhC&allow_fallback_to_sale=false&authenticate_only=false&authorize_only=true&preferred_scheme=",
        "metadata": null
    },
    "outcome": "pending",
    "success": true,
    "transaction": {
        "id": "tr_3F5uWCrkArYKXOiwauxMRlvNLvsiSP1A",
        "project_id": "proj_2v4UymiXdpycKiSFO1RV5ghdbBMCrkAr",
        "customer_id": "cust_ikPT5LwBxFX8saGtHYTBMwJbZIcPW5JL",
        ...
    }
}

To continue with authentication, redirect the customer on the front end to the URL denoted in the customer_action →value parameter. This will redirect the customer to a ProcessOut hosted page, which utilizes ProcessOut's JS library to continue the flow.

This removes the need for the merchant to utilize ProcessOut's JS library on your pages to conduct the flow from the front end.

Completion handling

Once the customer completes the authentication process, they will be redirected back to the return_url set on the invoice.

It is your responsibility to handle the post payment confirmation actions. We suggest to do a server-to-server GET transaction request to understand the latest status of the transaction.

Note

We do have a one hour timeout in place for 3DS payments. If the 3DS transaction was initiated, but subsequently abandoned. We will automatically transition it to timed out failure state.