openapi: 3.0.1
info:
  title: 3DS 3DS actions Identity verification API
  description: "Protect your business and meet regulatory requirements by verifying your customer's identity.\n\n__Authentication header__\n  ```\n    Authorization: {your_credentials}\n  ```\nReplace `{your_credentials}` with your base64-encoded Basic Auth username and password given to your by your Worldpay Implementation Manager.\n<br /> <br />\n\nYou **must** use the `Authorization` header for any request you send to our 3DS API.\n\n__Accept/Content-Type header__\n  ```\n  Content-Type: application/vnd.worldpay.verifications.customers-v3.hal+json\n  Accept: application/vnd.worldpay.verifications.customers-v3.hal+json\n  ```\nWe use the Accept header to identify which version of our API you are using. You must use the Accept header for any request you send to our 3DS API.\n\nWe require the Content-Type header if the request you're sending includes a request body, and if the HTTP method is a `POST` or a `PUT`.\n<br /><br />\n\n\n__DNS whitelisting__  \nWhitelist the following URLs:\n* `https://try.access.worldpay.com/`\n* `https://access.worldpay.com/`\n\nPlease ensure you use DNS whitelisting, not explicit IP whitelisting."
  version: '3'
  x-metadata:
    category:
    - 3DS
    - SCA Exemptions
    business:
    - Enterprise
    catalog-list: true
    generated: false
servers:
- url: https://try.access.worldpay.com
  description: Test (Try)
- url: https://access.worldpay.com
  description: Live
security:
- BasicAuth: []
tags:
- name: Identity verification
  description: Enable identity verification check on a party.
paths:
  /parties/{partyId}/identityVerification:
    post:
      tags:
      - Identity verification
      summary: Perform identity verification
      operationId: performIdentityVerification
      parameters:
      - name: partyId
        in: path
        description: A unique identifier for the party generated by us. This is sent in the response of your party creation call.
        required: true
        schema:
          type: string
          maxLength: 25
          minLength: 25
          pattern: ^par[a-zA-Z0-9-_]*0$
      - name: WP-Api-Version
        in: header
        description: The API version.
        required: true
        schema:
          type: string
          format: date
        example: '2025-01-01'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentityVerification'
            examples:
              Perform an Identity Verification request for a company with beneficial owners (modular):
                $ref: '#/components/examples/Perform_IVS_Company_modular'
              URL with invalid value:
                $ref: '#/components/examples/400_Invalid_Url'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityVerificationResponse'
              examples:
                Identity Verification response for a company with beneficial owners (modular):
                  $ref: '#/components/examples/Perform_IVS_Company_200_modular'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Bad request:
                  $ref: '#/components/examples/400'
                URL with invalid value:
                  $ref: '#/components/examples/400_Invalid_Url'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Internal error occurred:
                  $ref: '#/components/examples/500'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Service Unavailable:
                  $ref: '#/components/examples/503'
    get:
      tags:
      - Identity verification
      summary: View identity verification status
      operationId: getIdentityVerificationStatus
      parameters:
      - name: partyId
        in: path
        description: A unique identifier for the party generated by us. This is sent in the response of your party creation call.
        required: true
        schema:
          type: string
          maxLength: 25
          minLength: 25
          pattern: ^par[a-zA-Z0-9-_]*0$
      - name: WP-Api-Version
        in: header
        description: The API version.
        required: true
        schema:
          type: string
          format: date
        example: '2025-01-01'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityVerificationResponse'
              examples:
                Verify an Identity Verification status for a company with beneficial owners (modular):
                  $ref: '#/components/examples/Get_IVS_Company_200_modular'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                URL with invalid value:
                  $ref: '#/components/examples/400_Invalid_Url'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Internal error occurred:
                  $ref: '#/components/examples/500'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Service Unavailable:
                  $ref: '#/components/examples/503'
