openapi: 3.0.3
info:
  title: 3D Secure authentication service API
  description: This is an API reference for the 3D Secure authentication service.
  version: 1.0.0
servers:
  - url: https://api-services.pxp.io/api/v1
    description: Production environment
  - url: https://api-services.test.pxp.io/api/v1
    description: Sandbox environment
paths:
  /threedsecure/standalone/authentications:
    post:
      tags:
        - Standalone authentication
      summary: Pre-initiate a standalone authentication request
      description: >-
        Pre-initiates a stand-alone 3D Secure authentication request for a
        transaction. This endpoint is used by merchants who utilise PXP's
        service solely for authentication purposes. The pre-initiation step
        gathers necessary information and ensures that all required data is
        available and valid before proceeding with the actual authentication
        request. This process helps to streamline the authentication process and
        enhance security.
      operationId: pre-initiate-standalone-auth-request
      requestBody:
        description: Request payload for pre-initiating a standalone authentication.
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/standaloneAuthenticationPreinitiationRequest
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/standaloneAuthenticationPreinitiationResponse
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '401':
          description: Unauthorised
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
  /threedsecure/standalone/authentications/{authenticationId}/browser-authentication:
    put:
      tags:
        - Standalone authentication
      summary: Initiate a standalone authentication request
      description: >-
        Initiates a standalone 3D Secure authentication request for a
        transaction. This endpoint is used by merchants who utilise PXP's
        service solely for authentication purposes. The process involves
        verifying the cardholder's identity through a browser-based interaction.
        The request payload must include comprehensive details about the
        transaction, card information, merchant information, and additional
        contextual data necessary for the 3D Secure authentication flow. This
        ensures a secure and efficient authentication process.
      operationId: initiate-standalone-auth-request
      parameters:
        - name: authenticationId
          in: path
          required: true
          schema:
            type: string
            description: The authentication ID.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/standaloneBrowserAuthenticationRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/standaloneBrowserAuthenticationResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '401':
          description: Unauthorised
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
  /threedsecure/standalone/authentications/{authenticationId}:
    get:
      tags:
        - Standalone authentication
      summary: Retrieve 3DS authentication by ID
      description: >-
        This endpoint retrieves the details of a specific 3DS standalone
        authentication using the `authenticationId` provided in the path. The
        service is designed for retrieving authentication records that were
        created as part of a 3DS verification process.
      operationId: retrieve-auth-by-id
      parameters:
        - name: authenticationId
          in: path
          required: true
          schema:
            type: string
            description: The authentication ID.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getAuthenticationResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '401':
          description: Unauthorised
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
  /threedsecure/integrated/authentications:
    post:
      tags:
        - Integrated authentication
      summary: Pre-initiate an integrated authentication request
      description: >-
        Pre-initiates an integrated 3D Secure authentication request for a
        transaction. In integrated mode, PXP processes the transaction in a
        separate initiate transaction request using the 3D Secure supplied data.
        This step ensures that all required data is gathered and validated
        before the full authentication process, facilitating a smoother and more
        secure transaction flow.
      operationId: pre-initiate-integrated-auth-request
      requestBody:
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/integratedAuthenticationPreinitiationRequest
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/integratedAuthenticationPreinitiationResponse
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '401':
          description: Unauthorised
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
  /threedsecure/integrated/authentications/{authenticationId}/browser-authentication:
    put:
      tags:
        - Integrated authentication
      summary: Initiate an integrated authentication request
      operationId: initiate-integrated-auth-request
      description: >-
        Authenticates an integrated 3D Secure transaction request. In integrated
        mode, PXP processes the transaction in conjunction with the 3D Secure
        authentication data. This ensures that the transaction is authenticated
        securely, leveraging the full authentication data collected during the
        pre-initiation phase. The request payload must include comprehensive
        details about the transaction, card information, merchant information,
        and additional contextual data necessary for the 3D Secure
        authentication flow.
      parameters:
        - name: authenticationId
          in: path
          required: true
          schema:
            type: string
            description: The authentication ID.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/integratedBrowserAuthenticationRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/integratedBrowserAuthenticationResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '401':
          description: Unauthorised
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
components:
  schemas:
    authenticationAmounts:
      required:
        - currencyCode
        - transactionValue
      type: object
      description: Details about the authenticated transaction's amount.
      properties:
        transactionValue:
          description: >-
            This is the amount of the authenticated transaction. The numbers
            after the decimal will be zero padded if they are less than the
            expected currencyCode exponent. For example, GBP 1.1 = GBP 1.10, EUR
            1 = EUR 1.00, or BHD 1.3 = 1.300. The transaction will be rejected
            if numbers after the decimal are greater than the expected
            currencyCode exponent, for example, GBP 1.234, or if a decimal is
            supplied when the currencyCode of exponent does not require it, for
            example, JPY 1.0.
          type: number
          format: double
        currencyCode:
          description: >-
            Denotes the currency code associated with the transaction,
            conforming to the ISO 4217 standard. This three-character code
            specifies the currency in which the transaction is processed,
            ensuring clarity and consistency across international transactions.
          minLength: 3
          maxLength: 3
          type: string
          example: EUR
      additionalProperties: false
    browserAuthenticationAddressRequest:
      description: Details of the address used in browser-based authentication.
      type: object
      properties:
        city:
          description: The city of the address.
          maxLength: 50
          minLength: 0
          type: string
          nullable: true
          example: San Francisco
        countryNumericCode:
          description: >-
            The numeric code representing the country of the address, following
            ISO 3166-1 numeric standard.
          maxLength: 3
          minLength: 3
          type: string
          nullable: true
          example: '840'
        line1:
          description: >-
            The first line of the address, typically representing the street
            address or PO Box number.
          maxLength: 50
          minLength: 0
          type: string
          nullable: true
          example: 123 Market St
        line2:
          description: >-
            The second line of the address, if applicable, for additional
            address information.
          maxLength: 50
          minLength: 0
          type: string
          nullable: true
          example: Apt 456
        line3:
          description: >-
            The third line of the address, if applicable, for additional address
            information.
          maxLength: 50
          minLength: 0
          type: string
          nullable: true
          example: Building B
        postalCode:
          description: >-
            The postal code of the address, which can vary in length based on
            the country.
          maxLength: 16
          minLength: 0
          type: string
          nullable: true
          example: '94105'
        stateCode:
          description: The state or province of the address.
          maxLength: 3
          minLength: 0
          type: string
          nullable: true
          example: CA
      additionalProperties: false
    browserAuthenticationBrowserInformationRequest:
      description: Information about the browser used in the authentication process.
      required:
        - acceptHeader
        - colorDepth
        - javaEnabled
        - javaScriptEnabled
        - language
        - screenHeight
        - screenWidth
        - timeZoneOffsetInMinutes
        - userAgent
      type: object
      properties:
        acceptHeader:
          description: The Accept HTTP header field from the browser.
          maxLength: 2048
          minLength: 0
          type: string
          example: >-
            text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
        colorDepth:
          description: The color depth of the browser's screen, measured in bits per pixel.
          type: integer
          format: int32
          example: 24
        ipAddress:
          description: The IP address of the device running the browser, if available.
          maxLength: 45
          minLength: 0
          type: string
          nullable: true
          example: 192.168.1.1
        javaEnabled:
          description: Indicates whether the browser has Java enabled.
          type: boolean
          example: true
        javaScriptEnabled:
          description: Indicates whether the browser has JavaScript enabled.
          type: boolean
          example: true
        language:
          maxLength: 8
          minLength: 0
          type: string
          description: IETF BCP 47 language tag is used
          example: en-US
        screenHeight:
          description: The height of the browser's screen in pixels.
          type: integer
          format: int32
          example: 1080
        screenWidth:
          description: The width of the browser's screen in pixels.
          type: integer
          format: int32
          example: 1920
        timeZoneOffsetInMinutes:
          description: >-
            The difference, in minutes, between UTC and the local time of the
            browser.
          type: integer
          format: int32
          example: -420
        userAgent:
          description: The User-Agent string of the browser.
          maxLength: 2048
          minLength: 0
          type: string
          example: >-
            Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML,
            like Gecko) Chrome/91.0.4472.124 Safari/537.36
      additionalProperties: false
    browserAuthenticationCardholderInformationRequest:
      description: Details about the shopper involved in the authentication.
      type: object
      properties:
        email:
          description: The email address of the shopper.
          maxLength: 254
          minLength: 0
          type: string
          nullable: true
          example: johndoe@example.com
        homePhoneNumber:
          description: The home phone number of the shopper.
          pattern: ^\d{1,3}-\d{1,15}$
          type: string
          nullable: true
          example: '+1234567890'
        mobilePhoneNumber:
          description: The mobile phone number of the shopper.
          pattern: ^\d{1,3}-\d{1,15}$
          type: string
          nullable: true
          example: '+0987654321'
        workPhoneNumber:
          description: The work phone number of the shopper.
          pattern: ^\d{1,3}-\d{1,15}$
          type: string
          nullable: true
          example: '+1123456789'
      additionalProperties: false
    errorResponse:
      type: object
      properties:
        errorCode:
          type: string
          nullable: true
        errorReason:
          type: string
          nullable: true
        correlationId:
          type: string
          nullable: true
        details:
          type: array
          items:
            type: string
          nullable: true
      additionalProperties: false
    getAuthenticationResponse:
      type: object
      properties:
        authenticationId:
          description: >-
            A unique reference provided by PXP for the authentication request,
            represented as a GUID.
          type: string
          nullable: true
          example: 550e8400-e29b-41d4-a716-446655440000
        state:
          type: string
          nullable: true
          enum:
            - PendingClientData
            - AuthenticationSuccessful
            - AuthenticationFailed
            - AuthenticationRejected
            - AuthenticationError
            - PendingCustomerChallenge
        threeDSecureVersion:
          description: >-
            The version of the 3D Secure protocol being used for the
            authentication.
          type: string
          nullable: true
          example: 2.1.0
        directoryServerTransactionId:
          type: string
          nullable: true
        cardholderAuthenticationVerificationValue:
          description: >-
            A value generated during the authentication process to verify the
            cardholder's identity.
          type: string
          nullable: true
          example: CAVV1234567890
        electronicCommerceIndicator:
          description: >-
            Indicator used to signify the level of security used in the
            authentication, often used in electronic commerce transactions.
          type: string
          nullable: true
          example: '05'
      additionalProperties: false
    integratedAuthenticationPreinitiationRequest:
      description: Request schema for pre-initiating an integrated authentication.
      required:
        - acquirerProfileId
        - card
        - fingerprintCallbackUrl
        - providerId
        - site
      type: object
      properties:
        amount:
          $ref: '#/components/schemas/authenticationAmounts'
        fingerprintCallbackUrl:
          description: The fingerprint callback URL.
          minLength: 1
          type: string
        acquirerProfileId:
          description: The unique identifier for the acquirer's profile.
          maxLength: 36
          minLength: 0
          type: string
          example: acquirer_123456
        providerId:
          description: The unique identifier for the provider.
          maxLength: 36
          minLength: 0
          type: string
          example: provider_123456
        requestorAuthenticationIndicator:
          description: >
            Indicator used to specify the type of authentication request, such
            as payment authentication or account verification. 


            Possible values:
              - `01`: Payment transaction
              - `02`: Initial Recurring Transaction
              - `03`: Initial Card-on-file transaction for subsequent MITs
              - `04`: Initial Card-on-file transaction for subsequent CITs         
              - `05`: Store card details without purchase (card verification)
              - `06`: Instalment transaction
              - `07`: Billing agreement
              - `08`: Split shipment
              - `09`: Delayed shipment
              - `10`: Split payment
          maxLength: 2
          minLength: 0
          type: string
          nullable: true
          example:
            PaymentTransaction:
              value: 1
        site:
          maxLength: 10
          minLength: 0
          type: string
        cardData:
          $ref: '#/components/schemas/preinitiationCardData'
      additionalProperties: false
    integratedAuthenticationPreinitiationResponse:
      description: Response schema for pre-initiating an integrated authentication.
      type: object
      properties:
        authenticationId:
          description: ' A unique reference provided by PXP for the authentication request, represented as a GUID.'
          type: string
          nullable: true
          example: 550e8400-e29b-41d4-a716-446655440000
        state:
          description: >-
            Current state of the authentication request, indicating the status
            of the pre-initiation process.
          type: string
          nullable: true
          enum:
            - PendingClientData
            - AuthenticationSuccessful
            - AuthenticationFailed
            - AuthenticationRejected
            - AuthenticationError
            - PendingCustomerChallenge
        scaMandated:
          description: >-
            Indicates whether Strong Customer Authentication (SCA) is mandated
            for this transaction.
          type: boolean
          example: true
        applicableExemptions:
          description: >-
            Specifies any exemptions that apply to the transaction from SCA
            requirements.
          type: string
          nullable: true
          enum:
            - LVP
            - TRA
        threeDSecureVersion:
          description: >-
            The version of the 3D Secure protocol being used for the
            authentication.
          type: string
          nullable: true
          example: 2.1.0
        threeDSecureFingerprintUrl:
          description: The URL to which the 3D Secure method data should be sent.
          type: string
          nullable: true
          example: https://example.com/3ds-method
        threeDSecureFingerprintData:
          description: >-
            Data required for the 3D Secure method, typically a base64 encoded
            string.
          type: string
          nullable: true
          example: eyJ0aHJlZURTU2VjdXJlTWV0aG9kRGF0YSI6IlhYWiJ9
        threeDSecureSupported:
          description: >-
            Indicates whether 3D Secure authentication is supported for this
            transaction.
          type: boolean
          example: true
        recommendedChallengeIndicator:
          type: string
          nullable: true
      additionalProperties: false
    integratedBrowserAuthenticationRequest:
      description: Request schema for browser-based integrated authentication.
      required:
        - browserData
        - challengeCallbackUrl
        - challengeWindowSize
        - merchantCountryNumericCode
        - merchantLegalName
        - requestorChallengeIndicator
        - shopper
      type: object
      properties:
        fingerprintNotification:
          type: string
          nullable: true
          description: >-
            URL for notifying the fingerprinting result. Base64 of
            `{"threeDSMethodNotificationURL":"method url
            value","threeDSServerTransID":"transaction id value"}`
        merchantCountryNumericCode:
          description: >-
            The three-digit country code of the merchant, following ISO 3166-1
            numeric standard.
          maxLength: 3
          minLength: 3
          type: string
          example: '840'
        merchantLegalName:
          description: The legal name of the merchant.
          maxLength: 40
          minLength: 0
          type: string
          example: ACME ltd
        challengeWindowSize:
          maximum: 5
          minimum: 1
          type: integer
          format: int32
          description: >
            The desired size of the challenge window displayed to the cardholder
            during authentication.


            Possible values:
              - `1`: 250x400
              - `2`: 390x400
              - `3`: 500x600
              - `4`: 600x400         
              - `5`: FullScreen
          example:
            500x600:
              value: 3
        requestorChallengeIndicator:
          maxLength: 2
          minLength: 0
          type: string
          description: |
            Indicator of whether a challenge is requested for this transaction.

            Possible values:
              - `01`: NoPreference
              - `02`: NoChallengeRequested
              - `03`: ChallengeRequested3dsRequestorPreference
              - `04`: ChallengeRequestedMandate         
              - `05`: NoChallengeRequestedTRAPerformed
              - `06`: NoChallengeRequestedDataShareOnly
              - `07`: NoChallengeRequestedStrongConsumerAuthentication
              - `08`: NoChallengeRequestedTrustListExemption
              - `09`: ChallengeRequestedTrustListPrompt
              - `10`: NoChallengeRequestedLowValueExemption
              - `11`: NoChallengeRequestedSecureCorporatePayment
              - `12`: ChallengeRequestedDeviceBindingPrompt
              - `13`: ChallengeRequestedIssuerRequested
              - `14`: ChallengeRequestedMerchantInitiatedTransactions
          example:
            NoPreference:
              value: 1
        challengeCallbackUrl:
          maxLength: 256
          minLength: 1
          type: string
          format: uri
          description: >-
            Fully qualified URL of the system that receives the CRes message or
            Error Message. The CRes message is posted by the ACS through the
            Cardholder Browser at the end of the challenge and receipt of the
            RRes message.
        recurring:
          $ref: '#/components/schemas/recurringData'
        billingAddress:
          $ref: '#/components/schemas/browserAuthenticationAddressRequest'
        shippingAddress:
          $ref: '#/components/schemas/browserAuthenticationAddressRequest'
        browserData:
          $ref: '#/components/schemas/browserAuthenticationBrowserInformationRequest'
        shopper:
          $ref: >-
            #/components/schemas/browserAuthenticationCardholderInformationRequest
      additionalProperties: false
    integratedBrowserAuthenticationResponse:
      description: Response schema for browser-based integrated authentication.
      type: object
      properties:
        uniqueId:
          type: string
          nullable: true
        state:
          description: >-
            Current state of the authentication request, indicating the status
            of the authentication process.
          type: string
          nullable: true
          enum:
            - PendingClientData
            - AuthenticationSuccessful
            - AuthenticationFailed
            - AuthenticationRejected
            - AuthenticationError
            - PendingCustomerChallenge
        transactionStatus:
          type: string
          nullable: true
          description: |-
            The status of the transaction.

            Possible values include:
             - `Y`: AuthenticationVerificationSuccessful
             - `N`: NotAuthenticated_NotVerified
             - `U`: AuthenticationCouldNotBePerformed
             - `A`: AttemptsProcessingPerformed
             - `C`: ChallengeRequired
             - `R`: AuthenticationRejected
             - `I`: InformationalOnly
          example:
            AuthenticationVerificationSuccessful:
              value: 'Y'
        electronicCommerceIndicator:
          description: >-
            Indicator used to signify the level of security used in the
            authentication, often used in electronic commerce transactions.
          type: string
          nullable: true
          example: '05'
        exemptionGranted:
          description: >-
            Indicates whether an exemption from Strong Customer Authentication
            (SCA) was granted.
          type: boolean
        exemptionGrantedByIssuer:
          description: |
            Specifies if the exemption was granted by the issuer.

            Possible values:
              - `05`: TransactionRiskAnalysisExemption
              - `08`: TrustListExemption
              - `10`: LowValueExemption
              - `11`: SecureCorporatePaymentsExemption         
              - `79`: NoExemptionApplied
          type: string
          nullable: true
          example:
            TransactionRiskAnalysisExemption:
              value: 5
        acsUrl:
          description: >-
            The URL of the Access Control Server (ACS) where the cardholder is
            redirected for challenge authentication.
          type: string
          nullable: true
          example: https://acs.example.com/challenge
        challengeData:
          description: >-
            Data required for the challenge authentication process, typically a
            base64 encoded string.
          type: string
          nullable: true
          example: eyJjaGFsbGVuZ2VEYXRhIjoiQUJDIn0=
        stateData:
          $ref: '#/components/schemas/stateDataResponse'
        cardholderInfo:
          type: string
          nullable: true
          description: >-
            Text provided by the ACS/Issuer to the Cardholder during a
            transaction.
    preinitiationCardData:
      type: object
      description: >-
        Details related to the card used for 3D Secure authentication. You can
        provide card details directly, use a stored gateway token, or use a
        scheme token.
      oneOf:
        - title: Card
          description: >-
            Use full card details for authentication. This option requires the
            primary account number, expiry date, cardholder name, and
            optionally, the card verification code (CVC).
          properties:
            card:
              description: Details about the card.
              type: object
              required:
                - primaryAccountNumber
                - expiryMonth
                - expiryYear
                - holderName
              properties:
                primaryAccountNumber:
                  description: >-
                    The unique number assigned to a payment card, such as a
                    credit or debit card.
                  example: '4111111111111111'
                  maxLength: 19
                  minLength: 13
                  type: string
                holderName:
                  description: >-
                    The full name of the individual who owns the payment card,
                    printed on the physical card.
                  maxLength: 100
                  minLength: 2
                  type: string
                expiryMonth:
                  description: The expiry month [MM] of the card.
                  example: '03'
                  maxLength: 2
                  minLength: 2
                  pattern: ^[0-9]{2}$
                  type: string
                expiryYear:
                  description: The expiry year [YYYY] of the card.
                  example: '2025'
                  maxLength: 4
                  minLength: 4
                  pattern: ^[0-9]{4}$
                  type: string
                cardVerificationCode:
                  description: >-
                    A 3 or 4 digit security code found on the card, used for
                    verification in non-face-to-face transactions.
                  example: '123'
                  type: string
                  minLength: 3
                  maxLength: 4
        - title: Gateway token
          description: >-
            Use a previously saved payment card stored as a secure token by the
            PXP Unity gateway. This method eliminates the need to re-enter card
            details.
          properties:
            gatewayToken:
              description: Details about the gateway token.
              type: object
              properties:
                gatewayTokenId:
                  description: >-
                    A securely stored token representing a previously saved
                    card.
                  example: 2357e042-2bf0-4886-8d9d-718fa5909761
                  maxLength: 36
                  minLength: 36
                  type: string
              required:
                - gatewayTokenId
        - title: Scheme token
          description: >-
            Use a scheme-generated token instead of the full card number. This
            option is useful for enhanced security and compliance with
            tokenisation standards.
          properties:
            schemeToken:
              description: Details about the scheme token.
              type: object
              properties:
                schemeTokenId:
                  type: string
                  description: >-
                    A unique scheme token ID generated by PXP, used as a
                    reference to extract the schemeTokenNumber.
                  example: '4837261112345678'
              required:
                - schemeTokenId
        - title: Scheme token (external)
          description: >-
            Use an external scheme token issued by Visa or Mastercard. This
            method allows secure authentication without exposing full card
            details.
          properties:
            schemeTokenExternal:
              description: Details about the external scheme token.
              type: object
              properties:
                schemeTokenNumber:
                  type: string
                  description: An external scheme token issued by Visa or Mastercard.
                  example: '4837261112345678'
                expiryMonth:
                  description: The expiry month [MM] of the scheme token.
                  example: '03'
                  maxLength: 2
                  minLength: 2
                  pattern: ^[0-9]{2}$
                  type: string
                expiryYear:
                  description: The expiry year [YYYY] of the scheme token.
                  example: '2025'
                  maxLength: 4
                  minLength: 4
                  pattern: ^[0-9]{4}$
                  type: string
                holderName:
                  description: >-
                    The full name of the cardholder associated with the scheme
                    token.
                  example: Mr John Doe
                  maxLength: 100
                  minLength: 2
                  type: string
              required:
                - schemeTokenNumber
                - expiryMonth
                - expiryYear
                - holderName
    recurringData:
      description: Details related to recurring transactions for 3D Secure authentication.
      type: object
      properties:
        expirationDate:
          description: The expiration date of the recurring transaction plan.
          type: string
          example: '2024-12-31T23:59:59Z'
          format: date-time
          nullable: true
        frequencyInDays:
          description: The frequency of the recurring transactions in days.
          type: integer
          format: int32
          nullable: true
          example: 30
      additionalProperties: false
    standaloneAuthenticationPreinitiationRequest:
      description: Request schema for pre-initiating a stand-alone authentication.
      required:
        - acquirerProfileId
        - card
        - fingerprintCallbackUrl
        - merchantGroup
      type: object
      properties:
        amount:
          $ref: '#/components/schemas/authenticationAmounts'
        fingerprintCallbackUrl:
          description: The fingerprint callback URL.
          minLength: 1
          type: string
        acquirerProfileId:
          description: The unique identifier for the acquirer's profile.
          maxLength: 20
          minLength: 0
          type: string
        requestorAuthenticationIndicator:
          maxLength: 2
          minLength: 0
          type: string
          nullable: true
          description: >
            Indicator used to specify the type of authentication request, such
            as payment authentication or account verification. 


            Possible values:
              - `01`: Payment transaction
              - `02`: Initial Recurring Transaction
              - `03`: Initial Card-on-file transaction for subsequent MITs
              - `04`: Initial Card-on-file transaction for subsequent CITs         
              - `05`: Store card details without purchase (card verification)
              - `06`: Instalment transaction
              - `07`: Billing agreement
              - `08`: Split shipment
              - `09`: Delayed shipment
              - `10`: Split payment
          example:
            PaymentTransaction:
              value: 1
        merchantGroup:
          description: The merchant group.
          maxLength: 10
          minLength: 0
          type: string
        card:
          $ref: '#/components/schemas/preinitiationCardData'
      additionalProperties: false
    standaloneAuthenticationPreinitiationResponse:
      description: Response schema for pre-initiating a stand-alone authentication.
      type: object
      properties:
        authenticationId:
          description: >-
            A unique reference provided by PXP for the authentication request,
            represented as a GUID.
          type: string
          example: 550e8400-e29b-41d4-a716-446655440000
          nullable: true
        state:
          description: >-
            Current state of the authentication request, indicating the status
            of the pre-initiation process.
          type: string
          nullable: true
          enum:
            - PendingClientData
            - AuthenticationSuccessful
            - AuthenticationFailed
            - AuthenticationRejected
            - AuthenticationError
            - PendingCustomerChallenge
          example: PendingClientData
        scaMandated:
          description: >-
            Indicates whether Strong Customer Authentication (SCA) is mandated
            for this transaction.
          type: boolean
          example: true
        threeDSecureVersion:
          description: >-
            The version of the 3D Secure protocol being used for the
            authentication.
          type: string
          nullable: true
          example: 2.1.0
        threeDSecureFingerprintUrl:
          description: The URL to which the 3D Secure method data should be sent.
          type: string
          nullable: true
          example: https://example.com/3ds-method
        threeDSecureFingerprintData:
          description: >-
            Data required for the 3D Secure method, typically a base64 encoded
            string.
          type: string
          nullable: true
          example: eyJ0aHJlZURTU2VjdXJlTWV0aG9kRGF0YSI6IlhYWiJ9
        threeDSecureSupported:
          description: >-
            Indicates whether 3D Secure authentication is supported for this
            transaction.
          type: boolean
          example: true
        recommendedChallengeIndicator:
          description: The recommended challenge indicator.
          type: string
          nullable: true
      additionalProperties: false
    standaloneBrowserAuthenticationRequest:
      description: >-
        Request schema for browser-based stand-alone authentication for 3D
        Secure.
      required:
        - acquirerMerchantId
        - browserData
        - challengeCallbackUrl
        - challengeWindowSize
        - merchantCountryNumericCode
        - merchantLegalName
        - requestorChallengeIndicator
        - shopper
      type: object
      properties:
        fingerprintNotification:
          description: >-
            URL for notifying the fingerprinting result. Base64 of
            {"threeDSMethodNotificationURL":"method url
            value","threeDSServerTransID":"transaction id value"}
          type: string
          nullable: true
        merchantCategoryCode:
          description: >-
            The four-digit Merchant Category Code (MCC) assigned to the
            merchant.
          maxLength: 4
          minLength: 4
          type: string
          nullable: true
          example: '5411'
        merchantCountryNumericCode:
          description: >-
            The three-digit country code of the merchant, following ISO 3166-1
            numeric standard.
          maxLength: 3
          minLength: 3
          type: string
          example: '840'
        merchantLegalName:
          description: The legal name of the merchant.
          maxLength: 40
          minLength: 0
          type: string
          example: ACME Ltd
        acquirerMerchantId:
          description: The acquirer merchant ID.
          maxLength: 35
          minLength: 0
          type: string
        challengeWindowSize:
          description: >
            The desired size of the challenge window displayed to the cardholder
            during authentication.


            Possible values:
              - `1`: 250x400
              - `2`: 390x400
              - `3`: 500x600
              - `4`: 600x400         
              - `5`: FullScreen
          maximum: 5
          minimum: 1
          type: integer
          format: int32
          example:
            500x600:
              value: 3
        requestorChallengeIndicator:
          maxLength: 2
          minLength: 0
          type: string
          description: |
            Indicator of whether a challenge is requested for this transaction.

            Possible values:
              - `01`: NoPreference
              - `02`: NoChallengeRequested
              - `03`: ChallengeRequested3dsRequestorPreference
              - `04`: ChallengeRequestedMandate         
              - `05`: NoChallengeRequestedTRAPerformed
              - `06`: NoChallengeRequestedDataShareOnly
              - `07`: NoChallengeRequestedStrongConsumerAuthentication
              - `08`: NoChallengeRequestedTrustListExemption
              - `09`: ChallengeRequestedTrustListPrompt
              - `10`: NoChallengeRequestedLowValueExemption
              - `11`: NoChallengeRequestedSecureCorporatePayment
              - `12`: ChallengeRequestedDeviceBindingPrompt
              - `13`: ChallengeRequestedIssuerRequested
              - `14`: ChallengeRequestedMerchantInitiatedTransactions
          example:
            NoPreference:
              value: 1
        challengeCallbackUrl:
          maxLength: 256
          minLength: 1
          type: string
          format: uri
          description: >-
            Fully qualified URL of the system that receives the CRes message or
            Error Message. The CRes message is posted by the ACS through the
            Cardholder Browser at the end of the challenge and receipt of the
            RRes message.
        recurring:
          $ref: '#/components/schemas/recurringData'
        billingAddress:
          $ref: '#/components/schemas/browserAuthenticationAddressRequest'
        shippingAddress:
          $ref: '#/components/schemas/browserAuthenticationAddressRequest'
        browserData:
          $ref: '#/components/schemas/browserAuthenticationBrowserInformationRequest'
        shopper:
          $ref: >-
            #/components/schemas/browserAuthenticationCardholderInformationRequest
      additionalProperties: false
    standaloneBrowserAuthenticationResponse:
      description: Response schema for browser-based stand-alone authentication.
      type: object
      properties:
        state:
          description: >-
            Current state of the authentication request, indicating the status
            of the authentication process.
          type: string
          nullable: true
          enum:
            - PendingClientData
            - AuthenticationSuccessful
            - AuthenticationFailed
            - AuthenticationRejected
            - AuthenticationError
            - PendingCustomerChallenge
          example: PendingClientData
        transactionStatus:
          type: string
          nullable: true
          description: |-
            The status of the transaction.

            Possible values include:
             - `Y`: AuthenticationVerificationSuccessful
             - `N`: NotAuthenticated_NotVerified
             - `U`: AuthenticationCouldNotBePerformed
             - `A`: AttemptsProcessingPerformed
             - `C`: ChallengeRequired
             - `R`: AuthenticationRejected
             - `I`: InformationalOnly
          example:
            AuthenticationVerificationSuccessful:
              value: 'Y'
        electronicCommerceIndicator:
          description: >-
            Indicator used to signify the level of security used in the
            authentication, often used in electronic commerce transactions.
          type: string
          nullable: true
          example: '05'
        cardholderAuthenticationVerificationValue:
          description: >-
            A value generated during the authentication process to verify the
            cardholder's identity.
          type: string
          nullable: true
          example: CAVV1234567890
        exemptionGranted:
          description: >-
            Indicates whether an exemption from Strong Customer Authentication
            (SCA) was granted.
          type: boolean
          example: true
        exemptionGrantedByIssuer:
          type: string
          nullable: true
          description: |
            Specifies if the exemption was granted by the issuer.

            Possible values:
              - `05`: TransactionRiskAnalysisExemption
              - `08`: TrustListExemption
              - `10`: LowValueExemption
              - `11`: SecureCorporatePaymentsExemption         
              - `79`: NoExemptionApplied
          example:
            TransactionRiskAnalysisExemption:
              value: 5
        acsUrl:
          description: >-
            The URL of the Access Control Server (ACS) where the cardholder is
            redirected for challenge authentication.
          type: string
          nullable: true
          example: https://acs.example.com/challenge
        challengeData:
          description: >-
            Data required for the challenge authentication process, typically a
            base64 encoded string.
          type: string
          nullable: true
          example: eyJjaGFsbGVuZ2VEYXRhIjoiQUJDIn0=
        stateData:
          $ref: '#/components/schemas/stateDataResponse'
        cardholderInfo:
          type: string
          nullable: true
          description: >-
            Text provided by the ACS/Issuer to the Cardholder during a
            transaction.
      additionalProperties: false
    stateDataResponse:
      description: Details about the state.
      type: object
      properties:
        code:
          type: string
          nullable: true
          description: The state code. Possible values include numbers from 01 to 30
        reason:
          type: string
          description: The state reason.
          nullable: true
      additionalProperties: false
