🚧

Upgrade to the latest version

These docs are for version 2023-12-01. We encourage you to upgrade to version 2024-10-16 to access new features. Please see the changelog for more information.

📘

3DS is in private beta

If you are interested in using 3DS, or want help with reducing fraud and chargebacks, please contact Rainforest Support.

What is 3D Secure?

3D Secure, also known as "3DS", is an authentication protocol that can help prevent fraud and chargebacks.

→ Head over to the 3D Secure guide to learn more about how 3DS works and how to onboard your merchants to 3DS.

How to enable 3DS

When processing payins on a stored payment method, your implementation will typically be a backend API request. If your integration for processing payins on a stored payment method has the customer on session, the 3DS flow could be utilized for authentication. A Rainforest component will need to be embedded into your payment page to enable the 3DS flow with a stored payment method. This component will be completely invisible to the customer unless a 3DS challenge is required and a modal dialog will open over your page so that the customer can authenticate to the issuing bank.

This guide will walk through the steps you'll need to make to your payment integration to enable 3DS for stored payment methods.

3DS merchant onboarding

Your merchants must be onboarded to 3DS by Rainforest to run payments with 3DS protection.

→ Head over to the 3DS merchant onboarding guide for next steps.

Embed the stored payment component

First, create the payin config with the required 3DS fields:

• threeds_mode of ATTEMPT
• billing_contact.name
• billing_contact.email OR billing_contact.phone

🚧

Billing contact requirements for Visa

Visa requires the billing contact name and either email or phone to qualify for 3DS protection.

{
    "amount": 202, // $2.02
    "currency_code": "USD",
    "threeds_mode": "ATTEMPT",
  	"billing_contact": {
    	"name": "John Smith",
      "email": "[email protected]"
    }
}

The threeds_mode of ATTEMPT tells Rainforest to make a best-effort attempt to run 3DS. If the merchant is not onboarded to 3DS or the card does not support 3DS, Rainforest will continue to process an unauthenticated payment without 3DS protection.

→ Head over to the how 3DS works guide on more information on the payment flows with and without 3DS protection.

Session authentication

The page where you host the component should be secure and authenticated, so that you are sure the current user is authorized to process the payin.

Create a session to grant the stored payment component permissions to create a payin and pass the session_key into the stored payment component. The session should include at least the following statement:

curl --location 'https://api.rainforestpay.com/v1/sessions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{api_key}}' \
--data '{
    "ttl": 86400,
    "statements": [
        {
            "permissions": ["group#stored_payment_component"]
        }
    ]
}'

JavaScript bundle

Load the Rainforest payment JavaScript bundle onto your page so that you can render the stored payment component.

<script type="module" src="https://static.rainforestpay.com/sandbox.payment.js"></script>

Embed the stored payment component

Render the stored payment component as HTML, providing the previously-created session_key,payment_method_id, and payin_config_id as attributes:

<rainforest-stored-payment
    session-key="REPLACE_ME"
    payment-method-id="REPLACE_ME"
    payin-config-id="REPLACE_ME"
></rainforest-stored-payment>

This will enable Rainforest to run 3DS and then process a payin given the stored payment method and payin config.

You'll need to configure this component with the same configuration as the Payment component so Rainforest can run 3DS on your behalf.

Initiate payment processing

The component will be an invisible component unless a 3DS challenge is requested. To let Rainforest know to attempt 3DS and process the payin, call the component's submit method:

component.submit();

After the component is submitted, if the payin config threeds_mode is ATTEMPT, Rainforest will make a best-effort attempt to run 3DS. The Stored Payment Component will emit the following events if a challenge is requested in the 3DS flow.

Events

3DS mode behavior

If the payin config threeds_mode is NONE and you do not intend to run 3DS, then this component is not necessary. You can create a payin from a stored payment method via a backend API request.

Requests initiated via a backend API request will ignore the threeds_mode defined on the payin config, even if ATTEMPT was set, and the payment will process without 3DS protection. 3DS is only applicable via the Stored Payment Component because it requires frontend interactions with the customer and the issuing bank.

Event listeners

The payment component will emit one of the three events (approved, declined, or error) after attempting to process the payin. All applicable events for the Stored Payment Component are listed below.

Events