components:
  schemas:
    ErrorResponseItem:
      type: object
      properties:
        errorName:
          type: string
        message:
          type: string
        path:
          type: string
        jsonPath:
          type: string
        queryParameter:
          type: string
        pathParameter:
          type: string
    IdentityVerificationResponse:
      type: object
      properties:
        errorName:
          type: string
          description: An ordinal error type that is part of the API contract. It is machine readable, but also human readable for clarity and semantic understanding of the error.
          example: bodyDoesNotMatchSchema
        message:
          type: string
          description: A human readable message giving a corrective action for the error. THIS IS NOT FOR MACHINE CONSUMPTION.
        validationErrors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorResponseItem'
        pathParameter:
          type: string
        queryParameter:
          type: string
        jsonPath:
          type: string
        overall:
          $ref: '#/components/schemas/IdentityVerificationInfo'
        party:
          $ref: '#/components/schemas/PartyIdentityVerificationInfo'
        beneficialOwners:
          type: array
          items:
            $ref: '#/components/schemas/BeneficialOwnerIdentityVerificationInfo'
    IdentityVerificationInfo:
      type: object
      properties:
        identityVerificationState:
          type: string
          enum:
          - verified
          - notVerified
          - pending
          - rejected
          - notApplicable
          - started
          - startedAction
          - pendingStepUpAction
          - pendingManualReview - stepUpReceived
          readOnly: true
        identityVerificationMethod:
          type: string
          enum:
          - merchantCompliant
          - identityVerificationService
          readOnly: true
        identityVerificationDate:
          type: string
          format: date
          description: A valid date as YYYY-MM-DD
          example: '2033-11-22'
          readOnly: true
        url:
          type: string
          description: The link returned from Identity Verification Status (IVS) used to retrieve additional details from the user.
          readOnly: true
        message:
          type: string
          description: The message associated with link returned from Identity Verification Status (IVS).
          readOnly: true
    BeneficialOwnerIdentityVerificationInfo:
      type: object
      properties:
        identityVerificationState:
          type: string
          enum:
          - verified
          - notVerified
          - pending
          - rejected
          - notApplicable
          - started
          - startedAction
          - pendingStepUpAction
          - pendingManualReview - stepUpReceived
          readOnly: true
        identityVerificationMethod:
          type: string
          enum:
          - merchantCompliant
          - identityVerificationService
          readOnly: true
        identityVerificationDate:
          type: string
          format: date
          description: A valid date as YYYY-MM-DD
          example: '2033-11-22'
          readOnly: true
        url:
          type: string
          description: The link returned from Identity Verification Status (IVS) used to retrieve additional details from the user.
          readOnly: true
        message:
          type: string
          description: The message associated with link returned from Identity Verification Status (IVS).
          readOnly: true
        beneficialOwnerReference:
          type: string
          description: 'Your reference for this beneficial owner, must be unique within an entity.


            '
          example: Hosaka27384910
          maxLength: 64
          minLength: 3
          pattern: ^[A-Za-z0-9\-_ ]*$
        beneficialOwnerId:
          type: string
          description: A unique identifier for the beneficial owner generated by us.
          readOnly: true
    ErrorResponse:
      type: object
      properties:
        errorName:
          type: string
          description: An ordinal error type that is part of the API contract. It is machine readable, but also human readable for clarity and semantic understanding of the error.
          example: bodyDoesNotMatchSchema
        message:
          type: string
          description: A human readable message giving a corrective action for the error. THIS IS NOT FOR MACHINE CONSUMPTION.
        validationErrors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorResponseItem'
        pathParameter:
          type: string
        queryParameter:
          type: string
        jsonPath:
          type: string
      readOnly: true
      title: Error Response
    PartyIdentityVerificationInfo:
      type: object
      properties:
        identityVerificationState:
          type: string
          enum:
          - verified
          - notVerified
          - pending
          - rejected
          - notApplicable
          - started
          - startedAction
          - pendingStepUpAction
          - pendingManualReview
          - stepUpReceived
          readOnly: true
        identityVerificationMethod:
          type: string
          enum:
          - merchantCompliant
          - identityVerificationService
          readOnly: true
        identityVerificationDate:
          type: string
          format: date
          description: A valid date as YYYY-MM-DD
          example: '2033-11-22'
          readOnly: true
        url:
          type: string
          description: The link returned from Identity Verification Status (IVS) used to retrieve additional details from the user.
          readOnly: true
        message:
          type: string
          description: The message associated with link returned from Identity Verification Status (IVS).
          readOnly: true
        partyId:
          type: string
          description: A unique identifier for the party generated by us.
          readOnly: true
        partyReference:
          type: string
          description: 'Your reference for this party, must be unique within an entity.


            '
          example: Hosaka27384910
          maxLength: 64
          minLength: 3
          pattern: ^[A-Za-z0-9\-_ ]*$
    IdentityVerification:
      type: object
      properties:
        performIdentityVerification:
          type: boolean
          writeOnly: true
  examples:
    '503':
      value:
        errorName: serviceUnavailable
        message: Service cannot fulfil the request even though service functions witout internal errors.
    Get_IVS_Company_200_modular:
      description: Get Identiy Verification Status on a party of a company (modular)
      value:
        overall:
          identityVerificationState: started
          identityVerificationMethod: identityVerificationService
        party:
          identityVerificationState: started
          partyReference: Linnea474
          partyId: parWcAyq5G2-1KwvsEkFAKwz0
        beneficialOwners:
        - identityVerificationState: started
          beneficialOwnerReference: Mac551
          beneficialOwnerId: parAZo80iViOTdKRJi4Oq14Z0
        - identityVerificationState: started
          beneficialOwnerReference: Thea799
          beneficialOwnerId: parB5ON-IEK4olrLuHvjEDpE0
        - identityVerificationState: started
          beneficialOwnerReference: Santino227
          beneficialOwnerId: parNKRss9vllWyX1MUVOj7b-0
    400_Invalid_Url:
      value:
        errorName: urlContainsInvalidValue
        message: The URL contains a value or values that are invalid.
        validationErrors:
        - errorName: fieldHasInvalidValue
          message: Party 'parDgfhD9O5lWVjWiUOo3Cdf0' was not found.
          jsonPath: $.partyId
    Perform_IVS_Company_200_modular:
      description: Identity Verification Status on a party of a company (modular)
      value:
        overall:
          identityVerificationState: started
          identityVerificationMethod: identityVerificationService
        party:
          identityVerificationState: started
          partyReference: Euna925
          partyId: par1Bbf6r80Q3mEvhp_xBKNM0
        beneficialOwners:
        - identityVerificationState: started
          beneficialOwnerReference: Floy829
          beneficialOwnerId: parsH2dSCcczQveB-GQNx0qq0
        - identityVerificationState: started
          beneficialOwnerReference: Christina843
          beneficialOwnerId: parbQR-8sRkYASaOzOVPX5d10
        - identityVerificationState: started
          beneficialOwnerReference: Arlo912
          beneficialOwnerId: pargosUuzW0vv8HrWsCTuadb0
    '400':
      value:
        errorName: bodyDoesNotMatchSchema
        message: There were field validation errors. The errors that occurred are within the validationErrors array.
        validationErrors:
        - errorName: fieldIsNotAllowed
          message: The identified field is present when it is explicitly not allowed in the request.
          jsonPath: $.additionalData
    Perform_IVS_Company_modular:
      value:
        performIdentityVerification: true
    '500':
      value:
        errorName: internalErrorOccurred
        message: An error occurred within the service (potentially due to an interaction with a downstream service).
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic