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

Overview

As 3D Secure (3DS) becomes a mandatory part of the payment experience for 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: https://www.2checkout.com/lp/psd2-sca-compliance.html

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: https://verifone.cloud/docs/2checkout/API-Integration/01Start-using-the-2Checkout-API/2Checkout-API-general-information/3D-Secure-Flow/

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

To adapt existing calls, perform the following steps:

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, migrate by updating the endpoints where the placeOrder call is made. The request body does not change between versions.

Use these URLs for version 6:

• REST: https://api.2checkout.com/rest/

• SOAP: https://api.2checkout.com/soap/6.0/

• JSON-RPC: https://api.2checkout.com/rpc/6.0/

2

Adapt the request body

Send three new parameters in the placeOrder call through the 1-click purchase flow. These parameters must be provided in the PaymentDetails.PaymentMethod object.

Parameters:

Parameter	Type	Required/Optional	Description
Vendor3DSReturnURL	String	Optional	The URL address on the merchant's side to which customers are redirected after the 3DS details get validated by the bank and the order is successfully authorized.
Vendor3DSCancelURL	String	Optional	The URL address on the merchant's side to which customers are redirected if the 3DS details were not validated or the order could not be authorized.
CCID	String	Optional	The CVV/card security code.

Request body example:

placeOrder request example.json

{
   "Language":"en",
   "Country":"US",
   "CustomerIP":"10.10.10.10",
   "Source":"Website",
   "ExternalCustomerReference":"externalCustomerId",
   "Currency":"USD",
   "MachineId":"123456789",
   "Items":[
      {
         "Code":"5DCB30C6B0",
         "Quantity":1
      }
   ],
   "BillingDetails":{
      "Email":"[email protected]",
      "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 when the original order used a non-credit-card payment: If the original order used another payment method (PayPal, iDeal, Alipay), then the 3DS URLs and CVV are not required and must be sent as null.

placeOrder request example - wallet payment.json

{
   "Language":"en",
   "Country":"US",
   "CustomerIP":"10.10.10.10",
   "Source":"Website",
   "ExternalCustomerReference":"externalCustomerId",
   "Currency":"USD",
   "MachineId":"123456789",
   "Items":[
      {
         "Code":"5DCB30C6B0",
         "Quantity":1
      }
   ],
   "BillingDetails":{
      "Email":"[email protected]",
      "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
      }
   }
}

3

Redirect the shopper to the 3DS page

After placeOrder, the order is created with status = PENDING. The response contains information to finalize the 3DS process.

Redirect the shopper to the URL in PaymentDetails.PaymentMethod.Authorize3DS.Href with the parameters provided in Params. The parameters must be added according to the HTTP Method specified in Authorize3DS.

Response body example:

placeOrder response snippet.json

"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, redirect to: http://api.sandbox63.avangate.local/6.0/scripts/credit_card/authorize?avng8apitoken=50dcb997be8b70bd

Based on the 3DS flow outcome, the shopper will be redirected to Vendor3DSReturnURL if successful, or to Vendor3DSCancelURL if not.

4

Validate that the order was successful

You have two options to validate the order after the 3DS flow:

Option 1: Listen for a webhook

2Checkout provides webhooks triggered when the order status updates. Setting up a listener for Instant Payment Notifications (IPN) lets you receive a notification when an order's status changes. More info: https://verifone.cloud/docs/2checkout/API-Integration/Webhooks/06Instant_Payment_Notification_IPN

Option 2: Fetch the order via API

Perform an API request to retrieve the order by its reference to confirm its status and determine if it can be provisioned.