PaymentsOS-handled Flow

Flow Overview

The PaymentsOS-handled Flow is a single-call internal flow that allows you to perform 3D Secure authentication within your Create Authorization or Create Charge request. While both the PaymentsOS-handled flow and the Provider-handled flow allow you to invoke 3D Secure authentication as part of your authorization or charge request, the PaymentsOS-handled flow differs by automating the authentication with rules you pre-configure in advance via your control center— giving you an almost hands-free approach once the rules are set.

The following image illustrates a typical PaymentsOS-handled authentication flow:

1. Your shopper clicks ‘Pay’ and proceeds to checkout.

2. You invoke the Create Authorization or Create Charge request, including the mandatory required fields as listed in Step 3: Include Mandatory API Fields in Your Request.

3. PaymentsOS will run your pre-configured 3D Secure rules:

   • If the transaction falls within your set rules – PaymentsOS will perform 3D Secure authentication.

   • If the transaction does not comply with your set rules – PaymentsOS will proceed with the authorization or charge request.

4. The result of the 3D Secure authentication will be returned in the three_d_secure_result.result object in the authorization or charge response. The flow will proceed according to the result status:

   • A Succeed authentication status - If the shopper completes the 3D Secure authentication step successfully, PaymentsOS will continue with the authorization process and send you a webhook to notify you of the result.

   • A Failed authentication status – If your 3D Secure authentication fails, the transaction will fail as well. Note that PaymentsOS will continue with the authorization or charge request by default unless you preconfigured blocking rules based on your 3D Secure authentication result.

5. The provider sends an updated transaction status to a callback endpoint URL as soon as your shopper completed the authentication process, and we redirect your shopper to the merchant_site_url

6. We send an authorization update webhook event to let you know that the status of the transaction has changed.

Enabling the Flow

To begin using the service, you must:

1. Complete all prerequisites required to enable the flow.
2. Set 3D Secure rules to enroll specific transactions in the authentication flow and subsequently enroll/block them from authorization according to the authentication result. Learn more about optimizing your authentication flow here.
3. Include the mandatory API fields in your request.

Step 1: Complete All Prerequisites to Enable the Flow

To use the single-call internal 3D Secure flow, you need to complete the following:

1. Enable the flow. You will need to contact your account manager to activate the flow in your Control Center. This will allow you to configure rules in your Decision Engine, that are designed to enroll transactions in the authentication flow.

2. Configure 3D Secure rules to enroll or exclude specific transactions from 3D Secure authentication as well as to decide whether to proceed to authorization based on the authentication status result. Learn more about optimizing the flow here.

Step 2: Set 3D Secure Authentication Rules

Head over to your Decision Engine, and choose the business unit you wish to configure 3D Secure authentication rules for. Add one or more rules via the 3D Secure and Risk Management section.

Configuring rules will ensure that PaymentsOS will send all transactions that match with them for authentication. After authentication is complete, PaymentsOS will check for additional blocking rules before proceeding with the authorization or charge request.
Learn more about optimizing your payments here.

Step 3: Include Mandatory API Fields in Your Request

In addition to fields required to perform the authorization or charge request, you will need to include 3D Secure-specific fields. You can generate a sample request with our Bodybuilder— choose Cards followed by the request type and provider, and check the *Include optional fields in the output > Show 3DS 2 fields for a PaymentsOS-handled flow * box before generating the sample request. A possible sample request including the mandatory fields will look something like this:

{
   "merchant_site_url":"http://www.abc.com/return-url",
   "payment_method":{
      "credit_card_cvv":"123",
      "token":"f78cbf5b-0e23-44e0-be11-2081791d9501",
      "type":"tokenized"
   },
   "merchant":{
      "mcc":"1234",
      "merchant_name":"string",
      "merchant_country_code":"USA"
   },
   "acquirer":{
      "acquirer_merchant_id":"string",
      "acquirer_country_code":"USA",
      "acquirer_bin":"498707"
   }
}