openapi: 3.0.3
info:
  title: Merchant webhooks service API
  description: This is an API reference for the merchant webhooks 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:
  /merchant-webhooks:
    post:
      summary: Process a merchant webhook
      description: >-
        The `/merchant-webhooks` endpoint is designed for real-time
        notifications about transaction events, enabling you to automatically
        receive updates on transaction statuses such as authorisations,
        captures, and cancellations.
      operationId: process-merchant-webhook
      requestBody:
        description: Merchant webhooks
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/merchantWebhookRequest'
            examples:
              Transaction (Card Authorised) Event:
                value:
                  - eventDate: '2021-10-27T08:51:04.8264455Z'
                    eventCategory: Transaction
                    eventData:
                      state: Authorised
                      approvalCode: '123456'
                      merchant: MERCHANT-1
                      site: SITE-1
                      transactionMethod:
                        intent: Authorisation
                        fundingType: Card
                        entryType: Ecom
                      amounts:
                        transactionValue: 50.05
                        currencyCode: EUR
                      merchantOrderId: merchant_order_id
                      merchantTransactionId: merchant_transaction_id
                      systemTransactionId: 1ed768bb-e88a-4636-91ae-67927ccbb02b
                      merchantTransactionDate: '2024-01-27 08:51:02.826445+00:00'
                      fundingData:
                        cardScheme: Visa
                        tokenId: 1ed768bb-e88a-4636-91ae-67927ccbb03a
                        schemeTokenNumber: '4837261112345678'
                        providerResponse:
                          provider: PXPFinancial
                          code: '00'
                          message: Approved
                          merchantId: '77772182'
                          addressVerificationServiceResult: D
                          cardVerificationCodeResult: A
                          schemeTransactionId: TX1234567890123456
                          paymentAccountReference: PAR12345678901234567890
                          electronicCommerceIndicatorAdjustment: '01'
                          settlementDate: '2024-01-25'
              Transaction (Card Captured) Event:
                value:
                  - eventDate: '2021-10-27T08:51:04.8264455Z'
                    eventCategory: Transaction
                    eventData:
                      state: Captured
                      merchant: MERCHANT-1
                      site: SITE-1
                      transactionMethod:
                        intent: Capture
                        fundingType: Card
                        entryType: Ecom
                      amounts:
                        transactionValue: 50.05
                        currencyCode: EUR
                      merchantOrderId: This_is_my_merchant_order_id
                      merchantTransactionId: This_is_my_merchant_transaction_id
                      systemTransactionId: 1ed768bb-e88a-4636-91ae-67927ccbb02b
                      merchantTransactionDate: '2024-01-27 08:51:02.826445+00:00'
                      fundingData:
                        cardScheme: Visa
                        tokenId: 1ed768bb-e88a-4636-91ae-67927ccbb03a
                        schemeTokenNumber: '4837261112345678'
                        providerResponse:
                          provider: PXPFinancial
                          code: '00'
                          message: Approved
                          merchantId: '77772182'
                          paymentAccountReference: PAR12345678901234567890
                          schemeTransactionId: TX1234567890123456
                          settlementDate: '2024-01-25T00:00:00.000Z'
              Transaction (Card Cancelled) Event:
                value:
                  - eventDate: '2021-10-27T08:51:04.8264455Z'
                    eventCategory: Transaction
                    eventData:
                      state: Cancelled
                      merchant: MERCHANT-1
                      site: SITE-1
                      transactionMethod:
                        intent: Void
                        fundingType: Card
                        entryType: Ecom
                      amounts:
                        transactionValue: 50.05
                        currencyCode: EUR
                      merchantOrderId: This_is_my_merchant_order_id
                      merchantTransactionId: This_is_my_merchant_transaction_id
                      systemTransactionId: 1ed768bb-e88a-4636-91ae-67927ccbb02b
                      merchantTransactionDate: '2024-01-27 08:51:02.826445+00:00'
                      fundingData:
                        cardScheme: Visa
                        tokenId: 1ed768bb-e88a-4636-91ae-67927ccbb03a
                        schemeTokenNumber: '4837261112345678'
                        providerResponse:
                          provider: PXPFinancial
                          code: '00'
                          message: Approved
                          merchantId: '77772182'
                          paymentAccountReference: PAR12345678901234567890
                          schemeTransactionId: TX1234567890123456
              Token (SchemeTokenCreated) Event:
                value:
                  - eventDate: '2021-10-27T08:51:04.8264455Z'
                    eventCategory: Token
                    eventData:
                      state: SchemeTokenCreated
              Token (SchemeTokenCardUpdated) Event:
                value:
                  - eventDate: '2021-10-27T08:51:04.8264455Z'
                    eventCategory: Token
                    eventData:
                      state: SchemeTokenCardUpdated
              Token (SchemeTokenDisabled) Event:
                value:
                  - eventDate: '2021-10-27T08:51:04.8264455Z'
                    eventCategory: Token
                    eventData:
                      state: SchemeTokenDisabled
              Token (SchemeTokenUpdated) Event:
                value:
                  - eventDate: '2021-10-27T08:51:04.8264455Z'
                    eventCategory: Token
                    eventData:
                      state: SchemeTokenUpdated
        required: true
      responses:
        '200':
          description: Webhook response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/merchantWebhookResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: Unauthorised
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      servers:
        - url: https://merchantEndpoint
