Initiate the 3DS Authentication

Methods

POST

Initiate the 3DS authentication

Request

Copied!
{
 "type": "object",
 "required": [
  "transactionReference",
  "merchant",
  "instruction",
  "deviceData",
  "challenge"
 ],
 "properties": {
  "transactionReference": {
   "type": "string",
   "minLength": 1,
   "maxLength": 64,
   "pattern": "[^\"' <>]*"
  },
  "merchant": {
   "type": "object",
   "required": [
    "entity"
   ],
   "properties": {
    "entity": {
     "type": "string",
     "minLength": 1,
     "maxLength": 64,
     "pattern": "^[A-Za-z0-9 ]*$"
    }
   }
  },
  "instruction": {
   "type": "object",
   "properties": {
    "value": {
     "type": "object",
     "properties": {
      "amount": {
       "type": "integer",
       "minimum": 0,
       "maximum": 99999999999
      },
      "currency": {
       "type": "string",
       "minLength": 3,
       "maxLength": 3,
       "pattern": "^[A-Z]{3}$"
      }
     },
     "required": [
      "amount",
      "currency"
     ]
    },
    "paymentInstrument": {
     "oneOf": [
      {
       "type": "object",
       "properties": {
        "type": {
         "type": "string",
         "const": "card/front"
        },
        "billingAddress": {
         "type": "object",
         "properties": {
          "city": {
           "type": "string",
           "minLength": 1,
           "maxLength": 50
          },
          "state": {
           "type": "string",
           "minLength": 1,
           "maxLength": 30
          },
          "address1": {
           "type": "string",
           "minLength": 1,
           "maxLength": 80
          },
          "address2": {
           "type": "string",
           "maxLength": 80
          },
          "address3": {
           "type": "string",
           "maxLength": 80
          },
          "postalCode": {
           "type": "string",
           "minLength": 1,
           "maxLength": 15
          },
          "countryCode": {
           "type": "string",
           "minLength": 2,
           "maxLength": 2,
           "pattern": "^[A-Z]{2}$"
          }
         },
         "required": [
          "address1",
          "city",
          "postalCode",
          "countryCode"
         ]
        },
        "cardHolderName": {
         "type": "string",
         "minLength": 1,
         "maxLength": 255
        },
        "cardExpiryDate": {
         "type": "object",
         "properties": {
          "month": {
           "type": "integer",
           "minimum": 1,
           "maximum": 12
          },
          "year": {
           "type": "integer",
           "minimum": 1,
           "maximum": 9999
          }
         },
         "required": [
          "month",
          "year"
         ]
        },
        "cardNumber": {
         "type": "string",
         "minLength": 10,
         "maxLength": 19,
         "pattern": "^[0-9]*$"
        }
       },
       "required": [
        "type",
        "cardNumber",
        "cardHolderName",
        "cardExpiryDate"
       ]
      },
      {
       "type": "object",
       "properties": {
        "type": {
         "type": "string",
         "const": "card/tokenized"
        },
        "href": {
         "type": "string",
         "minLength": 1
        }
       },
       "required": [
        "type",
        "href"
       ]
      }
     ]
    }
   },
   "required": [
    "value",
    "paymentInstrument"
   ]
  },
  "deviceData": {
   "type": "object",
   "required": [
    "acceptHeader",
    "userAgentHeader"
   ],
   "properties": {
    "acceptHeader": {
     "type": "string",
     "minLength": 1,
     "maxLength": 2048
    },
    "userAgentHeader": {
     "type": "string",
     "minLength": 1,
     "maxLength": 2048
    },
    "collectionReference": {
     "type": "string",
     "maxLength": 200
    }
   }
  },
  "challenge": {
   "type": "object",
   "required": [
    "returnUrl"
   ],
   "properties": {
    "returnUrl": {
     "type": "string",
     "minLength": 1,
     "format": "uri"
    },
    "preference": {
     "type": "string",
     "enum": [
      "noPreference",
      "noChallengeRequested",
      "challengeRequested",
      "challengeMandated"
     ]
    },
    "windowSize": {
     "type": "string",
     "enum": [
      "390x400",
      "250x400",
      "600x400",
      "fullPage"
     ]
    }
   }
  },
  "riskData": {
   "type": "object",
   "properties": {
    "account": {
     "type": "object",
     "properties": {
      "previousSuspiciousActivity": {
       "type": "boolean"
      },
      "type": {
       "type": "string",
       "enum": [
        "guestUser",
        "registeredUser",
        "federatedAccount",
        "issuerCredentials",
        "thirdPartyAuthentication",
        "fidoAuthenticator"
       ]
      },
      "history": {
       "type": "object",
       "properties": {
        "createdAt": {
         "type": "string",
         "format": "date"
        },
        "modifiedAt": {
         "type": "string",
         "format": "date"
        },
        "passwordModifiedAt": {
         "type": "string",
         "format": "date"
        },
        "paymentAccountEnrolledAt": {
         "type": "string",
         "format": "date"
        }
       }
      }
     }
    },
    "transaction": {
     "type": "object",
     "properties": {
      "reorder": {
       "type": "boolean"
      },
      "preOrderDate": {
       "type": "string",
       "format": "date"
      },
      "history": {
       "type": "object",
       "properties": {
        "attemptsLastDay": {
         "type": "integer",
         "minimum": 0,
         "maximum": 999
        },
        "attemptsLastYear": {
         "type": "integer",
         "minimum": 0,
         "maximum": 999
        },
        "completedLastSixMonths": {
         "type": "integer",
         "minimum": 0,
         "maximum": 9999
        },
        "addCardsLastDay": {
         "type": "integer",
         "minimum": 0,
         "maximum": 999
        },
        "shippingAddressFirstUsedAt": {
         "type": "string",
         "format": "date"
        }
       }
      },
      "giftCardsPurchase": {
       "type": "object",
       "properties": {
        "totalValue": {
         "type": "object",
         "properties": {
          "amount": {
           "type": "integer",
           "minimum": 0,
           "maximum": 99999999999
          },
          "currency": {
           "type": "string",
           "minLength": 3,
           "maxLength": 3,
           "pattern": "^[A-Z]{3}$"
          }
         },
         "required": [
          "amount",
          "currency"
         ]
        },
        "quantity": {
         "type": "integer",
         "minimum": 0,
         "maximum": 99
        }
       }
      }
     }
    },
    "shipping": {
     "type": "object",
     "properties": {
      "nameMatchesAccountName": {
       "type": "boolean"
      },
      "method": {
       "type": "string",
       "enum": [
        "billingAddress",
        "verifiedAddress",
        "otherAddress",
        "store",
        "digital",
        "unshippedTickets",
        "other"
       ]
      },
      "timeFrame": {
       "type": "string",
       "enum": [
        "electronic",
        "twoDaysPlus",
        "nextDay",
        "sameDay"
       ]
      },
      "email": {
       "type": "string",
       "maxLength": 254
      }
     }
    }
   }
  }
 }
}

