{ "openapi": "3.0.1", "info": { "title": "3DS", "description": "Protect your business and meet regulatory requirements by verifying your customer's identity with our 3DS API.", "version": "1" }, "servers": [ { "url": "https://try.access.worldpay.com", "description": "Test (Try)" }, { "url": "https://access.worldpay.com", "description": "Live" } ], "paths": { "/verifications/customers/3ds/deviceDataInitialize": { "post": { "summary": "Generate required data for 3DS Device Data Collection", "description": "Allow card issuers to perform Device Data Collection to fingerprint your customer's device.\n\n", "operationId": "deviceDataInitialize", "parameters": [ { "in": "header", "name": "Content-Type", "schema": { "type": "string", "example": "application/vnd.worldpay.verifications.customers-v1.hal+json" } }, { "in": "header", "name": "Accept", "schema": { "type": "string", "example": "application/vnd.worldpay.verifications.customers-v1.hal+json" } } ], "requestBody": { "content": { "application/vnd.worldpay.verifications.customers-v1.hal+json": { "schema": { "$ref": "#/components/schemas/3DS_deviceDataInitialize" }, "examples": { "Initialize the device data collection for a token payment instrument": { "description": "Initialize the device data collection for a token payment instrument", "value": { "transactionReference": "uniqueId", "merchant": { "entity": "default" }, "paymentInstrument": { "type": "card/tokenized", "href": "https://tokens/tokens/MTIzNDU2Nzg5MDEyMzQ1Ng" } } }, "Initialize the device data collection without a payment instrument": { "description": "Initialize the device data collection without a payment instrument", "value": { "transactionReference": "uniqueId", "merchant": { "entity": "default" } } } } } } }, "responses": { "200": { "description": "The data for the device data collection has been generated", "content": { "application/vnd.worldpay.verifications.customers-v1.hal+json": { "schema": { "$ref": "#/components/schemas/3DS_deviceDataInitialize_200_response" }, "examples": { "Initialize the device data collection for a token payment instrument": { "description": "Initialize the device data collection for a token payment instrument", "value": { "outcome": "initialized", "transactionReference": "uniqueId", "deviceDataCollection": { "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJPcmdVbml0SWQiOiJvcmcgdW5pdCBpZCIsImlzcyI6ImFwaSBpZCIsImV4cCI6MTI5NDUsImlhdCI6MTIzNDUsImp0aSI6ImU1ODY2MDYzLWVmYmMtNGY5My1iYmI3LTg1MDkzZjAxZGZjZCJ9.SUafrXef_d3915NeHygKGP5LmnQXz2Jdxjhtj5OJRsw", "url": "https://secure.worldpay.com/url/to/ddc.html", "bin": "444433" }, "_links": { "curies": [ { "href": "https://try.access.worldpay.com/rels/verifications/customers/3ds/{rel}", "templated": true, "name": "3ds" } ], "3ds:authenticate": { "href": "authenticate" } } } }, "Initialize the device data collection without a payment instrument": { "description": "Initialize the device data collection without a payment instrument", "value": { "outcome": "initialized", "transactionReference": "uniqueId", "deviceDataCollection": { "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJPcmdVbml0SWQiOiJvcmcgdW5pdCBpZCIsImlzcyI6ImFwaSBpZCIsImV4cCI6MTI5NDUsImlhdCI6MTIzNDUsImp0aSI6ImU1ODY2MDYzLWVmYmMtNGY5My1iYmI3LTg1MDkzZjAxZGZjZCJ9.SUafrXef_d3915NeHygKGP5LmnQXz2Jdxjhtj5OJRsw", "url": "https://secure.worldpay.com/url/to/ddc.html" }, "_links": { "curies": [ { "href": "https://try.access.worldpay.com/rels/verifications/customers/3ds/{rel}", "templated": true, "name": "3ds" } ], "3ds:authenticate": { "href": "authenticate" } } } } } } } }, "400": { "description": "The request has encountered validation errors", "content": { "application/vnd.worldpay.verifications.customers-v1.hal+json": { "schema": { "$ref": "#/components/schemas/3DS_deviceDataInitialize_400_response" }, "examples": { "The request is missing a mandatory field `transactionReference`": { "description": "The request does not have a mandatory field `transactionReference`", "value": { "message": "The json body provided does not match the expected schema", "errorName": "bodyDoesNotMatchSchema", "validationErrors": [ { "errorName": "stringIsTooShort", "jsonPath": "$.transactionReference", "message": "Transaction reference must be between 1 and 64 characters inclusive" } ], "_links": { "3ds:deviceDataInitialize": { "href": "$serverUrl/verifications/customers/3ds/deviceDataInitialization" }, "curies": [ { "href": "$serverUrl/rels/verifications/customers/3ds/{rel}", "templated": true, "name": "3ds" } ] } } }, "The request contains an invalid `Content-Type` header": { "description": "The request contains an invalid `Content-Type` header", "value": { "message": "Provided request contains a header with an invalid value", "errorName": "headerHasInvalidValue", "headerName": "Content-Type", "_links": { "3ds:deviceDataInitialize": { "href": "$serverUrl/verifications/customers/3ds/deviceDataInitialization" }, "curies": [ { "href": "$serverUrl/rels/verifications/customers/3ds/{rel}", "name": "3ds", "templated": true } ] } } } } } } }, "502": { "description": "Invalid response received from upstream", "content": { "application/vnd.worldpay.verifications.customers-v1.hal+json": { "schema": { "$ref": "#/components/schemas/3DS_deviceDataInitialize_502_response" }, "examples": { "An invalid response is received from upstream": { "description": "An invalid response is received from upstream", "value": { "path": "/verifications/customers/3ds/deviceDataInitialization", "status": 502, "message": "Service Unavailable", "errorName": "serviceUnavailable", "_links": { "3ds:deviceDataInitialize": { "href": "$serverUrl/verifications/customers/3ds/deviceDataInitialization" }, "curies": [ { "href": "$serverUrl/rels/verifications/customers/3ds/{rel}", "name": "3ds", "templated": true } ] } } } } } } }, "503": { "description": "The requested service is unavailable", "content": { "application/vnd.worldpay.verifications.customers-v1.hal+json": { "schema": { "$ref": "#/components/schemas/3DS_deviceDataInitialize_503_response" }, "examples": { "The requested service is unavailable": { "description": "The requested service is unavailable", "value": { "message": "Service Unavailable", "errorName": "serviceUnavailable", "_links": { "3ds:deviceDataInitialize": { "href": "$serverUrl/verifications/customers/3ds/deviceDataInitialization" }, "curies": [ { "href": "$serverUrl/rels/verifications/customers/3ds/{rel}", "name": "3ds", "templated": true } ] } } } } } } } } } }, "/verifications/customers/3ds/authenticate": { "post": { "summary": "Initiate the 3DS authentication", "description": "Authenticate your customer by submitting order and risk data.\n\n", "operationId": "authenticate", "parameters": [ { "in": "header", "name": "Content-Type", "schema": { "type": "string", "example": "application/vnd.worldpay.verifications.customers-v1.hal+json" } }, { "in": "header", "name": "Accept", "schema": { "type": "string", "example": "application/vnd.worldpay.verifications.customers-v1.hal+json" } } ], "requestBody": { "content": { "application/vnd.worldpay.verifications.customers-v1.hal+json": { "schema": { "$ref": "#/components/schemas/3DS_authenticate" }, "examples": { "An example of a 3DS2 Authentication request containing card details which results in an authenticated response": { "description": "An example of a 3DS2 Authentication request containing card details which results in an authenticated response", "value": { "transactionReference": "uniqueId", "merchant": { "entity": "default" }, "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://returnUrl.com" }, "deviceData": { "acceptHeader": "text/html", "userAgentHeader": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)", "collectionReference": "reference" }, "riskData": { "account": { "previousSuspiciousActivity": true, "type": "guestUser", "history": { "createdAt": "2002-11-23", "modifiedAt": "2003-10-21", "passwordModifiedAt": "2005-02-10", "paymentAccountEnrolledAt": "2004-09-02" } }, "transaction": { "reorder": true, "preOrderDate": "2010-08-04", "history": { "attemptsLastDay": 2, "attemptsLastYear": 6, "completedLastSixMonths": 7, "addCardsLastDay": 5, "shippingAddressFirstUsedAt": "2009-02-22" }, "giftCardsPurchase": { "totalValue": { "currency": "GBP", "amount": 10 }, "quantity": 4 } }, "shipping": { "nameMatchesAccountName": false, "method": "digital", "timeFrame": "electronic", "email": "customer@website.com" } } } }, "An example of a 3DS2 Authentication request containing a token which results in an authenticated response": { "description": "An example of a 3DS2 Authentication request containing a token which results in an authenticated response", "value": { "transactionReference": "uniqueId", "merchant": { "entity": "default" }, "instruction": { "paymentInstrument": { "type": "card/tokenized", "href": "https://tokens/tokens/MTIzNDU2Nzg5MDEyMzQ1Ng" }, "value": { "currency": "GBP", "amount": 42 } }, "challenge": { "returnUrl": "https://returnUrl.com" }, "deviceData": { "acceptHeader": "text/html", "userAgentHeader": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)", "collectionReference": "reference" }, "riskData": { "account": { "previousSuspiciousActivity": true, "type": "guestUser", "history": { "createdAt": "2002-11-23", "modifiedAt": "2003-10-21", "passwordModifiedAt": "2005-02-10", "paymentAccountEnrolledAt": "2004-09-02" } }, "transaction": { "reorder": true, "preOrderDate": "2010-08-04", "history": { "attemptsLastDay": 2, "attemptsLastYear": 6, "completedLastSixMonths": 7, "addCardsLastDay": 5, "shippingAddressFirstUsedAt": "2009-02-22" }, "giftCardsPurchase": { "totalValue": { "currency": "GBP", "amount": 10 }, "quantity": 4 } }, "shipping": { "nameMatchesAccountName": false, "method": "digital", "timeFrame": "electronic", "email": "customer@website.com" } } } } } } } }, "responses": { "200": { "description": "The authentication has been created", "content": { "application/vnd.worldpay.verifications.customers-v1.hal+json": { "schema": { "$ref": "#/components/schemas/3DS_authenticate_200_response" }, "examples": { "An example of a 3DS2 Authentication request containing card details which results in an authenticated response": { "description": "An example of a 3DS2 Authentication request containing card details which results in an authenticated response", "value": { "outcome": "authenticated", "transactionReference": "uniqueId", "authentication": { "version": "2.1.0", "authenticationValue": "authValue", "eci": "02", "transactionId": "transaction1234567890" } } }, "An example of a 3DS2 Authentication request containing a token which results in an authenticated response": { "description": "An example of a 3DS2 Authentication request containing a token which results in an authenticated response", "value": { "outcome": "authenticated", "transactionReference": "uniqueId", "authentication": { "version": "2.1.0", "authenticationValue": "authValue", "eci": "02", "transactionId": "transaction1234567890" } } } } } } }, "400": { "description": "The request has encountered validation errors", "content": { "application/vnd.worldpay.verifications.customers-v1.hal+json": { "schema": { "$ref": "#/components/schemas/3DS_authenticate_400_response" }, "examples": { "The request is missing a mandatory field `merchant`": { "description": "The request does not have a mandatory field `merchant`", "value": { "message": "The json body provided does not match the expected schema", "errorName": "bodyDoesNotMatchSchema", "validationErrors": [ { "errorName": "fieldIsMissing", "jsonPath": "$.merchant", "message": "Merchant must be provided" } ], "_links": { "3ds:authenticate": { "href": "$serverUrl/verifications/customers/3ds/authentication" }, "3ds:verify": { "href": "$serverUrl/verifications/customers/3ds/verification" }, "curies": [ { "href": "$serverUrl/rels/verifications/customers/3ds/{rel}", "templated": true, "name": "3ds" } ] } } }, "The request contains an invalid `Content-Type` header": { "description": "The request contains an invalid `Content-Type` header", "value": { "message": "Provided request contains a header with an invalid value", "errorName": "headerHasInvalidValue", "headerName": "Content-Type", "_links": { "3ds:authenticate": { "href": "$serverUrl/verifications/customers/3ds/authentication" }, "3ds:verify": { "href": "$serverUrl/verifications/customers/3ds/verification" }, "curies": [ { "href": "$serverUrl/rels/verifications/customers/3ds/{rel}", "name": "3ds", "templated": true } ] } } }, "The request is using an invalid HTTP method": { "description": "The request is using an invalid HTTP method", "value": { "errorName": "methodNotAllowed", "allowedMethods": [ "POST" ], "message": "Method GET not allowed for this request", "_links": { "3ds:authenticate": { "href": "$serverUrl/verifications/customers/3ds/authentication" }, "3ds:verify": { "href": "$serverUrl/verifications/customers/3ds/verification" }, "curies": [ { "href": "$serverUrl/rels/verifications/customers/3ds/{rel}", "name": "3ds", "templated": true } ] } } } } } } }, "502": { "description": "Invalid response received from upstream", "content": { "application/vnd.worldpay.verifications.customers-v1.hal+json": { "schema": { "$ref": "#/components/schemas/3DS_authenticate_502_response" }, "examples": { "An invalid response is received from upstream": { "description": "An invalid response is received from upstream", "value": { "path": "/verifications/customers/3ds/authentication", "status": 502, "message": "Service Unavailable", "errorName": "serviceUnavailable", "_links": { "3ds:authenticate": { "href": "$serverUrl/verifications/customers/3ds/authentication" }, "3ds:verify": { "href": "$serverUrl/verifications/customers/3ds/verification" }, "curies": [ { "href": "$serverUrl/rels/verifications/customers/3ds/{rel}", "templated": true, "name": "3ds" } ] } } } } } } }, "503": { "description": "The requested service is unavailable", "content": { "application/vnd.worldpay.verifications.customers-v1.hal+json": { "schema": { "$ref": "#/components/schemas/3DS_authenticate_503_response" }, "examples": { "The requested service is unavailable": { "description": "The requested service is unavailable", "value": { "path": "/verifications/customers/3ds/authentication", "status": 503, "message": "Service Unavailable", "errorName": "serviceUnavailable", "_links": { "3ds:authenticate": { "href": "$serverUrl/verifications/customers/3ds/authentication" }, "3ds:verify": { "href": "$serverUrl/verifications/customers/3ds/verification" }, "curies": [ { "href": "$serverUrl/rels/verifications/customers/3ds/{rel}", "templated": true, "name": "3ds" } ] } } } } } } } } } }, "/verifications/customers/3ds/verification": { "post": { "summary": "Verify the 3DS challenge response", "description": "Verify the results of a challenged authentication.\n\n", "operationId": "verify", "parameters": [ { "in": "header", "name": "Content-Type", "schema": { "type": "string", "example": "application/vnd.worldpay.verifications.customers-v1.hal+json" } }, { "in": "header", "name": "Accept", "schema": { "type": "string", "example": "application/vnd.worldpay.verifications.customers-v1.hal+json" } } ], "requestBody": { "content": { "application/vnd.worldpay.verifications.customers-v1.hal+json": { "schema": { "$ref": "#/components/schemas/3DS_verify" }, "examples": { "An example of a 3DS Verification request": { "description": "An example of a 3DS Verification request", "value": { "transactionReference": "sRMPWCQoQrEiVxehTnu0", "merchant": { "entity": "default" }, "challenge": { "reference": "uniqueChallengeRef12" } } } } } } }, "responses": { "200": { "description": "The challenge was successful - obtain the authentication data for onward use", "content": { "application/vnd.worldpay.verifications.customers-v1.hal+json": { "schema": { "$ref": "#/components/schemas/3DS_verify_200_response" }, "examples": { "An example of a 3DS Verification request": { "description": "An example of a 3DS Verification request", "value": { "outcome": "authenticated", "transactionReference": "sRMPWCQoQrEiVxehTnu0", "authentication": { "version": "1.0.2", "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAAAA=", "eci": "05", "transactionId": "k4Vf36ijnJX54kwHQNqUr8" }, "_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" } } } } } } } }, "400": { "description": "The request has encountered validation errors", "content": { "application/vnd.worldpay.verifications.customers-v1.hal+json": { "schema": { "$ref": "#/components/schemas/3DS_verify_400_response" }, "examples": { "The request contains invalid characters": { "description": "The request contains invalid characters in `transactionReference` and `merchant.entity` fields", "value": { "path": "/verifications/customers/3ds/verification", "status": 400, "message": "The json body provided does not match the expected schema", "errorName": "bodyDoesNotMatchSchema", "validationErrors": [ { "errorName": "stringFailedRegexCheck", "jsonPath": "$.merchant.entity", "message": "Entity must be alphanumeric with optional spaces" }, { "errorName": "stringFailedRegexCheck", "jsonPath": "$.transactionReference", "message": "Transaction reference characters must be alphanumeric or one of the following: _!@#$%()*=-.:;?[]{}~`/+" } ], "_links": { "3ds:authenticate": { "href": "$serverUrl/verifications/customers/3ds/authentication" }, "3ds:verify": { "href": "$serverUrl/verifications/customers/3ds/verification" }, "curies": [ { "href": "$serverUrl/rels/verifications/customers/3ds/{rel}", "templated": true, "name": "3ds" } ] } } }, "The request contains an invalid `Content-Type` header": { "description": "The request contains an invalid `Content-Type` header", "value": { "path": "/verifications/customers/3ds/verification", "status": 400, "message": "Provided request contains a header with an invalid value", "errorName": "headerHasInvalidValue", "headerName": "Content-Type", "_links": { "3ds:authenticate": { "href": "$serverUrl/verifications/customers/3ds/authentication" }, "3ds:verify": { "href": "$serverUrl/verifications/customers/3ds/verification" }, "curies": [ { "href": "$serverUrl/rels/verifications/customers/3ds/{rel}", "name": "3ds", "templated": true } ] } } }, "The request is using an invalid HTTP method": { "description": "The request is using an invalid HTTP method", "value": { "message": "Method GET not allowed for this request", "errorName": "methodNotAllowed", "allowedMethods": [ "POST" ], "_links": { "3ds:authenticate": { "href": "$serverUrl/verifications/customers/3ds/authentication" }, "3ds:verify": { "href": "$serverUrl/verifications/customers/3ds/verification" }, "curies": [ { "href": "$serverUrl/rels/verifications/customers/3ds/{rel}", "templated": true, "name": "3ds" } ] } } } } } } }, "502": { "description": "Invalid response received from upstream", "content": { "application/vnd.worldpay.verifications.customers-v1.hal+json": { "schema": { "$ref": "#/components/schemas/3DS_authenticate_502_response" }, "examples": { "An invalid response is received from upstream": { "description": "An invalid response is received from upstream", "value": { "path": "/verifications/customers/3ds/authentication", "status": 502, "message": "Service Unavailable", "errorName": "serviceUnavailable", "_links": { "3ds:authenticate": { "href": "$serverUrl/verifications/customers/3ds/authentication" }, "3ds:verify": { "href": "$serverUrl/verifications/customers/3ds/verification" }, "curies": [ { "href": "$serverUrl/rels/verifications/customers/3ds/{rel}", "templated": true, "name": "3ds" } ] } } } } } } }, "503": { "description": "The requested service is unavailable", "content": { "application/vnd.worldpay.verifications.customers-v1.hal+json": { "schema": { "$ref": "#/components/schemas/3DS_authenticate_503_response" }, "examples": { "The requested service is unavailable": { "description": "The requested service is unavailable", "value": { "path": "/verifications/customers/3ds/authentication", "status": 503, "message": "Service Unavailable", "errorName": "serviceUnavailable", "_links": { "3ds:authenticate": { "href": "$serverUrl/verifications/customers/3ds/authentication" }, "3ds:verify": { "href": "$serverUrl/verifications/customers/3ds/verification" }, "curies": [ { "href": "$serverUrl/rels/verifications/customers/3ds/{rel}", "templated": true, "name": "3ds" } ] } } } } } } } } } } }, "components": { "schemas": { "3DS_deviceDataInitialize": { "required": [ "transactionReference", "merchant" ], "type": "object", "properties": { "transactionReference": { "maxLength": 64, "minLength": 1, "pattern": "^[-A-Za-z0-9_!@#$%()*=.:;?\\[\\]{}~`/+]*$", "type": "string", "description": "A unique reference for authentication. For example, e-commerce order code." }, "merchant": { "required": [ "entity" ], "type": "object", "description": "An object that contains information about the merchant and API level configuration.", "properties": { "entity": { "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9 ]*$", "type": "string", "description": "Used to route the request in Access Worldpay, created as part of on-boarding." } } }, "paymentInstrument": { "oneOf": [ { "$ref": "#/components/schemas/card_front" }, { "$ref": "#/components/schemas/card_tokenized" } ], "discriminator": { "mapping": { "card/front": "#/components/schemas/card_front", "card/tokenized": "#/components/schemas/card_tokenized" }, "propertyName": "type" } } } }, "3DS_deviceDataInitialize_200_response": { "required": [ "outcome", "transactionReference", "deviceDataCollection" ], "type": "object", "properties": { "outcome": { "type": "string", "format": "initialized", "description": "Outcome of the device data initialization request" }, "transactionReference": { "maxLength": 64, "minLength": 1, "type": "string", "description": "A unique reference for authentication. For example, e-commerce order code." }, "deviceDataCollection": { "required": [ "jwt", "url" ], "type": "object", "description": "Object containing device data collection related information", "properties": { "jwt": { "maxLength": 2048, "minLength": 1, "type": "string", "description": "A digitally signed token that contains additional details required for DDC." }, "url": { "maxLength": 2048, "minLength": 1, "type": "string", "description": "A `POST` action on the DDC form. Used to redirect to the issuers DDC page." }, "bin": { "maxLength": 6, "minLength": 6, "type": "string", "description": "First six digits of the card number (Bank Identification Number), used as part of DDC." } } } } }, "3DS_deviceDataInitialize_400_response": { "required": [ "message", "errorName" ], "type": "object", "properties": { "path": { "type": "string", "maxLength": 2048, "minLength": 1, "description": "The request URI path" }, "status": { "maxLength": 3, "minLength": 3, "type": "integer", "description": "The HTTP status returned from server" }, "message": { "type": "string", "maxLength": 2048, "minLength": 1, "description": "The error description message" }, "errorName": { "type": "string", "maxLength": 2048, "minLength": 1, "description": "The unique error name" }, "headerName": { "type": "string", "maxLength": 2048, "minLength": 1, "description": "The name of the header containing invalid value" }, "allowedMethods": { "type": "array", "description": "List of HTTP methods that are allowed", "items": { "type": "string" } }, "validationErrors": { "required": [ "errorName", "jsonPath", "message" ], "type": "object", "description": "Object containing details of validation errors occurred", "properties": { "errorName": { "maxLength": 2048, "minLength": 1, "type": "string", "description": "Unique name of the validation error" }, "jsonPath": { "maxLength": 2048, "minLength": 1, "type": "string", "description": "Location of the field in request body for which the error occurred" }, "message": { "maxLength": 2048, "minLength": 1, "type": "string", "description": "Error description message" } } } } }, "3DS_deviceDataInitialize_502_response": { "required": [ "message", "errorName" ], "type": "object", "properties": { "path": { "type": "string", "maxLength": 2048, "minLength": 1, "description": "The request URI path" }, "status": { "maxLength": 3, "minLength": 3, "type": "integer", "description": "The HTTP status returned from server" }, "message": { "type": "string", "maxLength": 2048, "minLength": 1, "description": "The error description message" }, "errorName": { "type": "string", "maxLength": 2048, "minLength": 1, "description": "The unique error name" } } }, "3DS_deviceDataInitialize_503_response": { "required": [ "message", "errorName" ], "type": "object", "properties": { "path": { "type": "string", "maxLength": 2048, "minLength": 1, "description": "The request URI path" }, "status": { "maxLength": 3, "minLength": 3, "type": "integer", "description": "The HTTP status returned from server" }, "message": { "type": "string", "maxLength": 2048, "minLength": 1, "description": "The error description message" }, "errorName": { "type": "string", "maxLength": 2048, "minLength": 1, "description": "The unique error name" } } }, "card_front": { "required": [ "type", "cardNumber", "cardHolderName", "cardExpiryDate" ], "type": "object", "properties": { "type": { "type": "string", "format": "card/front", "description": "An identifier for the `paymentInstrument` being used." }, "cardHolderName": { "maxLength": 255, "minLength": 1, "type": "string", "description": "The name on the customer's card." }, "cardExpiryDate": { "required": [ "month", "year" ], "type": "object", "description": "Object containing card expiry information", "properties": { "month": { "maximum": 12, "minimum": 1, "type": "integer", "description": "Card expiry month" }, "year": { "maximum": 9999, "minimum": 1, "type": "integer", "description": "Card expiry year" } } }, "cardNumber": { "maxLength": 19, "minLength": 10, "pattern": "^[0-9]*$", "type": "string", "description": "Clear card number (PAN)" }, "billingAddress": { "required": [ "address1", "city", "postalCode", "countryCode" ], "type": "object", "description": "An object containing the billing address information.", "properties": { "city": { "maxLength": 15, "minLength": 1, "type": "string", "description": "Billing address city" }, "address1": { "maxLength": 80, "minLength": 1, "type": "string", "description": "Billing address line 1" }, "postalCode": { "maxLength": 15, "minLength": 1, "type": "string", "description": "Billing address postal code" }, "countryCode": { "maxLength": 2, "minLength": 2, "pattern": "^[A-Z]{2}$", "type": "string", "description": "Billing address country code" }, "state": { "maxLength": 30, "minLength": 1, "type": "string", "description": "Billing address state. Should only be provided following the `ISO-3611-2` two-character sub division (e.g.“CA” for California)." }, "address2": { "maxLength": 80, "type": "string", "description": "Billing address line 2" }, "address3": { "maxLength": 80, "type": "string", "description": "Billing address line 3" } } } } }, "card_tokenized": { "required": [ "type", "href" ], "type": "object", "properties": { "type": { "type": "string", "format": "card/tokenized", "description": "An identifier for the `paymentInstrument` being used." }, "href": { "minLength": 1, "type": "string", "description": "An `http` address that contains your link to an Access Token" } } }, "3DS_authenticate": { "required": [ "transactionReference", "merchant", "instruction", "deviceData", "challenge" ], "type": "object", "properties": { "transactionReference": { "maxLength": 64, "minLength": 1, "pattern": "^[-A-Za-z0-9_!@#$%()*=.:;?\\[\\]{}~`/+]*$", "type": "string", "description": "A unique reference for authentication. For example, e-commerce order code." }, "merchant": { "required": [ "entity" ], "type": "object", "description": "An object that contains information about the merchant and API level configuration.", "properties": { "entity": { "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9 ]*$", "type": "string", "description": "Used to route the request in Access Worldpay, created as part of on-boarding." } } }, "instruction": { "required": [ "value", "paymentInstrument" ], "type": "object", "description": "The object that contains all the payment information related to the authentication request.", "properties": { "value": { "required": [ "amount", "currency" ], "type": "object", "description": "An object that contains information about the value of the authentication.", "properties": { "amount": { "maximum": 99999999999, "minimum": 0, "type": "integer", "description": "The authentication amount. This is a whole number with an exponent." }, "currency": { "maxLength": 3, "minLength": 3, "pattern": "^[A-Z]{3}$", "type": "string", "description": "The three digit currency code." } } }, "paymentInstrument": { "oneOf": [ { "$ref": "#/components/schemas/card_front" }, { "$ref": "#/components/schemas/card_tokenized" } ], "description": "An object that contains the card details or token location.", "discriminator": { "mapping": { "card/front": "#/components/schemas/card_front", "card/tokenized": "#/components/schemas/card_tokenized" }, "propertyName": "type" } } } }, "deviceData": { "required": [ "acceptHeader", "userAgentHeader" ], "type": "object", "description": "Object containing device data information.", "properties": { "acceptHeader": { "maxLength": 2048, "minLength": 1, "type": "string", "description": "Used by the issuer to check if the customer's browser is compatible with the issuer challenge display." }, "userAgentHeader": { "maxLength": 2048, "minLength": 1, "type": "string", "description": "Used by issuers as part of risk analysis and correctly displaying the challenge. Must conform to RFC 7321 E.g. `Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)`." }, "collectionReference": { "maxLength": 200, "type": "string", "description": "For web this is the `sessionId` in the post message response from the Device Data Collection form. For iOS/Android SDK this is the `consumerSessionId` returned as part of SDK and Device data initialization." } } }, "challenge": { "required": [ "returnUrl" ], "type": "object", "description": "An object that contains challenge related information.", "properties": { "returnUrl": { "minLength": 1, "type": "string", "format": "uri", "description": "URL the issuer will redirect to once the customer completes the challenge page." }, "preference": { "enum": [ "noPreference", "noChallengeRequested", "challengeRequested", "challengeMandated" ], "type": "string", "description": "Preference regarding issuer displaying challenge to the customer." }, "windowSize": { "enum": [ "390x400", "250x400", "600x400", "fullPage" ], "type": "string", "description": "Specify the challenge window size (width x height) that the issuer should use." } } }, "riskData": { "type": "object", "description": "Object containing additional risk data.", "properties": { "account": { "type": "object", "description": "Object containing all customer account related risk data.", "properties": { "previousSuspiciousActivity": { "type": "boolean", "description": "Whether there is a record of previous suspicious activity." }, "type": { "enum": [ "guestUser", "registeredUser", "federatedAccount", "issuerCredentials", "thirdPartyAuthentication", "fidoAuthenticator" ], "type": "string", "description": "Type of account the current customer has." }, "email": { "maxLength": 128, "minLength": 3, "pattern": "^.+@.+$", "type": "string", "description": "The customer's email address." }, "history": { "type": "object", "description": "Object containing customer's account history.", "properties": { "createdAt": { "type": "string", "format": "date", "description": "When the account was created." }, "modifiedAt": { "type": "string", "format": "date", "description": "When the account was last modified." }, "passwordModifiedAt": { "type": "string", "format": "date", "description": "When the account password was last changed." }, "paymentAccountEnrolledAt": { "type": "string", "format": "date", "description": "Date the payment account was added to the cardholder account." } } } } }, "transaction": { "type": "object", "description": "Object containing all customer transaction related risk data.", "properties": { "reorder": { "type": "boolean", "description": "If this is a repeat of a previous order." }, "preOrderDate": { "type": "string", "format": "date", "description": "Expected date that a pre-ordered purchase will be available." }, "firstName": { "maxLength": 22, "minLength": 1, "type": "string", "description": "Customer's first name." }, "lastName": { "maxLength": 22, "minLength": 1, "type": "string", "description": "Customer's last name." }, "phoneNumber": { "maxLength": 20, "minLength": 4, "pattern": "^[0-9]*$", "type": "string", "description": "Customer's phone number." }, "history": { "type": "object", "description": "Object containing details of the last transaction.", "properties": { "attemptsLastDay": { "maximum": 999, "minimum": 0, "type": "integer", "description": "Number of transactions (successful or abandoned) for this cardholder account within the last 24 hours." }, "attemptsLastYear": { "maximum": 999, "minimum": 0, "type": "integer", "description": "Number of transactions (successful or abandoned) for this cardholder account within the last year." }, "completedLastSixMonths": { "maximum": 9999, "minimum": 0, "type": "integer", "description": "Number of purchases with this customer account during the previous six months." }, "addCardsLastDay": { "maximum": 999, "minimum": 0, "type": "integer", "description": "Number of attempts to add a card in the last 24hrs." }, "shippingAddressFirstUsedAt": { "type": "string", "format": "date", "description": "When the shipping address used for the transaction was first used." } } }, "giftCardsPurchase": { "type": "object", "description": "Object containing information on whether the order is being used to purchase a gift card.", "properties": { "totalValue": { "required": [ "amount", "currency" ], "type": "object", "description": "Object containing information on value of the gift cards being purchase.", "properties": { "amount": { "maximum": 99999999999, "minimum": 0, "type": "integer", "description": "The amount being placed on the gift card. If provided, must include `totalValue.currency`." }, "currency": { "maxLength": 3, "minLength": 3, "pattern": "^[A-Z]{3}$", "type": "string", "description": "The three digit currency code. If provided must include `totalValue.amount`." } } }, "quantity": { "maximum": 99, "minimum": 0, "type": "integer", "description": "The number of gift cards being purchased." } } } } }, "shipping": { "type": "object", "description": "Object containing all data related to how the order will be shipped.", "properties": { "nameMatchesAccountName": { "type": "boolean", "description": "If customer name on account is identical to the shipping name." }, "method": { "enum": [ "billingAddress", "verifiedAddress", "otherAddress", "store", "digital", "unshippedTickets", "other" ], "type": "string", "description": "Field containing information on shipping method chosen by customer." }, "timeFrame": { "enum": [ "electronic", "twoDaysPlus", "nextDay", "sameDay" ], "type": "string", "description": "Timeframe chosen by customer for delivery." }, "email": { "maxLength": 128, "minLength": 3, "pattern": "^.+@.+$", "type": "string", "description": "The email address used for an electronic delivery." } } } } } } }, "3DS_authenticate_200_response": { "required": [ "outcome" ], "type": "object", "properties": { "outcome": { "enum": [ "challenged", "notEnrolled", "unavailable", "authenticationFailed", "authenticated", "signatureFailed", "bypassed" ], "type": "string", "description": "The outcome of the authentication request." }, "transactionReference": { "maxLength": 64, "minLength": 1, "type": "string", "description": "A unique reference for authentication that was passed in the request." }, "authentication": { "type": "object", "description": "Object that contains authentication related information.", "properties": { "version": { "maxLength": 10, "minLength": 1, "type": "string", "description": "The version of 3DS used to process the transaction." }, "eci": { "maxLength": 2, "minLength": 1, "type": "string", "description": "Electronic Commerce Indicator (ECI). Indicates the outcome of the 3DS authentication." }, "authenticationValue": { "maxLength": 64, "minLength": 1, "type": "string", "description": "A cryptographic value that provides evidence of the outcome of a 3DS verification." }, "transactionId": { "maxLength": 64, "minLength": 1, "type": "string", "description": "A transaction identifier. If provided, you should use it as part of your payment authorization." } } }, "challenge": { "type": "object", "description": "Object containing challenge related information in case of a \"challenged\" flow", "properties": { "reference": { "maxLength": 20, "minLength": 1, "type": "string", "description": "This links the authentication response to the subsequent challenge form and verification request." }, "url": { "maxLength": 2048, "minLength": 1, "type": "string", "description": "POST action on the challenge form. Used to redirect to the issuers challenge page as part of the challenge form." }, "jwt": { "maxLength": 2048, "minLength": 1, "type": "string", "description": "A digitally signed token that contains additional details, such as the URL to return to after the challenge screen." }, "payload": { "maxLength": 2048, "minLength": 1, "type": "string", "description": "JSON container with extra data required for the challenge." } } } } }, "3DS_authenticate_400_response": { "required": [ "message", "errorName" ], "type": "object", "properties": { "path": { "type": "string", "maxLength": 2048, "minLength": 1, "description": "The request URI path" }, "status": { "maxLength": 3, "minLength": 3, "type": "integer", "description": "The HTTP status returned from server" }, "message": { "type": "string", "maxLength": 2048, "minLength": 1, "description": "The error description message" }, "errorName": { "type": "string", "maxLength": 2048, "minLength": 1, "description": "The unique error name" }, "headerName": { "type": "string", "maxLength": 2048, "minLength": 1, "description": "The name of the header containing invalid value" }, "allowedMethods": { "type": "array", "description": "List of HTTP methods that are allowed", "items": { "type": "string" } }, "validationErrors": { "required": [ "errorName", "jsonPath", "message" ], "type": "object", "description": "Object containing details of validation errors occurred", "properties": { "errorName": { "maxLength": 2048, "minLength": 1, "type": "string", "description": "Unique name of the validation error" }, "jsonPath": { "maxLength": 2048, "minLength": 1, "type": "string", "description": "Location of the field in request body for which the error occurred" }, "message": { "maxLength": 2048, "minLength": 1, "type": "string", "description": "Error description message" } } } } }, "3DS_authenticate_502_response": { "required": [ "message", "errorName" ], "type": "object", "properties": { "path": { "type": "string", "maxLength": 2048, "minLength": 1, "description": "The request URI path" }, "status": { "maxLength": 3, "minLength": 3, "type": "integer", "description": "The HTTP status returned from server" }, "message": { "type": "string", "maxLength": 2048, "minLength": 1, "description": "The error description message" }, "errorName": { "type": "string", "maxLength": 2048, "minLength": 1, "description": "The unique error name" } } }, "3DS_authenticate_503_response": { "required": [ "message", "errorName" ], "type": "object", "properties": { "path": { "type": "string", "maxLength": 2048, "minLength": 1, "description": "The request URI path" }, "status": { "maxLength": 3, "minLength": 3, "type": "integer", "description": "The HTTP status returned from server" }, "message": { "type": "string", "maxLength": 2048, "minLength": 1, "description": "The error description message" }, "errorName": { "type": "string", "maxLength": 2048, "minLength": 1, "description": "The unique error name" } } }, "3DS_verify": { "required": [ "transactionReference", "challenge", "merchant" ], "type": "object", "properties": { "transactionReference": { "maxLength": 64, "minLength": 1, "pattern": "^[-A-Za-z0-9_!@#$%()*=.:;?\\[\\]{}~`/+]*$", "type": "string", "description": "A unique reference for authentication. For example, e-commerce order code." }, "merchant": { "required": [ "entity" ], "type": "object", "description": "An object that contains information about the merchant and API level configuration.", "properties": { "entity": { "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9 ]*$", "type": "string", "description": "Used to route the request in Access Worldpay, created as part of on-boarding." } } }, "challenge": { "required": [ "reference" ], "type": "object", "description": "Object containing challenge related information in case of a \"challenged\" flow", "properties": { "reference": { "maxLength": 20, "minLength": 20, "pattern": "(^[A-Za-z0-9]*$)", "type": "string", "description": "The challenge reference obtained from the previous authentication request, in case the customer was redirected to a \"challenged\" flow." } } } } }, "3DS_verify_200_response": { "type": "object", "properties": { "outcome": { "enum": [ "authenticated", "authenticationFailed", "unavailable", "signatureFailed", "bypassed" ], "type": "string", "description": "Outcome of the previously posted authentication request." }, "authentication": { "type": "object", "description": "Object that contains authentication related information.", "properties": { "version": { "maxLength": 10, "minLength": 1, "type": "string", "description": "The version of 3DS used to process the transaction." }, "eci": { "maxLength": 2, "minLength": 1, "type": "string", "description": "Electronic Commerce Indicator (ECI). Indicates the outcome of the 3DS authentication." }, "authenticationValue": { "maxLength": 64, "minLength": 1, "type": "string", "description": "A cryptographic value that provides evidence of the outcome of a 3DS verification." }, "transactionId": { "maxLength": 64, "minLength": 1, "type": "string", "description": "A transaction identifier. If provided, you should use it as part of your payment authorization." } } }, "transactionReference": { "maxLength": 64, "minLength": 1, "type": "string", "description": "A unique reference for authentication that was passed in the request." } } }, "3DS_verify_400_response": { "required": [ "message", "errorName" ], "type": "object", "properties": { "path": { "type": "string", "maxLength": 2048, "minLength": 1, "description": "The request URI path" }, "status": { "maxLength": 3, "minLength": 3, "type": "integer", "description": "The HTTP status returned from server" }, "message": { "type": "string", "maxLength": 2048, "minLength": 1, "description": "The error description message" }, "errorName": { "type": "string", "maxLength": 2048, "minLength": 1, "description": "The unique error name" }, "headerName": { "type": "string", "maxLength": 2048, "minLength": 1, "description": "The name of the header containing invalid value" }, "allowedMethods": { "type": "array", "description": "List of HTTP methods that are allowed", "items": { "type": "string" } }, "validationErrors": { "required": [ "errorName", "jsonPath", "message" ], "type": "object", "description": "Object containing details of validation errors occurred", "properties": { "errorName": { "maxLength": 2048, "minLength": 1, "type": "string", "description": "Unique name of the validation error" }, "jsonPath": { "maxLength": 2048, "minLength": 1, "type": "string", "description": "Location of the field in request body for which the error occurred" }, "message": { "maxLength": 2048, "minLength": 1, "type": "string", "description": "Error description message" } } } } } }, "securitySchemes": { "BasicAuth": { "type": "http", "scheme": "basic" } } }, "security": [ { "BasicAuth": [] } ] }