Payment flow with 2Pay Token

Overview

The 2Pay tokens generated using the 2Pay.js library can be used to place orders by following the same general flow as credit card orders (including the need and handling for the 3DS authorization process). 

Availability

Available to all 2Checkout accounts.

Requirements

Using the 2Pay.js library requires a mandatory SAQ-A questionnaire to be filled in by merchants that have over 20,000 transactions per year. Below this threshold, the SAQ-A questionnaire is not mandatory but recommended.  

Payment method Object structure

2Pay Token Validity

The security limitations imposed on the 2Pay token are:

• 10 minutes time limit - orders can only be placed within 10 minutes after the token has been generated
• one order per token - once a token has been used to place an order (be it successful or not), then this is flagged as used and cannot be used again to place an order (a new token needs to be generated).

2Pay Payment Flow

The sensitive information that otherwise would have to be passed in the PaymentDetails node:

 "PaymentDetails": {
    "Type": "CC",
    "Currency": "USD",
    "PaymentMethod": {
      "CardNumber": "4111111111111111",
      "CardType": "VISA",
      "ExpirationYear": "2023",
      "ExpirationMonth": "12",
      "HolderName": "Red Doe",
      "CCID": "123",
      "Vendor3DSReturnURL": "http://yoursuccessurl.com",
      "Vendor3DSCancelURL": "http://yourcancelurl.com"
    }

are now replaced by a token generated by the 2Pay.js library.

"PaymentDetails":{
      "Type":"EES_TOKEN_PAYMENT",
      "Currency":"USD",
      "PaymentMethod":{
         "EesToken":"0cd06e64-ea85-4240-88f1-ab0edc298f08",
         "Vendor3DSReturnURL":"https:\/\/example.com",
         "Vendor3DSCancelURL":"https:\/\/example.com"
      }

By replacing the sensitive information like the credit card details with a 2Pay token, the overhead generated by handling this sensitive information and the PCI compliance requirements are greatly reduced.  

Request example

The full JSON used to place an order with credit cards would look like:

{
   "Language":"en",
   "Country":"US",
   "CustomerIP":"10.10.10.10",
   "Source":"Website",
   "ExternalCustomerReference":"externalCustomerId",
   "Currency":"USD",
   "MachineId":"123456789",
   "Items":[
      {
         "Code": "5DCB30C6B0",
         "Quantity":1
      }
   ],
   "BillingDetails":{
      "FirstName":"Customer First Name",
      "LastName":"Customer Last Name",
      "CountryCode":"US",
      "State":"California",
      "City":"San Francisco",
      "Address1":"Example Street",
      "Zip":"90210",
      "Email":"example@email.com"
   },
   "PaymentDetails":{
      "Type":"EES_TOKEN_PAYMENT",
      "Currency":"USD",
      "PaymentMethod":{
         "EesToken":"0cd06e64-ea85-4240-88f1-ab0edc298f08",
         "Vendor3DSReturnURL":"https:\/\/example.com",
         "Vendor3DSCancelURL":"https:\/\/example.com"
      }
   }
}

3D Secure Flow

For more information on the 3DS flow please refer to this article.

Integration test cases

Using the test credit cards available here, follow the next steps:

1. Build a request in order to place a new order, with all the relevant information. Make sure that when the order is sent in the API the response contains an order object (order was placed successfully)
2. Handle the 3DS flows, both when 3DS is mandatory (and the shopper needs to be redirected to authorize the transaction), as well as where this is not needed (order is created with status AUTHRECEIVED or COMPLETE)
3. If you have any additional webhook integrations, make sure that the webhooks are correctly configured and that the notifications are received and processed successfully.