Skip to main content
knowledgecenter.2checkout.com

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

Field name Type Required/Optional Description

EesToken

String

Required

The 2Pay token obtained by integrating the 2Pay.js library.

Vendor3DSReturnURL 

String

Required

The URL address to which customers are redirected after the 3DS details get validated by the bank and the order is successfully authorized.

Vendor3DSCancelURL 

String

Required

The URL address to which customers are redirected if the 3DS details were not validated or the order could not be authorized.

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"
      }
   }
}

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. 

 

  • Was this article helpful?