Transition guide for the 1-click purchase flow with 3D Secure

Overview

As 3D Secure (3DS) becomes a mandatory part of the payment experience fror merchants and shoppers inside the European Economic Area, we recommend migrating to API version 6.0 in order to benefit from all the advantages of 3DS 2 and not experience any loss of conversion.

Find out more about 3DS here.

Adding 3DS to the 1-click purchase flow

In order to add support for 3DS to the 1-click purchase flow for new acquisitions, the same steps needed for Credit Card payments must be covered. The full 3DS flow is detailed here.

Renewal orders payed using 1-click purchase are not required to follow the 3DS flow.

In order to adapt the existing calls, 3 steps need to be done.

Step 1 - Migrate to API 6.0

Before adding the needed parameters for 3DS, make sure you are using version 6 of the 2Checkout Public API. If you are not using our latest API version, you need to migrate. This can be done easily by updating the endpoints where the placeOrder call is made, as the request body does not change between versions. The URLs you need to use for versions 6 are:

• REST: https://api.2checkout.com/rest/ 
• SOAP: https://api.2checkout.com/soap/6.0/ 
• JSON-RPC: https://api.2checkout.com/rpc/6.0/ 

Step 2 - Adapt the request body

The first step to add support for the 3DS flow is to send three new parameters in the placeOrder call done through the 1-click purchase flow. These parameters need to be provided in the PaymentDetails object in the request.

Request body example

{
   "Language":"en",
   "Country":"US",
   "CustomerIP":"10.10.10.10",
   "Source":"Website",
   "ExternalCustomerReference":"externalCustomerId",
   "Currency":"USD",
   "MachineId":"123456789",
   "Items":[
      {
         "Code":"5DCB30C6B0",
         "Quantity":1
      }
   ],
   "BillingDetails":{
      "Email":"example@email.com",
      "FirstName":"Customer First Name",
      "LastName":"Customer Last Name",
      "CountryCode":"US",
      "State":"California",
      "City":"San Francisco",
      "Address1":"Example Street",
      "Zip":"90210"
   },
   "PaymentDetails":{
      "Type":"PREVIOUS_ORDER",
      "Currency":"GBP",
      "CustomerIP":"159.8.170.22",
      "PaymentMethod":{
         "RecurringEnabled":false,
         "RefNo":"224497479",
         "Vendor3DSReturnURL": "http://yoursuccessurl.com",
         "Vendor3DSCancelURL": "http://yourcancelurl.com",
         "CCID": "123"
      }
   }
}

Handling 1-click purchase with orders payed with wallets

If the original order used in the 1-click purchase request was payed with any other payment method outside of credit cards (PayPal, iDeal, Alipay), then the 3DS URLs and CVV are not required and must be sent as null.

{
   "Language":"en",
   "Country":"US",
   "CustomerIP":"10.10.10.10",
   "Source":"Website",
   "ExternalCustomerReference":"externalCustomerId",
   "Currency":"USD",
   "MachineId":"123456789",
   "Items":[
      {
         "Code":"5DCB30C6B0",
         "Quantity":1
      }
   ],
   "BillingDetails":{
      "Email":"example@email.com",
      "FirstName":"Customer First Name",
      "LastName":"Customer Last Name",
      "CountryCode":"US",
      "State":"California",
      "City":"San Francisco",
      "Address1":"Example Street",
      "Zip":"90210"
   },
   "PaymentDetails":{
      "Type":"PREVIOUS_ORDER",
      "Currency":"GBP",
      "CustomerIP":"159.8.170.22",
      "PaymentMethod":{
         "RecurringEnabled":false,
         "RefNo":"224497479",
         "Vendor3DSReturnURL": null,
         "Vendor3DSCancelURL": null,
         "CCID": null
      }
   }
}

Step 3 - Redirect the shopper to the 3DS page

Once the place order call has been done, the order is created with the status = PENDING, and the response object contains the necessary information to finalize the 3DS process. 

For this, the shopper needs to be redirected to the URL provided in the Href property, with the parameters provided in the Params property. The parameters need to be added based on the HTTP Method provided in the Authorize3DS object. 

Response body example

 "PaymentDetails":{
      "Type":"TEST",
      "Currency":"usd",
      "PaymentMethod":{
         "Authorize3DS":{
            "Href":"http://api.sandbox63.avangate.local/6.0/scripts/credit_card/authorize",
            "Method":"GET",
            "Params":{
               "avng8apitoken":"50dcb997be8b70bd"
            }
         },
         "FirstDigits":"4111",
         "LastDigits":"1111",
         "CardType":"visa",
         "RecurringEnabled":false,
         "Vendor3DSReturnURL":null,
         "Vendor3DSCancelURL":null
      },
      "CustomerIP":"159.8.170.22"
   },

For the above response, the URL where the shopper needs to be redirect would be http://api.sandbox63.avangate.local/6.0/scripts/credit_card/authorize?avng8apitoken=50dcb997be8b70bd.

Based on the outcome of the 3DS flow, the shopper will be redirected to the Vendor3DSReturnURL, if the flow is completed successfully. If not, the shopper will be redirected to the Vendor3DSCancelURL.

Step 4 - Validate that the order was successful 

The final step is to validate that the order was successful during the 3DS flow. For this, you have two options:

Option 1: Listen for a webhook

2Checkout provides a series of webhooks that will be triggered once the order status is updated. Setting up a listener for the Instant Payment Notifications (IPN) will allow you to receive a webhook notification once the status of an order is changed. For more information on webhooks, visit our Webhook documentation.

Option 2: Fetch the order via API

In order to validate that the order status was update and that the order can be provisioned, you can perform an API request to get the order based on its reference.