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: testing (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.

      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.

      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.

      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: 50
              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: []