components:
  schemas:
    approvalCode:
      description: >-
        A unique identifier code provided by the authorising entity, indicating
        approval or reference for the transaction. This code typically consists
        of alphanumeric characters, starting with an uppercase letter, and
        serves as a key reference for authorisation verification.
      example: A123456
      type: string
      pattern: ^[A-Z]
    addressVerificationServiceResult:
      description: >-
        The result of the Address Verification System (AVS) check. This provides
        detailed insights into the matching status of the postal code and
        address provided by the cardholder against the information on file with
        the card issuer. AVS is a security measure to detect and prevent fraud
        in card-not-present transactions. The result codes offer granular
        information on what was matched, partially matched, not matched, or not
        checked, allowing for a nuanced understanding of the verification
        outcome.
      type: string
      enum:
        - NoInformationAvailable
        - PostCodeMatchedAddressMatched
        - PostCodeMatchedAddressNotMatched
        - PostCodeMatchedAddressNotChecked
        - PostCodeNotMatchedAddressMatched
        - PostCodeNotMatchedAddressNotMatched
        - PostCodeNotMatchedAddressNotChecked
        - PostCodeNotCheckedAddressMatched
        - PostCodeNotCheckedAddressNotMatched
        - PostCodeNotCheckedAddressNotChecked
        - PostCodeMatchedAndAddressPartialMatch
        - PostCodePartialMatchAddressMatched
        - PostCodePartialMatchAddressPartialMatch
        - PostCodeNotMatchedAddressPartialMatch
        - PostCodePartialMatchAddressNotMatched
        - PostCodePartialMatchAddressNotChecked
        - PostCodeNotCheckedAddressPartialMatch
      example: PostCodeMatchedAddressMatched
    authenticationData:
      properties:
        authenticationId:
          type: string
          description: >-
            Unique reference provided by PXP for the authentication request,
            represented as a GUID.
          example: 71e2698f-10ec-44d4-8302-dcff7bdcfe90
        state:
          $ref: '#/components/schemas/authenticationState'
        transactionStatus:
          $ref: '#/components/schemas/transactionStatus'
        transactionStatusReason:
          type: string
          description: Reason for the current transaction status.
        directoryServerTransactionId:
          type: string
          description: Unique identifier for the directory server transaction.
          example: 71e2698f-10ec-44d4-8302-dcff7bdcfe90
        threeDSecureVersion:
          type: string
          description: Version of the 3D Secure protocol.
          example: 2.2.0
        electronicCommerceIndicator:
          type: string
          description: >-
            Indicator used to signify the level of security used in the
            authentication, often used in electronic commerce transactions.
          example: '01'
        authenticationFlow:
          $ref: '#/components/schemas/authenticationFlow'
        challengeCancel:
          description: >
            Indicator informing the ACS and the DS that the authentication has
            been cancelled. 


            Possible values:
              - `01`: Cardholder selected “Cancel” 
              - `02`: Reserved for EMVCo future use (values invalid until defined by EMVCo).
              - `03`: Transaction Timed Out - Decoupled Authentication
              - `04`: Transaction Timed Out at ACS - other timeouts         
              - `05`: Transaction Timed Out at ACS - First CReq not received by ACS
              - `06`: Transaction Error
              - `07`: Unknown
              - `08`: Transaction Timed Out at 3DS SDK
              - `09`: Error Message in response to the CRes message sent by the ACS
              - `10`: Error Message in response to the CReq message received by the ACS
          type: string
          example: '01'
        challengeErrorReporting:
          description: >-
            A copy of the error message sent or received by the ACS in case of
            error in the CReq/CRes messages.
          type: string
    authenticationFlow:
      description: Flow of the authentication process.
      enum:
        - Frictionless
        - Challenge
      example: Challenge
      type: string
    authenticationState:
      description: >-
        The state of authentication indicating the outcome or current status of
        the authentication process.
      enum:
        - PendingClientData
        - AuthenticationSuccessful
        - AuthenticationFailed
        - AuthenticationRejected
        - AuthenticationError
        - PendingCustomerChallenge
      example: AuthenticationCompleted
      type: string
    cardScheme:
      description: >-
        Specifies the payment card's scheme, indicating the network through
        which the card transactions are processed. The card scheme is typically
        represented by a capitalized abbreviation or name of the card network.
        This information is crucial for identifying the card type and
        facilitating transaction processing in accordance with the network's
        regulations and standards.
      example: Visa
      type: string
      pattern: ^[A-Z]+$
    cardProviderResponse:
      description: >-
        The response from the payment provider containing details about the
        transaction processing outcome.
      required:
        - provider
        - code
        - merchantId
      properties:
        provider:
          $ref: '#/components/schemas/providerResponseName'
        code:
          $ref: '#/components/schemas/providerResponseCode'
        message:
          $ref: '#/components/schemas/providerResponseMessage'
        merchantId:
          $ref: '#/components/schemas/providerResponseMerchantId'
        cardVerificationCodeResult:
          $ref: '#/components/schemas/providerResponseCvcResult'
        addressVerificationServiceResult:
          $ref: '#/components/schemas/providerResponseAvsResult'
        paymentAccountReference:
          $ref: '#/components/schemas/paymentAccountReference'
        schemeTransactionId:
          $ref: '#/components/schemas/schemeTransactionId'
        electronicCommerceIndicatorAdjustment:
          $ref: '#/components/schemas/electronicCommerceIndicatorAdjustment'
        merchantAdvice:
          $ref: '#/components/schemas/merchantAdvice'
        settlementDate:
          $ref: '#/components/schemas/settlementDate'
    card:
      description: >-
        The `card` object contains essential information about a card involved
        in a transaction, including its scheme, payment account reference, and
        token IDs. Additionally, it provides verification results for enhanced
        security, such as CVC and AVS checks, enabling merchants to ensure
        transaction integrity and mitigate fraud risks efficiently. This object
        is returned if the `fundingType` under the `transactionMethod` is of
        type 'Card' or 'SchemeToken'.
      properties:
        cardScheme:
          $ref: '#/components/schemas/cardScheme'
        gatewayTokenId:
          $ref: '#/components/schemas/gatewayTokenId'
        schemeTokenNumber:
          $ref: '#/components/schemas/schemeTokenNumber'
        cardVerificationCodeResult:
          $ref: '#/components/schemas/cardVerificationCodeResult'
        addressVerificationServiceResult:
          $ref: '#/components/schemas/addressVerificationServiceResult'
        providerResponse:
          $ref: '#/components/schemas/cardProviderResponse'
      type: object
    currencyCode:
      description: >-
        The currency code associated with the transaction, in ISO 4217 format.
        This three-character code specifies the currency in which the
        transaction is processed, ensuring clarity and consistency across
        international transactions.
      example: EUR
      type: string
      minLength: 3
      maxLength: 3
    cardVerificationCodeResult:
      description: >-
        The outcome of the Card Verification Code (CVC) check, an essential
        security measure for verifying the cardholder's presence during a
        transaction. This result indicates whether the provided CVC matches,
        does not match, or has not been checked against the card issuer’s
        records, contributing to fraud prevention and transaction security.
      type: string
      enum:
        - NoInformationAvailable
        - CardSecurityCodeMatched
        - CardSecurityCodeNotMatched
        - CardSecurityCodeNotChecked
      example: CardSecurityCodeMatched
    electronicCommerceIndicatorAdjustment:
      description: >
        If present, this field represents the Electronic Commerce Indicator
        (ECI) adjustment made by the payment scheme after the initial
        transaction authorisation. The ECI signifies the level of security
        applied to an online transaction, indicating the authentication and
        verification methods used. Adjustments to the ECI reflect a reevaluation
        of the transaction's security level, which can be due to various factors
        such as risk assessment updates, compliance with security standards,
        outcomes of authentication processes, interchange fee considerations, or
        error corrections. An ECI adjustment can either upgrade or downgrade the
        transaction's security indicator, impacting interchange fees, chargeback
        liability, and the transaction's overall security assurance.


        Possible values:

        - "01": Transaction processed with SSL or equivalent but without
        cardholder authentication (considered less secure, higher risk).

        - "02": Transaction processed with cardholder authentication (e.g., 3D
        Secure), indicating a higher level of security.

        - "05": Transaction processed with 3D Secure authentication, cardholder
        authenticated successfully (high security).

        - "06": Transaction attempted 3D Secure authentication but could not be
        completed; cardholder not authenticated (medium security).

        - "07": Transaction processed without 3D Secure authentication, due to
        issuer or cardholder not participating in 3D Secure (considered less
        secure, higher risk).
      type: string
      example: '01'
    entryType:
      description: >-
        The environment and method by which the transaction is initiated,
        reflecting the nature of the transaction's origin. This classification
        is crucial for applying the appropriate security measures and compliance
        standards. The entry types include 'Ecom' for online transactions,
        'Moto' for mail order/telephone order transactions, and 'Instore' for
        physical retail environments, each representing different transaction
        contexts and risk profiles.
      type: string
      enum:
        - Ecom
        - Moto
        - Instore
      example: Ecom
    error:
      description: Details about the error.
      properties:
        correlationId:
          description: A unique identifier generated by PXP.
          type: string
        details:
          description: >-
            An array of additional details about the error, potentially
            including system-specific information, sub-errors, or contextual
            data to aid in troubleshooting.
          type: array
          items: {}
        errorCode:
          description: >-
            A standardised code that categorises the type of error encountered,
            enabling quick identification of common issues.
          type: string
        errorReason:
          description: >-
            A human-readable explanation of the error, providing clarity on the
            nature of the problem encountered.
          type: string
      required:
        - correlationId
        - errorCode
        - errorReason
      type: object
    eventCategory:
      description: >-
        The category of the webhook event sent from PXP to you. This field
        classifies the nature of the event being notified, facilitating targeted
        processing by your system. Event categories encompass a range of types,
        including but not limited to transactions (such as purchases,
        authorisations, captures), chargebacks, disputes, and more. Each
        category signifies a specific area of payment operations, enabling
        merchants to listen for and respond to relevant events effectively.
      type: string
      enum:
        - Authentication
        - Token
        - Transaction
      example: Transaction
    eventDate:
      description: >-
        The date and time when the event occurred, sent to the merchant as part
        of the webhook payload. This timestamp is crucial for tracking the
        timing of specific events, such as transaction authorisations, captures,
        or any other significant activity related to the merchant's operations.
        The format adheres to ISO 8601 standards, ensuring consistency and ease
        of parsing for system integration.
      type: string
      format: date-time
      example: '2021-10-27T08:51:04.826Z'
    fundingType:
      description: >-
        The method of payment used to fund the transaction. This field
        categorises the transaction by the payment medium, enabling tailored
        processing rules and security measures for each type. Understanding the
        funding type is crucial for processing the transaction correctly and
        ensuring compatibility with your  capabilities.
      type: string
      enum:
        - Card
      example: Card
    gatewayTokenId:
      description: >-
        A securely stored token that corresponds to a previously saved payment
        card. This token is generated and maintained by PXP to facilitate
        recurring transactions or transactions using stored card details,
        ensuring enhanced security and convenience. When a transaction is
        performed with a saved card, this token Id should be provided instead of
        the full card details. This approach enhances security by reducing the
        exposure of sensitive card information and simplifies the transaction
        process for returning customers."
      example: 2357e042-2bf0-4886-8d9d-718fa5909761
      maxLength: 36
      minLength: 36
      type: string
    gratuityValue:
      description: >-
        An optional field that captures the gratuity or tip amount added by the
        customer to the transaction total. This amount is separate from the main
        transaction and is specifically allocated as a gratuity for the service
        provider. Specifying this field allows for accurate reporting and
        distribution of tips to service staff, enhancing transparency and
        fairness in transactions where tipping is customary.
      example: 5.01
      type: number
    intent:
      description: >-
        The purpose or action of the transaction, indicating the intended money
        flow direction. This field is crucial for categorising the transaction
        type and guiding the processing logic accordingly. Options include
        'Authorisation' for reserving funds on the customer's payment method,
        'Purchase' for immediate fund capture following authorisation, and
        'Payout' for sending funds to a recipient. Each intent dictates a
        specific transaction flow and affects how the transaction is handled by
        the system.
      type: string
      enum:
        - Authorisation
        - Capture
        - EstimatedAuthorisation
        - Purchase
        - Payout
        - Refund
        - Verification
        - Void
      example: Authorisation
    merchant:
      description: >-
        A unique identifier assigned by PXP to represent a merchant entity, such
        as a store, hotel, or website, within the payment processing system.
        This identifier is crucial for routing transactions to the correct
        merchant account, ensuring accurate processing, settlement, and
        reporting. Merchants receive this value upon registration or integration
        with PXP, and it must be included in transaction requests to identify
        the merchant for whom the transaction is being processed.
      example: MERCHANT-1
      type: string
      maxLength: 20
    merchantAdvice:
      description: >-
        Provides additional guidance or recommendations from the card network
        regarding the transaction. This information is particularly useful for
        understanding the reasons behind a transaction's refusal and can offer
        suggestions for next steps. For instance, it might indicate that updated
        account information is available or suggest specific actions to resolve
        the refusal. The `merchantAdvice` object includes a `code` and `message`
        to detail this advisory information, making it easier for merchants to
        take corrective action or understand the refusal context.
      properties:
        code:
          type: string
          description: >-
            An advisory code provided by the card network that categorises the
            type of advice or recommendation.
        message:
          type: string
          description: >-
            A human-readable message that provides further details or
            clarification about the advice code, potentially suggesting next
            steps or reasons for the transaction refusal.
      type: object
    merchantOrderId:
      description: >-
        A unique order reference provided by you, the merchant, to uniquely
        identify and link multiple related transactions. This identifier serves
        as a key component for tracking and reconciling transactions associated
        with specific purchase orders or service requests within your system.
        Utilizing this reference enables efficient management and querying of
        transactional data, ensuring consistency across your financial reporting
        and customer service operations.
      example: merchant_order_id
      type: string
      maxLength: 50
    merchantTransactionDate:
      description: >-
        The date and time when the transaction was initiated by the merchant.
        This timestamp is crucial for tracking the transaction throughout its
        lifecycle and for chronological order analysis. The date and time format
        follows the ISO 8601 standard, ensuring consistency and ease of
        interpretation in global contexts. It facilitates the accurate and
        precise logging of transaction initiation times, aiding in transaction
        management and reconciliation processes between the merchant and PXP.
      type: string
      format: date-time
      example: '2021-10-27 08:51:02.826445+00:00'
    merchantTransactionId:
      description: >-
        A unique transaction reference assigned by you, the merchant, to
        identify individual transactions. This identifier serves as a primary
        means of communication regarding the transaction status between you and
        PXP. It is essential to maintain uniqueness for each transaction,
        ensuring accurate tracking and communication throughout the transaction
        lifecycle.
      example: merchant_transaction_id
      type: string
      maxLength: 50
    merchantWebhookRequest:
      description: >-
        The payload of a webhook request sent to the merchant, containing
        details of a transaction event. This schema includes information such as
        the event date, merchant identifier, site, transaction method,
        transaction amounts, transaction state, transaction details, card
        details, and provider response.
      required:
        - eventDate
        - eventCategory
        - eventData
      properties:
        eventDate:
          $ref: '#/components/schemas/eventDate'
        eventCategory:
          $ref: '#/components/schemas/eventCategory'
        eventData:
          oneOf:
            - $ref: '#/components/schemas/authenticationData'
            - $ref: '#/components/schemas/transactionData'
            - $ref: '#/components/schemas/tokenData'
    merchantWebhookResponse:
      description: >-
        The response sent by the merchant to acknowledge receipt and processing
        status of a PXP webhook request. This schema includes the state of the
        response, indicating whether the processing was successful or
        encountered an error.
      properties:
        state:
          description: The current state of the response.
          enum:
            - Success
          example: Success
          type: string
      required:
        - state
    paymentAccountReference:
      description: >-
        The unique identifier assigned to a payment account, independent of the
        card number. It remains constant over the account's lifetime, even if
        the card number (PAN) changes. PAR enhances transaction security and
        privacy, serving as a secure reference point for cardholders, merchants,
        and issuers. It is used in digital transaction processing to reliably
        link transactions and accounts without exposing the actual card number.
      example: PAR12345678901234567890
      pattern: ^[A-Z0-9]{22}$
      type: string
    providerResponseName:
      description: The name of the provider that processed the transaction.
      example: PXPFinancial
      type: string
    providerResponseCode:
      description: >-
        The raw result code returned by the provider that processed the
        transaction.
      example: '00'
      type: string
    providerResponseMessage:
      description: >-
        The raw message associated with the result code from the provider that
        processed the transaction.
      example: Transaction Approved
      type: string
    providerResponseMerchantId:
      description: >-
        The unique identifier assigned by the provider to represent the merchant
        involved in the transaction processing.
      example: '77772182'
      type: string
    providerTransactionId:
      type: string
      description: >-
        A unique identifier assigned by the financial service provider for the
        transaction. It facilitates tracking, reconciliation, and support
        processes.
    providerResponseAvsResult:
      description: >-
        The Address Verification Service (AVS) result returned by the provider.
        This is a raw data indicating the outcome of the AVS check performed
        during the transaction processing. It will only be returned for card
        transactions where the fundingType is 'card'.
      type: string
      example: A
    providerResponseCvcResult:
      description: >-
        The Card Verification Code (CVC) result returned by the provider. This
        is a raw data indicating the outcome of the CVC check performed during
        the transaction processing. It will only be returned for card
        transactions where the fundingType is 'card'.
      type: string
      example: D
    schemeTransactionId:
      type: string
      description: >-
        A unique identifier assigned by the card scheme (e.g., Visa, Mastercard)
        to each transaction. This identifier is crucial for tracking,
        reconciliation, and managing the lifecycle of the transaction,
        especially in contexts like chargebacks and fraud analysis. For card
        transactions, this could be the Visa Transaction Identifier or
        MasterCard Banknet Reference Number.
      example: '1234567890123456789012'
    schemeTokenNumber:
      type: string
      description: >-
        The scheme token number represents a scheme token issued by Visa or
        Mastercard, used for subsequent transaction processing. This token
        enhances security and facilitates recurring transactions, providing a
        secure and efficient alternative to sharing sensitive card details.
      example: '4837261112345678'
    settlementDate:
      type: string
      format: date
      description: >-
        The date on which the transaction funds are settled between banks for
        MasterCard payments. This field is applicable and provided only for
        transactions processed using MasterCard. The settlement date is crucial
        for financial reconciliation and is formatted as YYYY-MM-DD.
      example: '2024-01-25'
    site:
      description: >-
        The unique site identifier associated with the transaction. This could
        represent a physical location, website, or any other distinct entity
        where the transaction occurs. The value for this field is generated by
        PXP.
      example: SITE-1
      maxLength: 20
      type: string
    tokenState:
      description: >-
        The state of the scheme token indicating its current status or action
        taken.
      enum:
        - SchemeTokenCardUpdated
        - SchemeTokenCreated
        - SchemeTokenDisabled
        - SchemeTokenUpdated
      example: SchemeTokenCreated
      type: string
    state:
      description: The current state of the transaction.
      enum:
        - Authorised
        - Captured
        - Cancelled
      example: Authorised
      type: string
    systemTransactionId:
      description: >-
        The unique identifier generated by PXP for each transaction. It serves
        as a reference for tracking and querying transactions within the PXP
        system. This Id is crucial for performing modifications or querying
        transaction details.
      example: 1ed768bb-e88a-4636-91ae-67927ccbb02b
      minimum: 36
      maximum: 36
      pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
      type: string
    transactionValue:
      description: >-
        This is the amount of the 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.
      example: 30.32
      type: number
    transactionStatus:
      description: The status of the transaction.
      enum:
        - 'Y'
        - 'N'
        - U
        - A
        - C
        - D
        - R
        - I
      example: 'Y'
      type: string
    tokenData:
      required:
        - state
        - schemeTokenProvider
        - schemeTokenId
        - externalSchemeTokenId
        - paymentAccountReference
        - schemeTokenNumber
        - expiryMonth
        - expiryYear
        - maskedPrimaryAccountNumber
      properties:
        state:
          $ref: '#/components/schemas/tokenState'
        schemeTokenProvider:
          description: >-
            Indicates hether the scheme token provider is Visa or Mastercard for
            the API notification being sent to a merchant.
          type: string
          example: Visa
          enum:
            - Mastercard
            - Visa
        schemeTokenId:
          description: >-
            The unique scheme token ID generated by PXP. It is used as a
            reference to extract the `schemeTokenNumber`.
          example: f47ac10b-58cc-4372-a567-0e02b2c3d479
          format: uuid
          type: string
        externalSchemeTokenId:
          description: >-
            A unique identifier token provided by the external payment scheme.
            This token allows merchants to process payments through different
            payment service providers (PSPs) or transaction service providers
            (TSPs). The token facilitates interoperability between different
            PSPs, enabling merchants to seamlessly integrate with and utilize
            various payment processing services.
          format: uuid
          example: ext-123456789
          type: string
        paymentAccountReference:
          description: >-
            The Payment Account Reference (PAR) is a unique identifier assigned
            to a payment account, independent of the card number. It remains
            constant over the account's lifetime, even if the card number (PAN)
            changes. PAR enhances transaction security and privacy, serving as a
            secure reference point for cardholders, merchants, and issuers. It
            is used in digital transaction processing to reliably link
            transactions and accounts without exposing the actual card number. 
            Will only be sent if the state is `SchemeTokenCreated`
          type: string
          example: acc-987654321
        expiryMonth:
          description: The expiry month [MM] of the card.
          example: '03'
          maxLength: 2
          minLength: 2
          pattern: ^[0-9]
          type: string
        expiryYear:
          description: The expiry year [YYYY] of the card.
          example: '2025'
          maxLength: 4
          minLength: 4
          pattern: ^[0-9]
          type: string
        maskedPrimaryAccountNumber:
          description: >-
            A masked version of the unique number assigned to a payment card,
            such as a credit or debit card.
          example: 411111*********1111
          maxLength: 19
          minLength: 10
          type: string
    transactionData:
      required:
        - state
        - merchant
        - site
        - transactionMethod
        - amounts
        - merchantTransactionDate
        - merchantTransactionId
        - systemTransactionId
        - fundingData
      properties:
        state:
          $ref: '#/components/schemas/state'
        merchant:
          $ref: '#/components/schemas/merchant'
        site:
          $ref: '#/components/schemas/site'
        transactionMethod:
          $ref: '#/components/schemas/transactionMethod'
        amounts:
          type: object
          required:
            - currencyCode
            - transaction
          properties:
            currencyCode:
              $ref: '#/components/schemas/currencyCode'
            transactionValue:
              $ref: '#/components/schemas/transactionValue'
            gratuityValue:
              $ref: '#/components/schemas/gratuityValue'
        approvalCode:
          $ref: '#/components/schemas/approvalCode'
        merchantTransactionDate:
          $ref: '#/components/schemas/merchantTransactionDate'
        merchantOrderId:
          $ref: '#/components/schemas/merchantOrderId'
        merchantTransactionId:
          $ref: '#/components/schemas/merchantTransactionId'
        systemTransactionId:
          $ref: '#/components/schemas/systemTransactionId'
        providerTransactionId:
          $ref: '#/components/schemas/providerTransactionId'
        fundingData:
          description: Funding data specifying the payment method used for the transaction.
          oneOf:
            - $ref: '#/components/schemas/card'
    transactionMethod:
      description: >-
        Comprehensive details about the intent, capture method, and origin of a
        transaction.
      required:
        - entryType
        - fundingType
        - intent
      properties:
        entryType:
          $ref: '#/components/schemas/entryType'
        fundingType:
          $ref: '#/components/schemas/fundingType'
        intent:
          $ref: '#/components/schemas/intent'
      type: object