Responses

Response schema

Copied!
{
 "type": "object",
 "properties": {
  "outcome": {
   "type": "string",
   "enum": [
    "challenged",
    "notEnrolled",
    "unavailable",
    "authenticationFailed",
    "authenticated"
   ]
  },
  "transactionReference": {
   "type": "string"
  },
  "authentication": {
   "type": "object",
   "properties": {
    "version": {
     "type": "string"
    },
    "eci": {
     "type": "string"
    },
    "authenticationValue": {
     "type": "string"
    },
    "transactionId": {
     "type": "string"
    }
   }
  },
  "challenge": {
   "type": "object",
   "properties": {
    "reference": {
     "type": "string"
    },
    "url": {
     "type": "string"
    },
    "jwt": {
     "type": "string"
    }
   }
  },
  "_links": {
   "type": "object",
   "properties": {
    "3ds:authenticate": {
     "type": "object",
     "required": [
      "href"
     ],
     "properties": {
      "href": {
       "type": "string"
      }
     }
    },
    "3ds:verify": {
     "type": "object",
     "required": [
      "href"
     ],
     "properties": {
      "href": {
       "type": "string"
      }
     }
    },
    "curies": {
     "type": "array",
     "items": {
      "type": "object",
      "properties": {
       "href": {
        "type": "string"
       },
       "templated": {
        "type": "boolean"
       },
       "name": {
        "type": "string"
       }
      }
     },
     "required": [
      "href",
      "templated",
      "name"
     ]
    }
   }
  }
 },
 "required": [
  "outcome"
 ]
}

Examples

POST
 An example of a 3DS1 Authentication request containing card details which results in a challenge response
View
POST
 An example of a 3DS1 Authentication request containing a token which results in a challenge response
View
POST
 An example of a 3DS2 Authentication request containing card details which results in an authenticated response
View
POST
 An example of a 3DS2 Authentication request containing a token which results in an authenticated response
View

Link relationship

post
 An example of a 3DS1 Authentication request containing card details which results in a challenge response 
POST https://try.access.worldpay.com/verifications/customers/3ds/authentication
Copied!
{
  "Authorization": "Basic auth",
  "Content-Type": "application/vnd.worldpay.verifications.customers-v1.hal+json"
}
Copied!
{
  "transactionReference": "uniqueId",
  "merchant": {
    "entity": "entity1"
  },
  "instruction": {
    "paymentInstrument": {
      "type": "card/front",
      "cardHolderName": "Card Holder Name",
      "cardNumber": "4444333322221111",
      "cardExpiryDate": {
        "month": 5,
        "year": 2035
      },
      "billingAddress": {
        "address1": "Address 1",
        "address2": "Address 2",
        "address3": "Address 3",
        "postalCode": "Postal Code",
        "city": "City",
        "state": "State",
        "countryCode": "GB"
      }
    },
    "value": {
      "currency": "GBP",
      "amount": 42
    }
  },
  "challenge": {
    "returnUrl": "https://your-website.com/webhook"
  },
  "deviceData": {
    "acceptHeader": "text/html",
    "userAgentHeader": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)"
  }
}

200

Copied!
{
  "Content-Type": "application/vnd.worldpay.verifications.customers-v1.hal+json"
}
Copied!
{
  "outcome": "challenged",
  "transactionReference": "uniqueId",
  "authentication": {
    "version": "1.0.2"
  },
  "challenge": {
    "reference": "123456789",
    "url": "https://0eafstag.cardinalcommerce.com/EAFService/jsp/v1/redirect",
    "jwt": "VGhpcyBpcyBhIGJhc2UgNjQgZW5jb2RlZCBleGFtcGxlIG9mIGEgM0RTICJwYXlsb2FkIg=="
  },
  "_links": {
    "curies": [
      {
        "href": "https://try.access.worldpay.com/rels/verifications/customers/3ds/{rel}",
        "templated": true,
        "name": "3ds"
      }
    ],
    "3ds:authenticate": {
      "href": "authenticate"
    },
    "3ds:verify": {
      "href": "authenticate/verify"
    }
  }
}