openapi: 3.0.3
info:
  title: POS transaction service API
  description: This is an API reference for the Point of Sale transaction 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:
  /pos-transactions:
    post:
      summary: Initiate a POS transaction
      description: >-
        The /pos-transactions endpoint enables the initiation of instore
        transactions, supporting various transaction methods, including card and
        alternative payments.
      operationId: initiate-pos-transaction
      requestBody:
        description: Initiate a transaction
        content:
          application/json:
            schema:
              description: >-
                The transactionRequest object encapsulates all essential details
                required for initiating and processing a transaction. It
                includes funding data, address verification, transaction
                amounts, merchant information, shopper details, recurring
                payment information, site identifier, 3D Secure details, and
                transaction method.
              properties:
                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
                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
                pointOfInteraction:
                  description: >-
                    The pointOfInteraction object captures detailed information
                    about the device and environment where a card present
                    transaction takes place. It includes various attributes that
                    help identify and describe the capabilities and
                    configurations of the point of sale (POS) device.
                  properties:
                    pointOfSaleId:
                      type: string
                      description: >
                        "A PXP unique identifier for the specific point of sale
                        device, often assigned by the merchant or payment
                        processor."
                      example: ACME-001
                      maxLength: 20
                    language:
                      description: >
                        "ISO 639-1 language code representing the display
                        language."


                        Possible Values:

                        - `CA`: Catalan

                        - `DA`: Danish

                        - `DE`: German

                        - `EN`: English

                        - `ES`: Spanish

                        - `FR`: French

                        - `HU`: Hungarian

                        - `IS`: Icelandic

                        - `IT`: Italian

                        - `NL`: Dutch

                        - `NO`: Norwegian

                        - `PL`: Polish

                        - `PT`: Portuguese

                        - `SV`: Swedish
                      type: string
                      maxLength: 2
                      enum:
                        - CA
                        - DA
                        - DE
                        - EN
                        - ES
                        - FR
                        - HU
                        - IS
                        - IT
                        - NL
                        - 'NO'
                        - PL
                        - PT
                        - SV
                      example: EN
                    storeAndForwardType:
                      description: >
                        Store and Forward is a mechanism used for handling
                        transactions when the merchant's connection to the PXP
                        gateway is disrupted. It securely stores transactions
                        offline until communications are re-established with the
                        gateway. The types are:

                        Possible Values:

                        - `None`: No store and forward mechanism is used.

                        - `ForcedStoreAndForward`: Typically used in situations
                        like cruise liners with poor satellite communications.
                        Transactions are automatically forced into store and
                        forward mode. Once communication is re-established, the
                        transactions are sent to the gateway to perform online
                        authorisation with the acquirer via the PXP gateway.
                      enum:
                        - None
                        - ForcedStoreAndForward
                      example: None
                      type: string
                    invokeKeyed:
                      description: >-
                        Indicates whether the merchant wants to initiate a keyed
                        transaction on the device. Keyed transactions involve
                        manually entering the card details on the point of sale
                        (POS) device.
                      type: boolean
                      example: true
                      default: false
                merchantTransactionId:
                  description: >-
                    Represents 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: This_is_my_merchant_transaction_id
                  type: string
                  maxLength: 50
                merchantTransactionDate:
                  description: >-
                    Specifies 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'
                amounts:
                  description: >-
                    Details of the amount including transaction and gratuity
                    values and its associated currency.
                  type: object
                  required:
                    - currencyCode
                    - transaction
                  properties:
                    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.
                      example: EUR
                      type: string
                      minLength: 3
                      maxLength: 3
                    transaction:
                      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
                    gratuity:
                      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
                transactionMethod:
                  description: >-
                    The transaction method provides comprehensive details about
                    the intent, capture method, and origin of a transaction.
                  properties:
                    entryType:
                      description: >-
                        Specifies 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:
                        - Instore
                      example: Instore
                    fundingType:
                      description: >-
                        Specifies 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
                    intent:
                      description: >-
                        Specifies the purpose or action of the transaction,
                        indicating the intended money flow direction. This field
                        is crucial for categorizing 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
                        - EstimatedAuthorisation
                        - Purchase
                        - Payout
                        - Refund
                        - Verification
                      example: Authorisation
                  type: object
                  required:
                    - entryType
                    - fundingType
                    - intent
              required:
                - merchant
                - site
                - merchantTransactionId
                - merchantTransactionDate
                - amounts
                - transactionMethod
              type: object
            examples:
              Instore Card Authorisation:
                value:
                  pointOfInteraction:
                    pointOfSaleId: POS-1
                    language: EN
                    storeAndForwardType: None
                    invokeKeyed: 'False'
                  merchant: MERCHANT-1
                  site: SITE-1
                  merchantTransactionId: This_is_my_merchant_transaction_id
                  merchantTransactionDate: '2024-01-27 08:51:02.826445+00:00'
                  amounts:
                    transaction: 30.32
                    currencyCode: EUR
                  transactionMethod:
                    intent: Authorisation
                    entryType: Instore
                    fundingType: Card
              Instore Card Estimated Authorisation:
                value:
                  pointOfInteraction:
                    pointOfSaleId: POS-1
                    language: EN
                    storeAndForwardType: None
                    invokeKeyed: 'False'
                  merchant: MERCHANT-1
                  site: SITE-1
                  merchantTransactionId: This_is_my_merchant_transaction_id
                  merchantTransactionDate: '2024-01-27 08:51:02.826445+00:00'
                  amounts:
                    transaction: 30.32
                    currencyCode: EUR
                  transactionMethod:
                    intent: EstimatedAuthorisation
                    entryType: Instore
                    fundingType: Card
              Instore Card Purchase:
                value:
                  pointOfInteraction:
                    pointOfSaleId: POS-1
                    language: EN
                    storeAndForwardType: None
                    invokeKeyed: 'False'
                  merchant: MERCHANT-1
                  site: SITE-1
                  merchantTransactionId: This_is_my_merchant_transaction_id
                  merchantTransactionDate: '2024-01-27 08:51:02.826445+00:00'
                  amounts:
                    transaction: 30.32
                    currencyCode: EUR
                  transactionMethod:
                    intent: Purchase
                    entryType: Instore
                    fundingType: Card
              Instore Card Refund:
                value:
                  pointOfInteraction:
                    pointOfSaleId: POS-1
                    language: EN
                    storeAndForwardType: None
                    invokeKeyed: 'False'
                  merchant: MERCHANT-1
                  site: SITE-1
                  merchantTransactionId: This_is_my_merchant_transaction_id
                  merchantTransactionDate: '2024-01-27 08:51:02.826445+00:00'
                  amounts:
                    transaction: 30.32
                    currencyCode: EUR
                  transactionMethod:
                    intent: Refund
                    entryType: Instore
                    fundingType: Card
              Instore Card Verification:
                value:
                  pointOfInteraction:
                    pointOfSaleId: POS-1
                    language: en
                    storeAndForwardType: None
                    invokeKeyed: 'False'
                  merchant: MERCHANT-1
                  site: SITE-1
                  merchantTransactionId: This_is_my_merchant_transaction_id
                  merchantTransactionDate: '2024-01-27 08:51:02.826445+00:00'
                  amounts:
                    transaction: 30.32
                    currencyCode: EUR
                  transactionMethod:
                    intent: Verification
                    entryType: Instore
                    fundingType: Card
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                description: >-
                  The transactionResponse object provides comprehensive details
                  regarding the status and data associated with the transaction.
                  It includes information about the current state of the
                  transaction, transaction-specific details, funding data
                  related information, and the response received from the
                  payment provider.
                properties:
                  state:
                    description: The current state of the transaction.
                    enum:
                      - Authorised
                      - Captured
                      - Cancelled
                      - Error
                      - Refused
                    example: Authorised
                    type: string
                  stateData:
                    type: object
                    description: Key value pair for various state data
                    properties:
                      code:
                        description: This is the state Details Code
                        type: string
                      message:
                        description: This is the state Details Message
                        type: string
                    example:
                      code: '12345'
                      message: Merchant not found
                  approvalCode:
                    description: >-
                      A unique identifier code provided by the authorizing
                      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]
                  merchantTransactionDate:
                    description: >-
                      Specifies 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: >-
                      Represents 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: This_is_my_merchant_transaction_id
                    type: string
                    maxLength: 50
                  systemTransactionId:
                    description: >-
                      The system transaction Id is a 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
                  providerTransactionId:
                    type: string
                    description: >-
                      A unique identifier assigned by the financial service
                      provider for the transaction. It facilitates tracking,
                      reconciliation, and support processes.
                  fundingData:
                    description: >-
                      Funding data specifying the payment method used for the
                      transaction. It includes essential information about a
                      card involved in a transaction, such as its scheme,
                      payment account reference, and token IDs. Additionally, it
                      provides verification results for enhanced security, such
                      as CVC and AVS checks, enabling you to ensure transaction
                      integrity and mitigate fraud risks efficiently. This
                      object is returned if the `transactionMethod.fundingType`
                      is `card` or `schemeToken`.
                    type: object
                    properties:
                      maskedPrimaryAccountNumber:
                        description: >-
                          The card's primary account number (PAN) masked for
                          security, typically showing only the last four digits.
                        type: string
                        example: 463242******1234
                      expiryMonth:
                        description: This is the expiry month [MM] of the card.
                        type: string
                        example: '12'
                      expiryYear:
                        description: This is the expiry year [YYYY] of the card.
                        type: string
                        example: '2026'
                      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]+$
                      gatewayTokenId:
                        description: >-
                          The gateway token Id represents 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
                      emvDataResponse:
                        description: >-
                          Response containing EMV (Europay, MasterCard, and
                          Visa) data from a payment transaction.
                        type: object
                        properties:
                          applicationId:
                            description: >-
                              A unique identifier for the application used
                              during the EMV transaction.
                            type: string
                            example: A0000000031010
                          applicationLabel:
                            description: >-
                              The label or name of the application selected for
                              the transaction, typically representing the card
                              brand.
                            type: string
                            example: VISA CREDIT
                          authorisationResponseCode:
                            description: >-
                              The response code indicating the outcome of the
                              authorisation request.
                            type: string
                            example: '00'
                          cardHolderVerificationMethodResults:
                            description: >-
                              The results of the Cardholder Verification Method
                              (CVM) used in the transaction, such as PIN
                              verification or signature.
                            type: string
                            enum:
                              - Pin verified
                              - Signature verified
                              - No CVM required
                          panSequenceNumber:
                            description: >-
                              The sequence number that differentiates cards with
                              the same Primary Account Number (PAN) issued to
                              the same account holder.
                            type: string
                            example: '01'
                          preferredName:
                            description: >-
                              The preferred name of the application as displayed
                              on the terminal during the transaction.
                            type: string
                            example: Visa
                      providerResponse:
                        description: >-
                          The response from the payment provider containing
                          details about the transaction processing outcome.
                        properties:
                          provider:
                            description: >-
                              The name of the provider that processed the
                              transaction.
                            example: PXPFinancial
                            type: string
                          code:
                            description: >-
                              The raw result code returned by the provider that
                              processed the transaction.
                            example: '00'
                            type: string
                          message:
                            description: >-
                              The raw message associated with the result code
                              from the provider that processed the transaction.
                            example: Transaction Approved
                            type: string
                          merchantId:
                            description: >-
                              This is the unique identifier assigned by the
                              provider to represent the merchant involved in the
                              transaction processing.
                            example: '77772182'
                            type: string
                          terminalId:
                            description: >-
                              This is the unique identifier assigned by the
                              provider to represent the terminall involved in
                              the transaction processing.
                            example: '7777218212'
                            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.
                            example: PAR12345678901234567890
                            pattern: ^[A-Z0-9]{22}$
                            type: string
                          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'
                          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 categorizes 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
                          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'
                          issuerResponseCode:
                            type: string
                            description: >-
                              A two-character code that indicates the result of
                              the transaction authorisation.
                            example: '00'
                            x-readme-ref-name: issuerResponseCode
                type: object
              examples:
                Instore Card Authorised:
                  value:
                    state: Authorised
                    approvalCode: '123456'
                    merchantTransactionDate: '2024-01-27 08:51:02.826445+00:00'
                    merchantTransactionId: This_is_my_merchant_transaction_id
                    systemTransactionId: 1ed768bb-e88a-4636-91ae-67927ccbb02b
                    providerTransactionId: 1ed768bb-e88a-4636-91ae-67927ccbb02b
                    fundingData:
                      cardScheme: Visa
                      gatewayTokenId: 1ed768bb-e88a-4636-91ae-67927ccbb02b
                      providerResponse:
                        provider: PXPFinancial
                        code: '00'
                        message: Approved
                        merchantId: '77772182'
                        emvDataResponse:
                          authorisationResponseCode: 8A
                          issuerAuthenticationData: ''
                          issuerScriptTemplate1: ''
                          issuerScriptTemplate2: ''
                        paymentAccountReference: PAR12345678901234567890
                        schemeTransactionId: TX1234567890123456
                        issuerResponseCode: '00'
                Instore Card Refused:
                  value:
                    state: Refused
                    stateData:
                      code: PRO0006
                      message: Do not Hounour
                    merchantTransactionDate: '2024-01-27 08:51:02.826445+00:00'
                    merchantTransactionId: This_is_my_merchant_transaction_id
                    systemTransactionId: 1ed768bb-e88a-4636-91ae-67927ccbb02b
                    providerTransactionId: 1ed768bb-e88a-4636-91ae-67927ccbb02b
                    fundingData:
                      cardScheme: Visa
                      gatewayTokenId: 1ed768bb-e88a-4636-91ae-67927ccbb02b
                      providerResponse:
                        provider: PXPFinancial
                        code: '05'
                        message: Do not honour
                        merchantId: '77772182'
                        emvDataResponse:
                          authorisationResponseCode: 8A
                          issuerAuthenticationData: ''
                          issuerScriptTemplate1: ''
                          issuerScriptTemplate2: ''
                        merchantAdvice:
                          code: '01'
                          message: New account information available
                Instore Card Error (General):
                  value:
                    state: Error
                    stateData:
                      code: GEN0001
                      message: General Error
                    merchantTransactionDate: '2024-01-27 08:51:02.826445+00:00'
                    merchantTransactionId: This_is_my_merchant_transaction_id
                    systemTransactionId: 1ed768bb-e88a-4636-91ae-67927ccbb02b
                    fundingData:
                      cardScheme: Visa
                      gatewayTokenId: 1ed768bb-e88a-4636-91ae-67927ccbb02b
                Instore Card Error (Communication Timeout):
                  value:
                    state: Error
                    stateData:
                      code: PRO0002
                      message: Communication Timeout
                    merchantTransactionDate: '2024-01-27 08:51:02.826445+00:00'
                    merchantTransactionId: This_is_my_merchant_transaction_id
                    systemTransactionId: 1ed768bb-e88a-4636-91ae-67927ccbb02b
                    fundingData:
                      cardScheme: Visa
                      gatewayTokenId: 1ed768bb-e88a-4636-91ae-67927ccbb02b
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                description: >-
                  Indicates a client-side error where the request could not be
                  processed due to malformed syntax, invalid data, or missing
                  information. This response is used across different
                  transaction methods such as cards, APMs, bank transfers, and
                  wallets, signaling the need for the requester to modify their
                  input. It encompasses errors ranging from incorrect field
                  formats to missing required parameters.
                example:
                  correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                  details: []
                  errorCode: CAR0003
                  errorReason: Invalid Card Details Provided
                properties:
                  correlationId:
                    description: >-
                      A unique identifier generated by PXP, serving as a
                      critical tool for tracing and diagnosing transaction
                      errors. This Id allows for the precise location of
                      transactional issues, facilitating swift investigation and
                      resolution by correlating specific transaction attempts or
                      processes with error logs. Essential for support and
                      operational teams, the correlationId enhances PXP's
                      ability to maintain high-quality service and transaction
                      reliability.
                    example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                    type: string
                  details:
                    description: TBC
                    example:
                      - '''''$.site - The site field is required.'
                    items: {}
                    type: array
                  errorCode:
                    description: |
                      This is the error code returned for the operation.
                    example: INVALID_REQUEST
                    type: string
                  errorReason:
                    description: |
                      This is the error reason returned for the operation.
                    example: One or more validation errors occurred.
                    type: string
                type: object
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                description: >-
                  This response denotes an unauthorized request due to failed
                  authentication or missing credentials, applicable across
                  various payment methods. It suggests the system cannot verify
                  the requester's identity or validate the transaction's
                  legitimacy, necessitating authentication details or proper
                  credentials.
                example:
                  correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                  details: []
                  errorCode: CAR0004
                  errorReason: Authentication Failed for Card Transaction
                properties:
                  correlationId:
                    description: >-
                      A unique identifier generated by PXP, serving as a
                      critical tool for tracing and diagnosing transaction
                      errors. This Id allows for the precise location of
                      transactional issues, facilitating swift investigation and
                      resolution by correlating specific transaction attempts or
                      processes with error logs. Essential for support and
                      operational teams, the correlationId enhances PXP's
                      ability to maintain high-quality service and transaction
                      reliability.
                    example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                    type: string
                  details:
                    description: TBC
                    example:
                      - '''''$.site - The site field is required.'
                    items: {}
                    type: array
                  errorCode:
                    description: |
                      This is the error code returned for the operation.
                    example: INVALID_REQUEST
                    type: string
                  errorReason:
                    description: |
                      This is the error reason returned for the operation.
                    example: One or more validation errors occurred.
                    type: string
                type: object
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                description: >-
                  Signifies a request is understood but refused by the server,
                  often due to insufficient permissions or access rules. This
                  generic error is relevant for all transaction types,
                  indicating the action requested by the user is forbidden
                  despite successful authentication.
                example:
                  correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                  details: []
                  errorCode: CAR0005
                  errorReason: Transaction Not Permitted
                properties:
                  correlationId:
                    description: >-
                      A unique identifier generated by PXP, serving as a
                      critical tool for tracing and diagnosing transaction
                      errors. This Id allows for the precise location of
                      transactional issues, facilitating swift investigation and
                      resolution by correlating specific transaction attempts or
                      processes with error logs. Essential for support and
                      operational teams, the correlationId enhances PXP's
                      ability to maintain high-quality service and transaction
                      reliability.
                    example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                    type: string
                  details:
                    description: TBC
                    example:
                      - '''''$.site - The site field is required.'
                    items: {}
                    type: array
                  errorCode:
                    description: |
                      This is the error code returned for the operation.
                    example: INVALID_REQUEST
                    type: string
                  errorReason:
                    description: |
                      This is the error reason returned for the operation.
                    example: One or more validation errors occurred.
                    type: string
                type: object
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                description: >-
                  Occurs when the server can find no match for the requested
                  resource, applicable to any transaction type. This response
                  indicates the specified resource, whether it be transaction
                  details, user information, or other data, does not exist or
                  cannot be found.
                example:
                  correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                  details: []
                  errorCode: CAR0006
                  errorReason: Card Transaction Details Not Found
                properties:
                  correlationId:
                    description: >-
                      A unique identifier generated by PXP, serving as a
                      critical tool for tracing and diagnosing transaction
                      errors. This Id allows for the precise location of
                      transactional issues, facilitating swift investigation and
                      resolution by correlating specific transaction attempts or
                      processes with error logs. Essential for support and
                      operational teams, the correlationId enhances PXP's
                      ability to maintain high-quality service and transaction
                      reliability.
                    example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                    type: string
                  details:
                    description: TBC
                    example:
                      - '''''$.site - The site field is required.'
                    items: {}
                    type: array
                  errorCode:
                    description: |
                      This is the error code returned for the operation.
                    example: INVALID_REQUEST
                    type: string
                  errorReason:
                    description: |
                      This is the error reason returned for the operation.
                    example: One or more validation errors occurred.
                    type: string
                type: object
        '413':
          description: Payload too large
          content:
            application/json:
              schema:
                description: >-
                  Indicates that the server refuses to process the request
                  because the request payload is larger than the server is
                  willing or able to process. This error is applicable across
                  all transaction types, signaling that the data submitted
                  exceeds the maximum allowed size. Clients should reduce the
                  size of their request before retrying. This response helps
                  maintain efficient processing and prevents overloading the
                  server with excessive data.
                example:
                  correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                  details: []
                  errorCode: TOK0004
                  errorReason: Token Request Payload Too Large
                properties:
                  correlationId:
                    description: >-
                      A unique identifier generated by PXP, serving as a
                      critical tool for tracing and diagnosing transaction
                      errors. This Id allows for the precise location of
                      transactional issues, facilitating swift investigation and
                      resolution by correlating specific transaction attempts or
                      processes with error logs. Essential for support and
                      operational teams, the correlationId enhances PXP's
                      ability to maintain high-quality service and transaction
                      reliability.
                    example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                    type: string
                  details:
                    description: TBC
                    example:
                      - '''''$.site - The site field is required.'
                    items: {}
                    type: array
                  errorCode:
                    description: |
                      This is the error code returned for the operation.
                    example: INVALID_REQUEST
                    type: string
                  errorReason:
                    description: |
                      This is the error reason returned for the operation.
                    example: One or more validation errors occurred.
                    type: string
                type: object
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                description: >-
                  Signifies that the server understands the content type of the
                  request and the syntax is correct, but it cannot process the
                  contained instructions. This response is particularly relevant
                  when validating request fields across various transaction
                  methods, including cards, APMs, bank transfers, and wallets,
                  where specific field values do not meet the expected formats
                  or logical validations. It prompts a review and correction of
                  the submitted data to align with the required standards or
                  constraints.
                example:
                  correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                  details: []
                  errorCode: CAR0010
                  errorReason: Invalid Transaction Data Format
                properties:
                  correlationId:
                    description: >-
                      A unique identifier generated by PXP, serving as a
                      critical tool for tracing and diagnosing transaction
                      errors. This Id allows for the precise location of
                      transactional issues, facilitating swift investigation and
                      resolution by correlating specific transaction attempts or
                      processes with error logs. Essential for support and
                      operational teams, the correlationId enhances PXP's
                      ability to maintain high-quality service and transaction
                      reliability.
                    example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                    type: string
                  details:
                    description: TBC
                    example:
                      - '''''$.site - The site field is required.'
                    items: {}
                    type: array
                  errorCode:
                    description: |
                      This is the error code returned for the operation.
                    example: INVALID_REQUEST
                    type: string
                  errorReason:
                    description: |
                      This is the error reason returned for the operation.
                    example: One or more validation errors occurred.
                    type: string
                type: object
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                description: >-
                  Represents a generic error response indicating an internal
                  server error. This response is used when the server encounters
                  an unexpected condition that prevents it from fulfilling the
                  request, which could range from temporary server malfunctions
                  to more complex issues within the server's processing of
                  specific transactions. It signals that the problem lies with
                  the server's internal operations rather than the request
                  itself. This type of error requires server-side investigation
                  and potentially corrective action to resolve the underlying
                  issue.
                example:
                  correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                  details: []
                  errorCode: GEN0008
                  errorReason: Unexpected Internal Error
                properties:
                  correlationId:
                    description: >-
                      A unique identifier generated by PXP, serving as a
                      critical tool for tracing and diagnosing transaction
                      errors. This Id allows for the precise location of
                      transactional issues, facilitating swift investigation and
                      resolution by correlating specific transaction attempts or
                      processes with error logs. Essential for support and
                      operational teams, the correlationId enhances PXP's
                      ability to maintain high-quality service and transaction
                      reliability.
                    example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                    type: string
                  details:
                    description: TBC
                    example:
                      - '''''$.site - The site field is required.'
                    items: {}
                    type: array
                  errorCode:
                    description: |
                      This is the error code returned for the operation.
                    example: INVALID_REQUEST
                    type: string
                  errorReason:
                    description: |
                      This is the error reason returned for the operation.
                    example: One or more validation errors occurred.
                    type: string
                type: object
        default:
          description: Error
          content:
            application/json:
              schema:
                description: >-
                  Defines the structure for reporting errors encountered during
                  the transaction process. This object includes a unique
                  `correlationId` for tracking and diagnosing the issue, an
                  `errorCode` identifying the type of error, and an
                  `errorReason` providing a descriptive explanation of the
                  error. Additionally, a `details` array may contain further
                  information or context about the error, offering insights
                  necessary for troubleshooting and resolution. This structured
                  approach ensures precise error reporting and aids in efficient
                  error management and support processes.
                properties:
                  correlationId:
                    description: >-
                      A unique identifier generated to correlate the error with
                      a specific transaction attempt, facilitating easier
                      tracking and resolution of issues.
                    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 standardized code that categorizes 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
  /pos-transactions/legacy:
    post:
      summary: Initiate a POS transaction (legacy)
      description: >-
        The /pos-transactions endpoint enables the initiation of instore
        transactions, supporting various transaction methods, including card and
        alternative payments.
      operationId: initiate-pos-transaction-legacy
      requestBody:
        description: Initiate a transaction
        content:
          application/json:
            schema:
              description: >-
                The transactionRequest object encapsulates all essential details
                required for initiating and processing a transaction. It
                includes funding data, address verification, transaction
                amounts, merchant information, shopper details, recurring
                payment information, site identifier, 3D Secure details, and
                transaction method.
              properties:
                credentials:
                  description: >-
                    Credentials used for authentication. This is only to be used
                    when processing transactions to the `PXP ANYpay` platform.
                  properties:
                    username:
                      description: The username used for authentication.
                    password:
                      description: The password used for authentication.
                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
                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
                pointOfInteraction:
                  description: >-
                    The pointOfInteraction object captures detailed information
                    about the device and environment where a card present
                    transaction takes place. It includes various attributes that
                    help identify and describe the capabilities and
                    configurations of the point of sale (POS) device.
                  properties:
                    pointOfSaleId:
                      type: string
                      description: >
                        "A PXP unique identifier for the specific point of sale
                        device, often assigned by the merchant or payment
                        processor."
                      example: ACME-001
                      maxLength: 20
                    language:
                      description: >
                        "ISO 639-1 language code representing the display
                        language."


                        Possible Values:

                        - `CA`: Catalan

                        - `DA`: Danish

                        - `DE`: German

                        - `EN`: English

                        - `ES`: Spanish

                        - `FR`: French

                        - `HU`: Hungarian

                        - `IS`: Icelandic

                        - `IT`: Italian

                        - `NL`: Dutch

                        - `NO`: Norwegian

                        - `PL`: Polish

                        - `PT`: Portuguese

                        - `SV`: Swedish
                      type: string
                      maxLength: 2
                      enum:
                        - CA
                        - DA
                        - DE
                        - EN
                        - ES
                        - FR
                        - HU
                        - IS
                        - IT
                        - NL
                        - 'NO'
                        - PL
                        - PT
                        - SV
                      example: EN
                    storeAndForwardType:
                      description: >
                        Store and Forward is a mechanism used for handling
                        transactions when the merchant's connection to the PXP
                        gateway is disrupted. It securely stores transactions
                        offline until communications are re-established with the
                        gateway. The types are:

                        Possible Values:

                        - `None`: No store and forward mechanism is used.

                        - `ForcedStoreAndForward`: Typically used in situations
                        like cruise liners with poor satellite communications.
                        Transactions are automatically forced into store and
                        forward mode. Once communication is re-established, the
                        transactions are sent to the gateway to perform online
                        authorisation with the acquirer via the PXP gateway.
                      enum:
                        - None
                        - ForcedStoreAndForward
                      example: None
                      type: string
                    invokeKeyed:
                      description: >-
                        Indicates whether the merchant wants to initiate a keyed
                        transaction on the device. Keyed transactions involve
                        manually entering the card details on the point of sale
                        (POS) device.
                      type: boolean
                      example: true
                      default: false
                merchantTransactionId:
                  description: >-
                    Represents 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: This_is_my_merchant_transaction_id
                  type: string
                  maxLength: 50
                merchantTransactionDate:
                  description: >-
                    Specifies 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'
                amounts:
                  description: >-
                    Details of the amount including transaction and gratuity
                    values and its associated currency.
                  type: object
                  required:
                    - currencyCode
                    - transaction
                  properties:
                    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.
                      example: EUR
                      type: string
                      minLength: 3
                      maxLength: 3
                    transaction:
                      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
                    gratuity:
                      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
                transactionMethod:
                  description: >-
                    The transaction method provides comprehensive details about
                    the intent, capture method, and origin of a transaction.
                  properties:
                    entryType:
                      description: >-
                        Specifies 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:
                        - Instore
                      example: Instore
                    fundingType:
                      description: >-
                        Specifies 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
                    intent:
                      description: >-
                        Specifies the purpose or action of the transaction,
                        indicating the intended money flow direction. This field
                        is crucial for categorizing 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
                        - EstimatedAuthorisation
                        - Purchase
                        - Payout
                        - Refund
                        - Verification
                      example: Authorisation
                  type: object
                  required:
                    - entryType
                    - fundingType
                    - intent
              required:
                - merchant
                - site
                - merchantTransactionId
                - merchantTransactionDate
                - amounts
                - transactionMethod
              type: object
            examples:
              Instore Card Authorisation:
                value:
                  pointOfInteraction:
                    pointOfSaleId: POS-1
                    language: EN
                    storeAndForwardType: None
                    invokeKeyed: 'False'
                  merchant: MERCHANT-1
                  site: SITE-1
                  merchantTransactionId: This_is_my_merchant_transaction_id
                  merchantTransactionDate: '2024-01-27 08:51:02.826445+00:00'
                  amounts:
                    transaction: 30.32
                    currencyCode: EUR
                  transactionMethod:
                    intent: Authorisation
                    entryType: Instore
                    fundingType: Card
              Instore Card Authorisation (Legacy):
                value:
                  credentials:
                    username: testusername
                    password: testpassword
                  pointOfInteraction:
                    pointOfSaleId: POS-1
                    language: EN
                    storeAndForwardType: None
                    invokeKeyed: 'False'
                  merchant: MERCHANT-1
                  site: SITE-1
                  merchantTransactionId: This_is_my_merchant_transaction_id
                  merchantTransactionDate: '2024-01-27 08:51:02.826445+00:00'
                  amounts:
                    transaction: 30.32
                    currencyCode: EUR
                  transactionMethod:
                    intent: Authorisation
                    entryType: Instore
                    fundingType: Card
              Instore Card Estimated Authorisation:
                value:
                  pointOfInteraction:
                    pointOfSaleId: POS-1
                    language: EN
                    storeAndForwardType: None
                    invokeKeyed: 'False'
                  merchant: MERCHANT-1
                  site: SITE-1
                  merchantTransactionId: This_is_my_merchant_transaction_id
                  merchantTransactionDate: '2024-01-27 08:51:02.826445+00:00'
                  amounts:
                    transaction: 30.32
                    currencyCode: EUR
                  transactionMethod:
                    intent: EstimatedAuthorisation
                    entryType: Instore
                    fundingType: Card
              Instore Card Estimated Authorisation (Legacy):
                value:
                  credentials:
                    username: testusername
                    password: testpassword
                  pointOfInteraction:
                    pointOfSaleId: POS-1
                    language: EN
                    storeAndForwardType: None
                    invokeKeyed: 'False'
                  merchant: MERCHANT-1
                  site: SITE-1
                  merchantTransactionId: This_is_my_merchant_transaction_id
                  merchantTransactionDate: '2024-01-27 08:51:02.826445+00:00'
                  amounts:
                    transaction: 30.32
                    currencyCode: EUR
                  transactionMethod:
                    intent: EstimatedAuthorisation
                    entryType: Instore
                    fundingType: Card
              Instore Card Purchase:
                value:
                  pointOfInteraction:
                    pointOfSaleId: POS-1
                    language: EN
                    storeAndForwardType: None
                    invokeKeyed: 'False'
                  merchant: MERCHANT-1
                  site: SITE-1
                  merchantTransactionId: This_is_my_merchant_transaction_id
                  merchantTransactionDate: '2024-01-27 08:51:02.826445+00:00'
                  amounts:
                    transaction: 30.32
                    currencyCode: EUR
                  transactionMethod:
                    intent: Purchase
                    entryType: Instore
                    fundingType: Card
              Instore Card Purchase (Legacy):
                value:
                  credentials:
                    username: testusername
                    password: testpassword
                  pointOfInteraction:
                    pointOfSaleId: POS-1
                    language: EN
                    storeAndForwardType: None
                    invokeKeyed: 'False'
                  merchant: MERCHANT-1
                  site: SITE-1
                  merchantTransactionId: This_is_my_merchant_transaction_id
                  merchantTransactionDate: '2024-01-27 08:51:02.826445+00:00'
                  amounts:
                    transaction: 30.32
                    currencyCode: EUR
                  transactionMethod:
                    intent: Purchase
                    entryType: Instore
                    fundingType: Card
              Instore Card Refund:
                value:
                  pointOfInteraction:
                    pointOfSaleId: POS-1
                    language: EN
                    storeAndForwardType: None
                    invokeKeyed: 'False'
                  merchant: MERCHANT-1
                  site: SITE-1
                  merchantTransactionId: This_is_my_merchant_transaction_id
                  merchantTransactionDate: '2024-01-27 08:51:02.826445+00:00'
                  amounts:
                    transaction: 30.32
                    currencyCode: EUR
                  transactionMethod:
                    intent: Refund
                    entryType: Instore
                    fundingType: Card
              Instore Card Refund (Legacy):
                value:
                  credentials:
                    username: testusername
                    password: testpassword
                  pointOfInteraction:
                    pointOfSaleId: POS-1
                    language: EN
                    storeAndForwardType: None
                    invokeKeyed: 'False'
                  merchant: MERCHANT-1
                  site: SITE-1
                  merchantTransactionId: This_is_my_merchant_transaction_id
                  merchantTransactionDate: '2024-01-27 08:51:02.826445+00:00'
                  amounts:
                    transaction: 30.32
                    currencyCode: EUR
                  transactionMethod:
                    intent: Refund
                    entryType: Instore
                    fundingType: Card
              Instore Card Verification:
                value:
                  pointOfInteraction:
                    pointOfSaleId: POS-1
                    language: en
                    storeAndForwardType: None
                    invokeKeyed: 'False'
                  merchant: MERCHANT-1
                  site: SITE-1
                  merchantTransactionId: This_is_my_merchant_transaction_id
                  merchantTransactionDate: '2024-01-27 08:51:02.826445+00:00'
                  amounts:
                    transaction: 30.32
                    currencyCode: EUR
                  transactionMethod:
                    intent: Verification
                    entryType: Instore
                    fundingType: Card
              Instore Card Verification (Legacy):
                value:
                  credentials:
                    username: testusername
                    password: testpassword
                  pointOfInteraction:
                    pointOfSaleId: POS-1
                    language: EN
                    storeAndForwardType: None
                    invokeKeyed: 'False'
                  merchant: MERCHANT-1
                  site: SITE-1
                  merchantTransactionId: This_is_my_merchant_transaction_id
                  merchantTransactionDate: '2024-01-27 08:51:02.826445+00:00'
                  amounts:
                    transaction: 30.32
                    currencyCode: EUR
                  transactionMethod:
                    intent: Verification
                    entryType: Instore
                    fundingType: Card
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                description: >-
                  The transactionResponse object provides comprehensive details
                  regarding the status and data associated with the transaction.
                  It includes information about the current state of the
                  transaction, transaction-specific details, funding data
                  related information, and the response received from the
                  payment provider.
                properties:
                  state:
                    description: The current state of the transaction.
                    enum:
                      - Authorised
                      - Captured
                      - Cancelled
                      - Error
                      - Refused
                    example: Authorised
                    type: string
                  stateData:
                    type: object
                    description: Key value pair for various state data
                    properties:
                      code:
                        description: This is the state Details Code
                        type: string
                      message:
                        description: This is the state Details Message
                        type: string
                    example:
                      code: '12345'
                      message: Merchant not found
                  approvalCode:
                    description: >-
                      A unique identifier code provided by the authorizing
                      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]
                  merchantTransactionDate:
                    description: >-
                      Specifies 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: >-
                      Represents 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: This_is_my_merchant_transaction_id
                    type: string
                    maxLength: 50
                  systemTransactionId:
                    description: >-
                      The system transaction Id is a 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
                  providerTransactionId:
                    type: string
                    description: >-
                      A unique identifier assigned by the financial service
                      provider for the transaction. It facilitates tracking,
                      reconciliation, and support processes.
                  fundingData:
                    type: object
                    description: >-
                      Funding data specifying the payment method used for the
                      transaction. It includes essential information about a
                      card involved in a transaction, such as its scheme,
                      payment account reference, and token IDs. Additionally, it
                      provides verification results for enhanced security, such
                      as CVC and AVS checks, enabling you to ensure transaction
                      integrity and mitigate fraud risks efficiently. This
                      object is returned if the `transactionMethod.fundingType`
                      is `card` or `schemeToken`.
                    properties:
                      maskedPrimaryAccountNumber:
                        description: >-
                          The card's primary account number (PAN) masked for
                          security, typically showing only the last four digits.
                        type: string
                        example: 463242******1234
                      expiryMonth:
                        description: This is the expiry month [MM] of the card.
                        type: string
                        example: '12'
                      expiryYear:
                        description: This is the expiry year [YYYY] of the card.
                        type: string
                        example: '2026'
                      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]+$
                      gatewayTokenId:
                        description: >-
                          The gateway token Id represents 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
                      emvDataResponse:
                        description: >-
                          Response containing EMV (Europay, MasterCard, and
                          Visa) data from a payment transaction.
                        type: object
                        properties:
                          applicationId:
                            description: >-
                              A unique identifier for the application used
                              during the EMV transaction.
                            type: string
                            example: A0000000031010
                          applicationLabel:
                            description: >-
                              The label or name of the application selected for
                              the transaction, typically representing the card
                              brand.
                            type: string
                            example: VISA CREDIT
                          authorisationResponseCode:
                            description: >-
                              The response code indicating the outcome of the
                              authorisation request.
                            type: string
                            example: '00'
                          cardHolderVerificationMethodResults:
                            description: >-
                              The results of the Cardholder Verification Method
                              (CVM) used in the transaction, such as PIN
                              verification or signature.
                            type: string
                            enum:
                              - Pin verified
                              - Signature verified
                              - No CVM required
                          panSequenceNumber:
                            description: >-
                              The sequence number that differentiates cards with
                              the same Primary Account Number (PAN) issued to
                              the same account holder.
                            type: string
                            example: '01'
                          preferredName:
                            description: >-
                              The preferred name of the application as displayed
                              on the terminal during the transaction.
                            type: string
                            example: Visa
                      providerResponse:
                        description: >-
                          The response from the payment provider containing
                          details about the transaction processing outcome.
                        properties:
                          provider:
                            description: >-
                              The name of the provider that processed the
                              transaction.
                            example: PXPFinancial
                            type: string
                          code:
                            description: >-
                              The raw result code returned by the provider that
                              processed the transaction.
                            example: '00'
                            type: string
                          message:
                            description: >-
                              The raw message associated with the result code
                              from the provider that processed the transaction.
                            example: Transaction Approved
                            type: string
                          merchantId:
                            description: >-
                              This is the unique identifier assigned by the
                              provider to represent the merchant involved in the
                              transaction processing.
                            example: '77772182'
                            type: string
                          terminalId:
                            description: >-
                              This is the unique identifier assigned by the
                              provider to represent the terminall involved in
                              the transaction processing.
                            example: '7777218212'
                            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.
                            example: PAR12345678901234567890
                            pattern: ^[A-Z0-9]{22}$
                            type: string
                          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'
                          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 categorizes 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
                          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'
                          issuerResponseCode:
                            type: string
                            description: >-
                              A two-character code that indicates the result of
                              the transaction authorisation.
                            example: '00'
                            x-readme-ref-name: issuerResponseCode
                type: object
              examples:
                Instore Card Authorised:
                  value:
                    state: Authorised
                    approvalCode: '123456'
                    merchantTransactionDate: '2024-01-27 08:51:02.826445+00:00'
                    merchantTransactionId: This_is_my_merchant_transaction_id
                    systemTransactionId: 1ed768bb-e88a-4636-91ae-67927ccbb02b
                    providerTransactionId: 1ed768bb-e88a-4636-91ae-67927ccbb02b
                    fundingData:
                      cardScheme: Visa
                      gatewayTokenId: 1ed768bb-e88a-4636-91ae-67927ccbb02b
                      providerResponse:
                        provider: PXPFinancial
                        code: '00'
                        message: Approved
                        merchantId: '77772182'
                        emvDataResponse:
                          authorisationResponseCode: 8A
                          issuerAuthenticationData: ''
                          issuerScriptTemplate1: ''
                          issuerScriptTemplate2: ''
                        paymentAccountReference: PAR12345678901234567890
                        schemeTransactionId: TX1234567890123456
                Instore Card Refused:
                  value:
                    state: Refused
                    stateData:
                      code: PRO0006
                      message: Do not Hounour
                    merchantTransactionDate: '2024-01-27 08:51:02.826445+00:00'
                    merchantTransactionId: This_is_my_merchant_transaction_id
                    systemTransactionId: 1ed768bb-e88a-4636-91ae-67927ccbb02b
                    providerTransactionId: 1ed768bb-e88a-4636-91ae-67927ccbb02b
                    fundingData:
                      cardScheme: Visa
                      gatewayTokenId: 1ed768bb-e88a-4636-91ae-67927ccbb02b
                      providerResponse:
                        provider: PXPFinancial
                        code: '05'
                        message: Do not honour
                        merchantId: '77772182'
                        emvDataResponse:
                          authorisationResponseCode: 8A
                          issuerAuthenticationData: ''
                          issuerScriptTemplate1: ''
                          issuerScriptTemplate2: ''
                        merchantAdvice:
                          code: '01'
                          message: New account information available
                Instore Card Error (General):
                  value:
                    state: Error
                    stateData:
                      code: GEN0001
                      message: General Error
                    merchantTransactionDate: '2024-01-27 08:51:02.826445+00:00'
                    merchantTransactionId: This_is_my_merchant_transaction_id
                    systemTransactionId: 1ed768bb-e88a-4636-91ae-67927ccbb02b
                    fundingData:
                      cardScheme: Visa
                      gatewayTokenId: 1ed768bb-e88a-4636-91ae-67927ccbb02b
                Instore Card Error (Communication Timeout):
                  value:
                    state: Error
                    stateData:
                      code: PRO0002
                      message: Communication Timeout
                    merchantTransactionDate: '2024-01-27 08:51:02.826445+00:00'
                    merchantTransactionId: This_is_my_merchant_transaction_id
                    systemTransactionId: 1ed768bb-e88a-4636-91ae-67927ccbb02b
                    fundingData:
                      cardScheme: Visa
                      gatewayTokenId: 1ed768bb-e88a-4636-91ae-67927ccbb02b
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                description: >-
                  Indicates a client-side error where the request could not be
                  processed due to malformed syntax, invalid data, or missing
                  information. This response is used across different
                  transaction methods such as cards, APMs, bank transfers, and
                  wallets, signaling the need for the requester to modify their
                  input. It encompasses errors ranging from incorrect field
                  formats to missing required parameters.
                example:
                  correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                  details: []
                  errorCode: CAR0003
                  errorReason: Invalid Card Details Provided
                properties:
                  correlationId:
                    description: >-
                      A unique identifier generated by PXP, serving as a
                      critical tool for tracing and diagnosing transaction
                      errors. This Id allows for the precise location of
                      transactional issues, facilitating swift investigation and
                      resolution by correlating specific transaction attempts or
                      processes with error logs. Essential for support and
                      operational teams, the correlationId enhances PXP's
                      ability to maintain high-quality service and transaction
                      reliability.
                    example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                    type: string
                  details:
                    description: TBC
                    example:
                      - '''''$.site - The site field is required.'
                    items: {}
                    type: array
                  errorCode:
                    description: |
                      This is the error code returned for the operation.
                    example: INVALID_REQUEST
                    type: string
                  errorReason:
                    description: |
                      This is the error reason returned for the operation.
                    example: One or more validation errors occurred.
                    type: string
                type: object
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                description: >-
                  This response denotes an unauthorized request due to failed
                  authentication or missing credentials, applicable across
                  various payment methods. It suggests the system cannot verify
                  the requester's identity or validate the transaction's
                  legitimacy, necessitating authentication details or proper
                  credentials.
                example:
                  correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                  details: []
                  errorCode: CAR0004
                  errorReason: Authentication Failed for Card Transaction
                properties:
                  correlationId:
                    description: >-
                      A unique identifier generated by PXP, serving as a
                      critical tool for tracing and diagnosing transaction
                      errors. This Id allows for the precise location of
                      transactional issues, facilitating swift investigation and
                      resolution by correlating specific transaction attempts or
                      processes with error logs. Essential for support and
                      operational teams, the correlationId enhances PXP's
                      ability to maintain high-quality service and transaction
                      reliability.
                    example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                    type: string
                  details:
                    description: TBC
                    example:
                      - '''''$.site - The site field is required.'
                    items: {}
                    type: array
                  errorCode:
                    description: |
                      This is the error code returned for the operation.
                    example: INVALID_REQUEST
                    type: string
                  errorReason:
                    description: |
                      This is the error reason returned for the operation.
                    example: One or more validation errors occurred.
                    type: string
                type: object
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                description: >-
                  Signifies a request is understood but refused by the server,
                  often due to insufficient permissions or access rules. This
                  generic error is relevant for all transaction types,
                  indicating the action requested by the user is forbidden
                  despite successful authentication.
                example:
                  correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                  details: []
                  errorCode: CAR0005
                  errorReason: Transaction Not Permitted
                properties:
                  correlationId:
                    description: >-
                      A unique identifier generated by PXP, serving as a
                      critical tool for tracing and diagnosing transaction
                      errors. This Id allows for the precise location of
                      transactional issues, facilitating swift investigation and
                      resolution by correlating specific transaction attempts or
                      processes with error logs. Essential for support and
                      operational teams, the correlationId enhances PXP's
                      ability to maintain high-quality service and transaction
                      reliability.
                    example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                    type: string
                  details:
                    description: TBC
                    example:
                      - '''''$.site - The site field is required.'
                    items: {}
                    type: array
                  errorCode:
                    description: |
                      This is the error code returned for the operation.
                    example: INVALID_REQUEST
                    type: string
                  errorReason:
                    description: |
                      This is the error reason returned for the operation.
                    example: One or more validation errors occurred.
                    type: string
                type: object
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                description: >-
                  Occurs when the server can find no match for the requested
                  resource, applicable to any transaction type. This response
                  indicates the specified resource, whether it be transaction
                  details, user information, or other data, does not exist or
                  cannot be found.
                example:
                  correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                  details: []
                  errorCode: CAR0006
                  errorReason: Card Transaction Details Not Found
                properties:
                  correlationId:
                    description: >-
                      A unique identifier generated by PXP, serving as a
                      critical tool for tracing and diagnosing transaction
                      errors. This Id allows for the precise location of
                      transactional issues, facilitating swift investigation and
                      resolution by correlating specific transaction attempts or
                      processes with error logs. Essential for support and
                      operational teams, the correlationId enhances PXP's
                      ability to maintain high-quality service and transaction
                      reliability.
                    example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                    type: string
                  details:
                    description: TBC
                    example:
                      - '''''$.site - The site field is required.'
                    items: {}
                    type: array
                  errorCode:
                    description: |
                      This is the error code returned for the operation.
                    example: INVALID_REQUEST
                    type: string
                  errorReason:
                    description: |
                      This is the error reason returned for the operation.
                    example: One or more validation errors occurred.
                    type: string
                type: object
        '413':
          description: Payload too large
          content:
            application/json:
              schema:
                description: >-
                  Indicates that the server refuses to process the request
                  because the request payload is larger than the server is
                  willing or able to process. This error is applicable across
                  all transaction types, signaling that the data submitted
                  exceeds the maximum allowed size. Clients should reduce the
                  size of their request before retrying. This response helps
                  maintain efficient processing and prevents overloading the
                  server with excessive data.
                example:
                  correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                  details: []
                  errorCode: TOK0004
                  errorReason: Token Request Payload Too Large
                properties:
                  correlationId:
                    description: >-
                      A unique identifier generated by PXP, serving as a
                      critical tool for tracing and diagnosing transaction
                      errors. This Id allows for the precise location of
                      transactional issues, facilitating swift investigation and
                      resolution by correlating specific transaction attempts or
                      processes with error logs. Essential for support and
                      operational teams, the correlationId enhances PXP's
                      ability to maintain high-quality service and transaction
                      reliability.
                    example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                    type: string
                  details:
                    description: TBC
                    example:
                      - '''''$.site - The site field is required.'
                    items: {}
                    type: array
                  errorCode:
                    description: |
                      This is the error code returned for the operation.
                    example: INVALID_REQUEST
                    type: string
                  errorReason:
                    description: |
                      This is the error reason returned for the operation.
                    example: One or more validation errors occurred.
                    type: string
                type: object
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                description: >-
                  Signifies that the server understands the content type of the
                  request and the syntax is correct, but it cannot process the
                  contained instructions. This response is particularly relevant
                  when validating request fields across various transaction
                  methods, including cards, APMs, bank transfers, and wallets,
                  where specific field values do not meet the expected formats
                  or logical validations. It prompts a review and correction of
                  the submitted data to align with the required standards or
                  constraints.
                example:
                  correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                  details: []
                  errorCode: CAR0010
                  errorReason: Invalid Transaction Data Format
                properties:
                  correlationId:
                    description: >-
                      A unique identifier generated by PXP, serving as a
                      critical tool for tracing and diagnosing transaction
                      errors. This Id allows for the precise location of
                      transactional issues, facilitating swift investigation and
                      resolution by correlating specific transaction attempts or
                      processes with error logs. Essential for support and
                      operational teams, the correlationId enhances PXP's
                      ability to maintain high-quality service and transaction
                      reliability.
                    example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                    type: string
                  details:
                    description: TBC
                    example:
                      - '''''$.site - The site field is required.'
                    items: {}
                    type: array
                  errorCode:
                    description: |
                      This is the error code returned for the operation.
                    example: INVALID_REQUEST
                    type: string
                  errorReason:
                    description: |
                      This is the error reason returned for the operation.
                    example: One or more validation errors occurred.
                    type: string
                type: object
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                description: >-
                  Represents a generic error response indicating an internal
                  server error. This response is used when the server encounters
                  an unexpected condition that prevents it from fulfilling the
                  request, which could range from temporary server malfunctions
                  to more complex issues within the server's processing of
                  specific transactions. It signals that the problem lies with
                  the server's internal operations rather than the request
                  itself. This type of error requires server-side investigation
                  and potentially corrective action to resolve the underlying
                  issue.
                example:
                  correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                  details: []
                  errorCode: GEN0008
                  errorReason: Unexpected Internal Error
                properties:
                  correlationId:
                    description: >-
                      A unique identifier generated by PXP, serving as a
                      critical tool for tracing and diagnosing transaction
                      errors. This Id allows for the precise location of
                      transactional issues, facilitating swift investigation and
                      resolution by correlating specific transaction attempts or
                      processes with error logs. Essential for support and
                      operational teams, the correlationId enhances PXP's
                      ability to maintain high-quality service and transaction
                      reliability.
                    example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                    type: string
                  details:
                    description: TBC
                    example:
                      - '''''$.site - The site field is required.'
                    items: {}
                    type: array
                  errorCode:
                    description: |
                      This is the error code returned for the operation.
                    example: INVALID_REQUEST
                    type: string
                  errorReason:
                    description: |
                      This is the error reason returned for the operation.
                    example: One or more validation errors occurred.
                    type: string
                type: object
        default:
          description: Error
          content:
            application/json:
              schema:
                description: >-
                  Defines the structure for reporting errors encountered during
                  the transaction process. This object includes a unique
                  `correlationId` for tracking and diagnosing the issue, an
                  `errorCode` identifying the type of error, and an
                  `errorReason` providing a descriptive explanation of the
                  error. Additionally, a `details` array may contain further
                  information or context about the error, offering insights
                  necessary for troubleshooting and resolution. This structured
                  approach ensures precise error reporting and aids in efficient
                  error management and support processes.
                properties:
                  correlationId:
                    description: >-
                      A unique identifier generated to correlate the error with
                      a specific transaction attempt, facilitating easier
                      tracking and resolution of issues.
                    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 standardized code that categorizes 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
  /pos-transactions/{systemTransactionId}/modifications:
    post:
      summary: Create a POS modification
      description: >-
        This endpoint facilitates the processing of modifications on previously
        initiated transactions that have not yet been fully processed or
        captured. Supported modification actions include refunds, captures,
        incremental authorisations, and voids. Upon successful execution, it
        returns a unique reference for the modification request, allowing for
        easy tracking and reconciliation.
      operationId: modify-pos-transaction
      parameters:
        - name: systemTransactionId
          in: path
          description: >-
            The unique systemTransactionId with which you want to process an
            operation.
          required: true
          style: simple
          explode: false
          schema:
            description: >-
              The system transaction Id is a 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
      requestBody:
        description: Modifications to a previous transaction.
        content:
          application/json:
            schema:
              description: >-
                The modification request contains details required to perform a
                modification on a transaction, such as a refund, increment,
                void, or capture.
              required:
                - merchant
                - amounts
                - merchantTransactionId
                - operation
                - site
                - merchantTransactionDate
              properties:
                amounts:
                  description: >-
                    Details of the amount including transaction and gratuity
                    values and its associated currency.
                  type: object
                  required:
                    - transaction
                  properties:
                    transaction:
                      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
                    gratuity:
                      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
                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
                merchantTransactionId:
                  description: >-
                    Represents 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: This_is_my_merchant_transaction_id
                  type: string
                  maxLength: 50
                merchantTransactionDate:
                  description: >-
                    Specifies 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'
                operation:
                  description: >-
                    Describes the operation to be applied to the previous
                    transaction. This field specifies actions such as refund,
                    void, capture, or incremental adjustments to a transaction.
                  enum:
                    - Capture
                    - Incremental
                    - Refund
                    - Void
                  example: Capture
                  type: string
                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
              type: object
            examples:
              Refund:
                value:
                  merchant: MERCHANT-1
                  site: SITE-1
                  merchantTransactionId: This_is_my_merchant_transaction_id
                  merchantTransactionDate: '2024-01-27T08:51:02.826Z'
                  amounts:
                    transaction: 30.32
                  operation: Refund
              Capture:
                value:
                  merchant: MERCHANT-1
                  site: SITE-1
                  merchantTransactionId: This_is_my_merchant_transaction_id_1
                  merchantTransactionDate: '2024-01-27T08:51:02.826Z'
                  amounts:
                    transaction: 30.32
                  operation: Capture
              Incremental:
                value:
                  merchant: MERCHANT-1
                  site: SITE-1
                  merchantTransactionId: This_is_my_merchant_transaction_id_1
                  merchantTransactionDate: '2024-01-27T08:51:02.826Z'
                  amounts:
                    transaction: 1
                  operation: Incremental
              Void:
                value:
                  merchant: MERCHANT-1
                  site: SITE-1
                  merchantTransactionId: This_is_my_merchant_transaction_id_1
                  merchantTransactionDate: '2024-01-27T08:51:02.826Z'
                  amounts:
                    transaction: 30.32
                  operation: Void
        required: true
      responses:
        '200':
          description: Modifications Response
          content:
            application/json:
              schema:
                description: >-
                  The modifications response provides details about the state of
                  a transaction modification request, including the state
                  itself, any additional state details, and relevant
                  transaction, funding data, and provider information.
                properties:
                  state:
                    description: The current state of the transaction.
                    enum:
                      - Authorised
                      - Captured
                      - Cancelled
                      - Error
                      - Refused
                    example: Authorised
                    type: string
                  stateData:
                    type: object
                    description: Key value pair for various state data
                    properties:
                      code:
                        description: This is the state Details Code
                        type: string
                      message:
                        description: This is the state Details Message
                        type: string
                    example:
                      code: '12345'
                      message: Merchant not found
                  approvalCode:
                    description: >-
                      A unique identifier code provided by the authorizing
                      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]
                  merchantTransactionId:
                    description: >-
                      Represents 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: This_is_my_merchant_transaction_id
                    type: string
                    maxLength: 50
                  systemTransactionId:
                    description: >-
                      The system transaction Id is a 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
                  merchantTransactionDate:
                    description: >-
                      Specifies 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'
                  fundingData:
                    type: object
                    description: >-
                      Funding data specifying the payment method used for the
                      transaction. It includes essential information about a
                      card involved in a transaction, such as its scheme,
                      payment account reference, and token IDs. Additionally, it
                      provides verification results for enhanced security, such
                      as CVC and AVS checks, enabling you to ensure transaction
                      integrity and mitigate fraud risks efficiently. This
                      object is returned if the `transactionMethod.fundingType`
                      is `card` or `schemeToken`.
                    properties:
                      maskedPrimaryAccountNumber:
                        description: >-
                          The card's primary account number (PAN) masked for
                          security, typically showing only the last four digits.
                        type: string
                        example: 463242******1234
                      expiryMonth:
                        description: This is the expiry month [MM] of the card.
                        type: string
                        example: '12'
                      expiryYear:
                        description: This is the expiry year [YYYY] of the card.
                        type: string
                        example: '2026'
                      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]+$
                      gatewayTokenId:
                        description: >-
                          The gateway token Id represents 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
                      emvDataResponse:
                        description: >-
                          Response containing EMV (Europay, MasterCard, and
                          Visa) data from a payment transaction.
                        type: object
                        properties:
                          applicationId:
                            description: >-
                              A unique identifier for the application used
                              during the EMV transaction.
                            type: string
                            example: A0000000031010
                          applicationLabel:
                            description: >-
                              The label or name of the application selected for
                              the transaction, typically representing the card
                              brand.
                            type: string
                            example: VISA CREDIT
                          authorisationResponseCode:
                            description: >-
                              The response code indicating the outcome of the
                              authorisation request.
                            type: string
                            example: '00'
                          cardHolderVerificationMethodResults:
                            description: >-
                              The results of the Cardholder Verification Method
                              (CVM) used in the transaction, such as PIN
                              verification or signature.
                            type: string
                            enum:
                              - Pin verified
                              - Signature verified
                              - No CVM required
                          panSequenceNumber:
                            description: >-
                              The sequence number that differentiates cards with
                              the same Primary Account Number (PAN) issued to
                              the same account holder.
                            type: string
                            example: '01'
                          preferredName:
                            description: >-
                              The preferred name of the application as displayed
                              on the terminal during the transaction.
                            type: string
                            example: Visa
                      providerResponse:
                        description: >-
                          The response from the payment provider containing
                          details about the transaction processing outcome.
                        properties:
                          provider:
                            description: >-
                              The name of the provider that processed the
                              transaction.
                            example: PXPFinancial
                            type: string
                          code:
                            description: >-
                              The raw result code returned by the provider that
                              processed the transaction.
                            example: '00'
                            type: string
                          message:
                            description: >-
                              The raw message associated with the result code
                              from the provider that processed the transaction.
                            example: Transaction Approved
                            type: string
                          merchantId:
                            description: >-
                              This is the unique identifier assigned by the
                              provider to represent the merchant involved in the
                              transaction processing.
                            example: '77772182'
                            type: string
                          terminalId:
                            description: >-
                              This is the unique identifier assigned by the
                              provider to represent the terminall involved in
                              the transaction processing.
                            example: '7777218212'
                            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.
                            example: PAR12345678901234567890
                            pattern: ^[A-Z0-9]{22}$
                            type: string
                          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'
                          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 categorizes 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
                          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'
                          issuerResponseCode:
                            type: string
                            description: >-
                              A two-character code that indicates the result of
                              the transaction authorisation.
                            example: '00'
                            x-readme-ref-name: issuerResponseCode
                required:
                  - state
              examples:
                Capture (Captured):
                  value:
                    state: Captured
                    approvalCode: '123456'
                    merchantTransactionId: This_is_my_merchant_transaction_id
                    systemTransactionId: 1ed768bb-e88a-4636-91ae-67927ccbb02b
                    merchantTransactionDate: '2024-01-27T08:51:02.826Z'
                    fundingData:
                      cardScheme: Visa
                      gatewayTokenId: 1ed768bb-e88a-4636-91ae-67927ccbb03a
                    providerResponse:
                      provider: PXPFinancial
                      code: '00'
                      message: Approved
                      merchantId: '77772182'
                      paymentAccountReference: PAR12345678901234567890
                      schemeTransactionId: TX1234567890123456
                Incremental (Authorised):
                  value:
                    state: Authorised
                    approvalCode: '123456'
                    merchantTransactionId: This_is_my_merchant_transaction_id
                    systemTransactionId: 1ed768bb-e88a-4636-91ae-67927ccbb02b
                    merchantTransactionDate: '2024-01-27T08:51:02.826Z'
                    fundingData:
                      cardScheme: Visa
                      gatewayTokenId: 1ed768bb-e88a-4636-91ae-67927ccbb03a
                    providerResponse:
                      provider: PXPFinancial
                      code: '00'
                      message: Approved
                      merchantId: '77772182'
                      paymentAccountReference: PAR12345678901234567890
                      schemeTransactionId: TX1234567890123456
                Refund (Authorised):
                  value:
                    state: Authorised
                    approvalCode: '123456'
                    merchantTransactionId: This_is_my_merchant_transaction_id
                    systemTransactionId: 1ed768bb-e88a-4636-91ae-67927ccbb02b
                    fundingData:
                      cardScheme: Visa
                      gatewayTokenId: 1ed768bb-e88a-4636-91ae-67927ccbb03a
                    providerResponse:
                      provider: PXPFinancial
                      code: '00'
                      message: Approved
                      merchantId: '77772182'
                      paymentAccountReference: PAR12345678901234567890
                      schemeTransactionId: TX1234567890123456
                Void (Authorised):
                  value:
                    state: Cancelled
                    approvalCode: '123456'
                    merchantTransactionId: This_is_my_merchant_transaction_id
                    systemTransactionId: 1ed768bb-e88a-4636-91ae-67927ccbb02b
                    merchantTransactionDate: '2024-01-27T08:51:02.826Z'
                    fundingData:
                      cardScheme: Visa
                      gatewayTokenId: 1ed768bb-e88a-4636-91ae-67927ccbb03a
                    providerResponse:
                      provider: PXPFinancial
                      code: '00'
                      message: Approved
                      merchantId: '77772182'
                      paymentAccountReference: PAR12345678901234567890
                      schemeTransactionId: TX1234567890123456
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                description: >-
                  Indicates a client-side error where the request could not be
                  processed due to malformed syntax, invalid data, or missing
                  information. This response is used across different
                  transaction methods such as cards, APMs, bank transfers, and
                  wallets, signaling the need for the requester to modify their
                  input. It encompasses errors ranging from incorrect field
                  formats to missing required parameters.
                example:
                  correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                  details: []
                  errorCode: CAR0003
                  errorReason: Invalid Card Details Provided
                properties:
                  correlationId:
                    description: >-
                      A unique identifier generated by PXP, serving as a
                      critical tool for tracing and diagnosing transaction
                      errors. This Id allows for the precise location of
                      transactional issues, facilitating swift investigation and
                      resolution by correlating specific transaction attempts or
                      processes with error logs. Essential for support and
                      operational teams, the correlationId enhances PXP's
                      ability to maintain high-quality service and transaction
                      reliability.
                    example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                    type: string
                  details:
                    description: TBC
                    example:
                      - '''''$.site - The site field is required.'
                    items: {}
                    type: array
                  errorCode:
                    description: |
                      This is the error code returned for the operation.
                    example: INVALID_REQUEST
                    type: string
                  errorReason:
                    description: |
                      This is the error reason returned for the operation.
                    example: One or more validation errors occurred.
                    type: string
                type: object
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                description: >-
                  This response denotes an unauthorized request due to failed
                  authentication or missing credentials, applicable across
                  various payment methods. It suggests the system cannot verify
                  the requester's identity or validate the transaction's
                  legitimacy, necessitating authentication details or proper
                  credentials.
                example:
                  correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                  details: []
                  errorCode: CAR0004
                  errorReason: Authentication Failed for Card Transaction
                properties:
                  correlationId:
                    description: >-
                      A unique identifier generated by PXP, serving as a
                      critical tool for tracing and diagnosing transaction
                      errors. This Id allows for the precise location of
                      transactional issues, facilitating swift investigation and
                      resolution by correlating specific transaction attempts or
                      processes with error logs. Essential for support and
                      operational teams, the correlationId enhances PXP's
                      ability to maintain high-quality service and transaction
                      reliability.
                    example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                    type: string
                  details:
                    description: TBC
                    example:
                      - '''''$.site - The site field is required.'
                    items: {}
                    type: array
                  errorCode:
                    description: |
                      This is the error code returned for the operation.
                    example: INVALID_REQUEST
                    type: string
                  errorReason:
                    description: |
                      This is the error reason returned for the operation.
                    example: One or more validation errors occurred.
                    type: string
                type: object
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                description: >-
                  Signifies a request is understood but refused by the server,
                  often due to insufficient permissions or access rules. This
                  generic error is relevant for all transaction types,
                  indicating the action requested by the user is forbidden
                  despite successful authentication.
                example:
                  correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                  details: []
                  errorCode: CAR0005
                  errorReason: Transaction Not Permitted
                properties:
                  correlationId:
                    description: >-
                      A unique identifier generated by PXP, serving as a
                      critical tool for tracing and diagnosing transaction
                      errors. This Id allows for the precise location of
                      transactional issues, facilitating swift investigation and
                      resolution by correlating specific transaction attempts or
                      processes with error logs. Essential for support and
                      operational teams, the correlationId enhances PXP's
                      ability to maintain high-quality service and transaction
                      reliability.
                    example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                    type: string
                  details:
                    description: TBC
                    example:
                      - '''''$.site - The site field is required.'
                    items: {}
                    type: array
                  errorCode:
                    description: |
                      This is the error code returned for the operation.
                    example: INVALID_REQUEST
                    type: string
                  errorReason:
                    description: |
                      This is the error reason returned for the operation.
                    example: One or more validation errors occurred.
                    type: string
                type: object
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                description: >-
                  Occurs when the server can find no match for the requested
                  resource, applicable to any transaction type. This response
                  indicates the specified resource, whether it be transaction
                  details, user information, or other data, does not exist or
                  cannot be found.
                example:
                  correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                  details: []
                  errorCode: CAR0006
                  errorReason: Card Transaction Details Not Found
                properties:
                  correlationId:
                    description: >-
                      A unique identifier generated by PXP, serving as a
                      critical tool for tracing and diagnosing transaction
                      errors. This Id allows for the precise location of
                      transactional issues, facilitating swift investigation and
                      resolution by correlating specific transaction attempts or
                      processes with error logs. Essential for support and
                      operational teams, the correlationId enhances PXP's
                      ability to maintain high-quality service and transaction
                      reliability.
                    example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                    type: string
                  details:
                    description: TBC
                    example:
                      - '''''$.site - The site field is required.'
                    items: {}
                    type: array
                  errorCode:
                    description: |
                      This is the error code returned for the operation.
                    example: INVALID_REQUEST
                    type: string
                  errorReason:
                    description: |
                      This is the error reason returned for the operation.
                    example: One or more validation errors occurred.
                    type: string
                type: object
        '413':
          description: Payload too large
          content:
            application/json:
              schema:
                description: >-
                  Indicates that the server refuses to process the request
                  because the request payload is larger than the server is
                  willing or able to process. This error is applicable across
                  all transaction types, signaling that the data submitted
                  exceeds the maximum allowed size. Clients should reduce the
                  size of their request before retrying. This response helps
                  maintain efficient processing and prevents overloading the
                  server with excessive data.
                example:
                  correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                  details: []
                  errorCode: TOK0004
                  errorReason: Token Request Payload Too Large
                properties:
                  correlationId:
                    description: >-
                      A unique identifier generated by PXP, serving as a
                      critical tool for tracing and diagnosing transaction
                      errors. This Id allows for the precise location of
                      transactional issues, facilitating swift investigation and
                      resolution by correlating specific transaction attempts or
                      processes with error logs. Essential for support and
                      operational teams, the correlationId enhances PXP's
                      ability to maintain high-quality service and transaction
                      reliability.
                    example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                    type: string
                  details:
                    description: TBC
                    example:
                      - '''''$.site - The site field is required.'
                    items: {}
                    type: array
                  errorCode:
                    description: |
                      This is the error code returned for the operation.
                    example: INVALID_REQUEST
                    type: string
                  errorReason:
                    description: |
                      This is the error reason returned for the operation.
                    example: One or more validation errors occurred.
                    type: string
                type: object
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                description: >-
                  Signifies that the server understands the content type of the
                  request and the syntax is correct, but it cannot process the
                  contained instructions. This response is particularly relevant
                  when validating request fields across various transaction
                  methods, including cards, APMs, bank transfers, and wallets,
                  where specific field values do not meet the expected formats
                  or logical validations. It prompts a review and correction of
                  the submitted data to align with the required standards or
                  constraints.
                example:
                  correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                  details: []
                  errorCode: CAR0010
                  errorReason: Invalid Transaction Data Format
                properties:
                  correlationId:
                    description: >-
                      A unique identifier generated by PXP, serving as a
                      critical tool for tracing and diagnosing transaction
                      errors. This Id allows for the precise location of
                      transactional issues, facilitating swift investigation and
                      resolution by correlating specific transaction attempts or
                      processes with error logs. Essential for support and
                      operational teams, the correlationId enhances PXP's
                      ability to maintain high-quality service and transaction
                      reliability.
                    example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                    type: string
                  details:
                    description: TBC
                    example:
                      - '''''$.site - The site field is required.'
                    items: {}
                    type: array
                  errorCode:
                    description: |
                      This is the error code returned for the operation.
                    example: INVALID_REQUEST
                    type: string
                  errorReason:
                    description: |
                      This is the error reason returned for the operation.
                    example: One or more validation errors occurred.
                    type: string
                type: object
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                description: >-
                  Represents a generic error response indicating an internal
                  server error. This response is used when the server encounters
                  an unexpected condition that prevents it from fulfilling the
                  request, which could range from temporary server malfunctions
                  to more complex issues within the server's processing of
                  specific transactions. It signals that the problem lies with
                  the server's internal operations rather than the request
                  itself. This type of error requires server-side investigation
                  and potentially corrective action to resolve the underlying
                  issue.
                example:
                  correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                  details: []
                  errorCode: GEN0008
                  errorReason: Unexpected Internal Error
                properties:
                  correlationId:
                    description: >-
                      A unique identifier generated by PXP, serving as a
                      critical tool for tracing and diagnosing transaction
                      errors. This Id allows for the precise location of
                      transactional issues, facilitating swift investigation and
                      resolution by correlating specific transaction attempts or
                      processes with error logs. Essential for support and
                      operational teams, the correlationId enhances PXP's
                      ability to maintain high-quality service and transaction
                      reliability.
                    example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                    type: string
                  details:
                    description: TBC
                    example:
                      - '''''$.site - The site field is required.'
                    items: {}
                    type: array
                  errorCode:
                    description: |
                      This is the error code returned for the operation.
                    example: INVALID_REQUEST
                    type: string
                  errorReason:
                    description: |
                      This is the error reason returned for the operation.
                    example: One or more validation errors occurred.
                    type: string
                type: object
        default:
          description: Error
          content:
            application/json:
              schema:
                description: >-
                  Defines the structure for reporting errors encountered during
                  the transaction process. This object includes a unique
                  `correlationId` for tracking and diagnosing the issue, an
                  `errorCode` identifying the type of error, and an
                  `errorReason` providing a descriptive explanation of the
                  error. Additionally, a `details` array may contain further
                  information or context about the error, offering insights
                  necessary for troubleshooting and resolution. This structured
                  approach ensures precise error reporting and aids in efficient
                  error management and support processes.
                properties:
                  correlationId:
                    description: >-
                      A unique identifier generated to correlate the error with
                      a specific transaction attempt, facilitating easier
                      tracking and resolution of issues.
                    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 standardized code that categorizes 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
components:
  schemas:
    approvalCode:
      description: >-
        A unique identifier code provided by the authorizing 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]
    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.
      properties:
        provider:
          description: The name of the provider that processed the transaction.
          example: PXPFinancial
          type: string
        code:
          description: >-
            The raw result code returned by the provider that processed the
            transaction.
          example: '00'
          type: string
        message:
          description: >-
            The raw message associated with the result code from the provider
            that processed the transaction.
          example: Transaction Approved
          type: string
        merchantId:
          description: >-
            This is the unique identifier assigned by the provider to represent
            the merchant involved in the transaction processing.
          example: '77772182'
          type: string
        terminalId:
          description: >-
            This is the unique identifier assigned by the provider to represent
            the terminall involved in the transaction processing.
          example: '7777218212'
          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.
          example: PAR12345678901234567890
          pattern: ^[A-Z0-9]{22}$
          type: string
        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'
        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 categorizes
                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
        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'
    cardResponse:
      description: >-
        The `cardResponse` object encapsulates 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:
        maskedPrimaryAccountNumber:
          description: >-
            The card's primary account number (PAN) masked for security,
            typically showing only the last four digits.
          type: string
          example: 463242******1234
        expiryMonth:
          description: This is the expiry month [MM] of the card.
          type: string
          example: '12'
        expiryYear:
          description: This is the expiry year [YYYY] of the card.
          type: string
          example: '2026'
        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]+$
        gatewayTokenId:
          description: >-
            The gateway token Id represents 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
        emvDataResponse:
          description: >-
            Response containing EMV (Europay, MasterCard, and Visa) data from a
            payment transaction.
          type: object
          properties:
            applicationId:
              description: >-
                A unique identifier for the application used during the EMV
                transaction.
              type: string
              example: A0000000031010
            applicationLabel:
              description: >-
                The label or name of the application selected for the
                transaction, typically representing the card brand.
              type: string
              example: VISA CREDIT
            authorisationResponseCode:
              description: >-
                The response code indicating the outcome of the authorisation
                request.
              type: string
              example: '00'
            cardHolderVerificationMethodResults:
              description: >-
                The results of the Cardholder Verification Method (CVM) used in
                the transaction, such as PIN verification or signature.
              type: string
              enum:
                - Pin verified
                - Signature verified
                - No CVM required
            panSequenceNumber:
              description: >-
                The sequence number that differentiates cards with the same
                Primary Account Number (PAN) issued to the same account holder.
              type: string
              example: '01'
            preferredName:
              description: >-
                The preferred name of the application as displayed on the
                terminal during the transaction.
              type: string
              example: Visa
        providerResponse:
          description: >-
            The response from the payment provider containing details about the
            transaction processing outcome.
          properties:
            provider:
              description: The name of the provider that processed the transaction.
              example: PXPFinancial
              type: string
            code:
              description: >-
                The raw result code returned by the provider that processed the
                transaction.
              example: '00'
              type: string
            message:
              description: >-
                The raw message associated with the result code from the
                provider that processed the transaction.
              example: Transaction Approved
              type: string
            merchantId:
              description: >-
                This is the unique identifier assigned by the provider to
                represent the merchant involved in the transaction processing.
              example: '77772182'
              type: string
            terminalId:
              description: >-
                This is the unique identifier assigned by the provider to
                represent the terminall involved in the transaction processing.
              example: '7777218212'
              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.
              example: PAR12345678901234567890
              pattern: ^[A-Z0-9]{22}$
              type: string
            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'
            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
                    categorizes 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
            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'
      type: object
    correlationId:
      description: >-
        A unique identifier generated by PXP, serving as a critical tool for
        tracing and diagnosing transaction errors. This Id allows for the
        precise location of transactional issues, facilitating swift
        investigation and resolution by correlating specific transaction
        attempts or processes with error logs. Essential for support and
        operational teams, the correlationId enhances PXP's ability to maintain
        high-quality service and transaction reliability.
      example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
      type: string
    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.
      example: EUR
      type: string
      minLength: 3
      maxLength: 3
    details:
      description: TBC
      example:
        - '''''$.site - The site field is required.'
      items: {}
      type: array
    entryType:
      description: >-
        Specifies 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:
        - Instore
      example: Instore
    error:
      description: >-
        Defines the structure for reporting errors encountered during the
        transaction process. This object includes a unique `correlationId` for
        tracking and diagnosing the issue, an `errorCode` identifying the type
        of error, and an `errorReason` providing a descriptive explanation of
        the error. Additionally, a `details` array may contain further
        information or context about the error, offering insights necessary for
        troubleshooting and resolution. This structured approach ensures precise
        error reporting and aids in efficient error management and support
        processes.
      properties:
        correlationId:
          description: >-
            A unique identifier generated to correlate the error with a specific
            transaction attempt, facilitating easier tracking and resolution of
            issues.
          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 standardized code that categorizes 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
    errorCode:
      description: |
        This is the error code returned for the operation.
      example: INVALID_REQUEST
      type: string
    errorReason:
      description: |
        This is the error reason returned for the operation.
      example: One or more validation errors occurred.
      type: string
    fundingType:
      description: >-
        Specifies 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: >-
        The gateway token Id represents 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
    gratuity:
      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
    inline_response_400:
      description: >-
        Indicates a client-side error where the request could not be processed
        due to malformed syntax, invalid data, or missing information. This
        response is used across different transaction methods such as cards,
        APMs, bank transfers, and wallets, signaling the need for the requester
        to modify their input. It encompasses errors ranging from incorrect
        field formats to missing required parameters.
      example:
        correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
        details: []
        errorCode: CAR0003
        errorReason: Invalid Card Details Provided
      properties:
        correlationId:
          description: >-
            A unique identifier generated by PXP, serving as a critical tool for
            tracing and diagnosing transaction errors. This Id allows for the
            precise location of transactional issues, facilitating swift
            investigation and resolution by correlating specific transaction
            attempts or processes with error logs. Essential for support and
            operational teams, the correlationId enhances PXP's ability to
            maintain high-quality service and transaction reliability.
          example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
          type: string
        details:
          description: TBC
          example:
            - '''''$.site - The site field is required.'
          items: {}
          type: array
        errorCode:
          description: |
            This is the error code returned for the operation.
          example: INVALID_REQUEST
          type: string
        errorReason:
          description: |
            This is the error reason returned for the operation.
          example: One or more validation errors occurred.
          type: string
      type: object
    inline_response_401:
      description: >-
        This response denotes an unauthorized request due to failed
        authentication or missing credentials, applicable across various payment
        methods. It suggests the system cannot verify the requester's identity
        or validate the transaction's legitimacy, necessitating authentication
        details or proper credentials.
      example:
        correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
        details: []
        errorCode: CAR0004
        errorReason: Authentication Failed for Card Transaction
      properties:
        correlationId:
          description: >-
            A unique identifier generated by PXP, serving as a critical tool for
            tracing and diagnosing transaction errors. This Id allows for the
            precise location of transactional issues, facilitating swift
            investigation and resolution by correlating specific transaction
            attempts or processes with error logs. Essential for support and
            operational teams, the correlationId enhances PXP's ability to
            maintain high-quality service and transaction reliability.
          example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
          type: string
        details:
          description: TBC
          example:
            - '''''$.site - The site field is required.'
          items: {}
          type: array
        errorCode:
          description: |
            This is the error code returned for the operation.
          example: INVALID_REQUEST
          type: string
        errorReason:
          description: |
            This is the error reason returned for the operation.
          example: One or more validation errors occurred.
          type: string
      type: object
    inline_response_403:
      description: >-
        Signifies a request is understood but refused by the server, often due
        to insufficient permissions or access rules. This generic error is
        relevant for all transaction types, indicating the action requested by
        the user is forbidden despite successful authentication.
      example:
        correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
        details: []
        errorCode: CAR0005
        errorReason: Transaction Not Permitted
      properties:
        correlationId:
          description: >-
            A unique identifier generated by PXP, serving as a critical tool for
            tracing and diagnosing transaction errors. This Id allows for the
            precise location of transactional issues, facilitating swift
            investigation and resolution by correlating specific transaction
            attempts or processes with error logs. Essential for support and
            operational teams, the correlationId enhances PXP's ability to
            maintain high-quality service and transaction reliability.
          example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
          type: string
        details:
          description: TBC
          example:
            - '''''$.site - The site field is required.'
          items: {}
          type: array
        errorCode:
          description: |
            This is the error code returned for the operation.
          example: INVALID_REQUEST
          type: string
        errorReason:
          description: |
            This is the error reason returned for the operation.
          example: One or more validation errors occurred.
          type: string
      type: object
    inline_response_404:
      description: >-
        Occurs when the server can find no match for the requested resource,
        applicable to any transaction type. This response indicates the
        specified resource, whether it be transaction details, user information,
        or other data, does not exist or cannot be found.
      example:
        correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
        details: []
        errorCode: CAR0006
        errorReason: Card Transaction Details Not Found
      properties:
        correlationId:
          description: >-
            A unique identifier generated by PXP, serving as a critical tool for
            tracing and diagnosing transaction errors. This Id allows for the
            precise location of transactional issues, facilitating swift
            investigation and resolution by correlating specific transaction
            attempts or processes with error logs. Essential for support and
            operational teams, the correlationId enhances PXP's ability to
            maintain high-quality service and transaction reliability.
          example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
          type: string
        details:
          description: TBC
          example:
            - '''''$.site - The site field is required.'
          items: {}
          type: array
        errorCode:
          description: |
            This is the error code returned for the operation.
          example: INVALID_REQUEST
          type: string
        errorReason:
          description: |
            This is the error reason returned for the operation.
          example: One or more validation errors occurred.
          type: string
      type: object
    inline_response_413:
      description: >-
        Indicates that the server refuses to process the request because the
        request payload is larger than the server is willing or able to process.
        This error is applicable across all transaction types, signaling that
        the data submitted exceeds the maximum allowed size. Clients should
        reduce the size of their request before retrying. This response helps
        maintain efficient processing and prevents overloading the server with
        excessive data.
      example:
        correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
        details: []
        errorCode: TOK0004
        errorReason: Token Request Payload Too Large
      properties:
        correlationId:
          description: >-
            A unique identifier generated by PXP, serving as a critical tool for
            tracing and diagnosing transaction errors. This Id allows for the
            precise location of transactional issues, facilitating swift
            investigation and resolution by correlating specific transaction
            attempts or processes with error logs. Essential for support and
            operational teams, the correlationId enhances PXP's ability to
            maintain high-quality service and transaction reliability.
          example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
          type: string
        details:
          description: TBC
          example:
            - '''''$.site - The site field is required.'
          items: {}
          type: array
        errorCode:
          description: |
            This is the error code returned for the operation.
          example: INVALID_REQUEST
          type: string
        errorReason:
          description: |
            This is the error reason returned for the operation.
          example: One or more validation errors occurred.
          type: string
      type: object
    inline_response_422:
      description: >-
        Signifies that the server understands the content type of the request
        and the syntax is correct, but it cannot process the contained
        instructions. This response is particularly relevant when validating
        request fields across various transaction methods, including cards,
        APMs, bank transfers, and wallets, where specific field values do not
        meet the expected formats or logical validations. It prompts a review
        and correction of the submitted data to align with the required
        standards or constraints.
      example:
        correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
        details: []
        errorCode: CAR0010
        errorReason: Invalid Transaction Data Format
      properties:
        correlationId:
          description: >-
            A unique identifier generated by PXP, serving as a critical tool for
            tracing and diagnosing transaction errors. This Id allows for the
            precise location of transactional issues, facilitating swift
            investigation and resolution by correlating specific transaction
            attempts or processes with error logs. Essential for support and
            operational teams, the correlationId enhances PXP's ability to
            maintain high-quality service and transaction reliability.
          example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
          type: string
        details:
          description: TBC
          example:
            - '''''$.site - The site field is required.'
          items: {}
          type: array
        errorCode:
          description: |
            This is the error code returned for the operation.
          example: INVALID_REQUEST
          type: string
        errorReason:
          description: |
            This is the error reason returned for the operation.
          example: One or more validation errors occurred.
          type: string
      type: object
    inline_response_500:
      description: >-
        Represents a generic error response indicating an internal server error.
        This response is used when the server encounters an unexpected condition
        that prevents it from fulfilling the request, which could range from
        temporary server malfunctions to more complex issues within the server's
        processing of specific transactions. It signals that the problem lies
        with the server's internal operations rather than the request itself.
        This type of error requires server-side investigation and potentially
        corrective action to resolve the underlying issue.
      example:
        correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
        details: []
        errorCode: GEN0008
        errorReason: Unexpected Internal Error
      properties:
        correlationId:
          description: >-
            A unique identifier generated by PXP, serving as a critical tool for
            tracing and diagnosing transaction errors. This Id allows for the
            precise location of transactional issues, facilitating swift
            investigation and resolution by correlating specific transaction
            attempts or processes with error logs. Essential for support and
            operational teams, the correlationId enhances PXP's ability to
            maintain high-quality service and transaction reliability.
          example: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
          type: string
        details:
          description: TBC
          example:
            - '''''$.site - The site field is required.'
          items: {}
          type: array
        errorCode:
          description: |
            This is the error code returned for the operation.
          example: INVALID_REQUEST
          type: string
        errorReason:
          description: |
            This is the error reason returned for the operation.
          example: One or more validation errors occurred.
          type: string
      type: object
    intent:
      description: >-
        Specifies the purpose or action of the transaction, indicating the
        intended money flow direction. This field is crucial for categorizing
        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
        - EstimatedAuthorisation
        - Purchase
        - Payout
        - Refund
        - Verification
      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 categorizes 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
    merchantTransactionDate:
      description: >-
        Specifies 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: >-
        Represents 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: This_is_my_merchant_transaction_id
      type: string
      maxLength: 50
    modificationRequest:
      description: >-
        The modification request contains details required to perform a
        modification on a transaction, such as a refund, increment, void, or
        capture.
      required:
        - merchant
        - amounts
        - merchantTransactionId
        - operation
        - site
        - merchantTransactionDate
      properties:
        amounts:
          description: >-
            Details of the amount including transaction and gratuity values and
            its associated currency.
          type: object
          required:
            - transaction
          properties:
            transaction:
              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
            gratuity:
              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
        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
        merchantTransactionId:
          description: >-
            Represents 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: This_is_my_merchant_transaction_id
          type: string
          maxLength: 50
        merchantTransactionDate:
          description: >-
            Specifies 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'
        operation:
          description: >-
            Describes the operation to be applied to the previous transaction.
            This field specifies actions such as refund, void, capture, or
            incremental adjustments to a transaction.
          enum:
            - Capture
            - Incremental
            - Refund
            - Void
          example: Capture
          type: string
        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
      type: object
    modificationResponse:
      description: >-
        The modifications response provides details about the state of a
        transaction modification request, including the state itself, any
        additional state details, and relevant transaction, funding data, and
        provider information.
      properties:
        state:
          description: The current state of the transaction.
          enum:
            - Authorised
            - Captured
            - Cancelled
            - Error
            - Refused
          example: Authorised
          type: string
        stateData:
          type: object
          description: Key value pair for various state data
          properties:
            code:
              description: This is the state Details Code
              type: string
            message:
              description: This is the state Details Message
              type: string
          example:
            code: '12345'
            message: Merchant not found
        approvalCode:
          description: >-
            A unique identifier code provided by the authorizing 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]
        merchantTransactionId:
          description: >-
            Represents 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: This_is_my_merchant_transaction_id
          type: string
          maxLength: 50
        systemTransactionId:
          description: >-
            The system transaction Id is a 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
        merchantTransactionDate:
          description: >-
            Specifies 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'
        fundingData:
          description: >-
            Funding data specifying the payment method used for the transaction.
            It includes essential information about a card involved in a
            transaction, such as its scheme, payment account reference, and
            token IDs. Additionally, it provides verification results for
            enhanced security, such as CVC and AVS checks, enabling you to
            ensure transaction integrity and mitigate fraud risks efficiently.
            This object is returned if the `transactionMethod.fundingType` is
            `card` or `schemeToken`.
          properties:
            maskedPrimaryAccountNumber:
              description: >-
                The card's primary account number (PAN) masked for security,
                typically showing only the last four digits.
              type: string
              example: 463242******1234
            expiryMonth:
              description: This is the expiry month [MM] of the card.
              type: string
              example: '12'
            expiryYear:
              description: This is the expiry year [YYYY] of the card.
              type: string
              example: '2026'
            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]+$
            gatewayTokenId:
              description: >-
                The gateway token Id represents 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
            emvDataResponse:
              description: >-
                Response containing EMV (Europay, MasterCard, and Visa) data
                from a payment transaction.
              type: object
              properties:
                applicationId:
                  description: >-
                    A unique identifier for the application used during the EMV
                    transaction.
                  type: string
                  example: A0000000031010
                applicationLabel:
                  description: >-
                    The label or name of the application selected for the
                    transaction, typically representing the card brand.
                  type: string
                  example: VISA CREDIT
                authorisationResponseCode:
                  description: >-
                    The response code indicating the outcome of the
                    authorisation request.
                  type: string
                  example: '00'
                cardHolderVerificationMethodResults:
                  description: >-
                    The results of the Cardholder Verification Method (CVM) used
                    in the transaction, such as PIN verification or signature.
                  type: string
                  enum:
                    - Pin verified
                    - Signature verified
                    - No CVM required
                panSequenceNumber:
                  description: >-
                    The sequence number that differentiates cards with the same
                    Primary Account Number (PAN) issued to the same account
                    holder.
                  type: string
                  example: '01'
                preferredName:
                  description: >-
                    The preferred name of the application as displayed on the
                    terminal during the transaction.
                  type: string
                  example: Visa
        providerResponse:
          type: object
          description: >-
            The response from the payment provider containing details about the
            transaction processing outcome.
          properties:
            provider:
              description: The name of the provider that processed the transaction.
              example: PXPFinancial
              type: string
            code:
              description: >-
                The raw result code returned by the provider that processed the
                transaction.
              example: '00'
              type: string
            message:
              description: >-
                The raw message associated with the result code from the
                provider that processed the transaction.
              example: Transaction Approved
              type: string
            merchantId:
              description: >-
                This is the unique identifier assigned by the provider to
                represent the merchant involved in the transaction processing.
              example: '77772182'
              type: string
            terminalId:
              description: >-
                This is the unique identifier assigned by the provider to
                represent the terminall involved in the transaction processing.
              example: '7777218212'
              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.
              example: PAR12345678901234567890
              pattern: ^[A-Z0-9]{22}$
              type: string
            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'
            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
                    categorizes 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
            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'
      required:
        - state
    operation:
      description: >-
        Describes the operation to be applied to the previous transaction. This
        field specifies actions such as refund, void, capture, or incremental
        adjustments to a transaction.
      enum:
        - Capture
        - Incremental
        - Refund
        - Void
      example: Capture
      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.
      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: >-
        This is the unique identifier assigned by the provider to represent the
        merchant involved in the transaction processing.
      example: '77772182'
      type: string
    providerResponseTerminalId:
      description: >-
        This is the unique identifier assigned by the provider to represent the
        terminall involved in the transaction processing.
      example: '7777218212'
      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.
    pointOfSaleId:
      type: string
      description: >
        "A PXP unique identifier for the specific point of sale device, often
        assigned by the merchant or payment processor."
      example: ACME-001
      maxLength: 20
    storeAndForwardType:
      description: >
        Store and Forward is a mechanism used for handling transactions when the
        merchant's connection to the PXP gateway is disrupted. It securely
        stores transactions offline until communications are re-established with
        the gateway. The types are:

        Possible Values:

        - `None`: No store and forward mechanism is used.

        - `ForcedStoreAndForward`: Typically used in situations like cruise
        liners with poor satellite communications. Transactions are
        automatically forced into store and forward mode. Once communication is
        re-established, the transactions are sent to the gateway to perform
        online authorisation with the acquirer via the PXP gateway.
      enum:
        - None
        - ForcedStoreAndForward
      example: None
      type: string
    language:
      description: |
        "ISO 639-1 language code representing the display language."

        Possible Values:
        - `CA`: Catalan
        - `DA`: Danish
        - `DE`: German
        - `EN`: English
        - `ES`: Spanish
        - `FR`: French
        - `HU`: Hungarian
        - `IS`: Icelandic
        - `IT`: Italian
        - `NL`: Dutch
        - `NO`: Norwegian
        - `PL`: Polish
        - `PT`: Portuguese
        - `SV`: Swedish
      type: string
      maxLength: 2
      enum:
        - CA
        - DA
        - DE
        - EN
        - ES
        - FR
        - HU
        - IS
        - IT
        - NL
        - 'NO'
        - PL
        - PT
        - SV
      example: EN
    pointOfInteraction:
      description: >-
        The pointOfInteraction object captures detailed information about the
        device and environment where a card present transaction takes place. It
        includes various attributes that help identify and describe the
        capabilities and configurations of the point of sale (POS) device.
      properties:
        pointOfSaleId:
          type: string
          description: >
            "A PXP unique identifier for the specific point of sale device,
            often assigned by the merchant or payment processor."
          example: ACME-001
          maxLength: 20
        language:
          description: |
            "ISO 639-1 language code representing the display language."

            Possible Values:
            - `CA`: Catalan
            - `DA`: Danish
            - `DE`: German
            - `EN`: English
            - `ES`: Spanish
            - `FR`: French
            - `HU`: Hungarian
            - `IS`: Icelandic
            - `IT`: Italian
            - `NL`: Dutch
            - `NO`: Norwegian
            - `PL`: Polish
            - `PT`: Portuguese
            - `SV`: Swedish
          type: string
          maxLength: 2
          enum:
            - CA
            - DA
            - DE
            - EN
            - ES
            - FR
            - HU
            - IS
            - IT
            - NL
            - 'NO'
            - PL
            - PT
            - SV
          example: EN
        storeAndForwardType:
          description: >
            Store and Forward is a mechanism used for handling transactions when
            the merchant's connection to the PXP gateway is disrupted. It
            securely stores transactions offline until communications are
            re-established with the gateway. The types are:

            Possible Values:

            - `None`: No store and forward mechanism is used.

            - `ForcedStoreAndForward`: Typically used in situations like cruise
            liners with poor satellite communications. Transactions are
            automatically forced into store and forward mode. Once communication
            is re-established, the transactions are sent to the gateway to
            perform online authorisation with the acquirer via the PXP gateway.
          enum:
            - None
            - ForcedStoreAndForward
          example: None
          type: string
        invokeKeyed:
          description: >-
            Indicates whether the merchant wants to initiate a keyed transaction
            on the device. Keyed transactions involve manually entering the card
            details on the point of sale (POS) device.
          type: boolean
          example: true
          default: false
    emvDataResponse:
      description: >-
        Response containing EMV (Europay, MasterCard, and Visa) data from a
        payment transaction.
      type: object
      properties:
        applicationId:
          description: >-
            A unique identifier for the application used during the EMV
            transaction.
          type: string
          example: A0000000031010
        applicationLabel:
          description: >-
            The label or name of the application selected for the transaction,
            typically representing the card brand.
          type: string
          example: VISA CREDIT
        authorisationResponseCode:
          description: >-
            The response code indicating the outcome of the authorisation
            request.
          type: string
          example: '00'
        cardHolderVerificationMethodResults:
          description: >-
            The results of the Cardholder Verification Method (CVM) used in the
            transaction, such as PIN verification or signature.
          type: string
          enum:
            - Pin verified
            - Signature verified
            - No CVM required
        panSequenceNumber:
          description: >-
            The sequence number that differentiates cards with the same Primary
            Account Number (PAN) issued to the same account holder.
          type: string
          example: '01'
        preferredName:
          description: >-
            The preferred name of the application as displayed on the terminal
            during the transaction.
          type: string
          example: Visa
    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'
    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
    state:
      description: The current state of the transaction.
      enum:
        - Authorised
        - Captured
        - Cancelled
        - Error
        - Refused
      example: Authorised
      type: string
    stateData:
      type: object
      description: Key value pair for various state data
      properties:
        code:
          description: This is the state Details Code
          type: string
        message:
          description: This is the state Details Message
          type: string
      example:
        code: '12345'
        message: Merchant not found
    stateDataCode:
      description: This is the state Details Code
      type: string
    stateDataMessage:
      description: This is the state Details Message
      type: string
    systemTransactionId:
      description: >-
        The system transaction Id is a 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
    transaction:
      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
    transactionMethod:
      description: >-
        The transaction method provides comprehensive details about the intent,
        capture method, and origin of a transaction.
      properties:
        entryType:
          description: >-
            Specifies 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:
            - Instore
          example: Instore
        fundingType:
          description: >-
            Specifies 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
        intent:
          description: >-
            Specifies the purpose or action of the transaction, indicating the
            intended money flow direction. This field is crucial for
            categorizing 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
            - EstimatedAuthorisation
            - Purchase
            - Payout
            - Refund
            - Verification
          example: Authorisation
      type: object
      required:
        - entryType
        - fundingType
        - intent
    transactionRequest:
      description: >-
        The transactionRequest object encapsulates all essential details
        required for initiating and processing a transaction. It includes
        funding data, address verification, transaction amounts, merchant
        information, shopper details, recurring payment information, site
        identifier, 3D Secure details, and transaction method.
      properties:
        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
        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
        pointOfInteraction:
          description: >-
            The pointOfInteraction object captures detailed information about
            the device and environment where a card present transaction takes
            place. It includes various attributes that help identify and
            describe the capabilities and configurations of the point of sale
            (POS) device.
          properties:
            pointOfSaleId:
              type: string
              description: >
                "A PXP unique identifier for the specific point of sale device,
                often assigned by the merchant or payment processor."
              example: ACME-001
              maxLength: 20
            language:
              description: |
                "ISO 639-1 language code representing the display language."

                Possible Values:
                - `CA`: Catalan
                - `DA`: Danish
                - `DE`: German
                - `EN`: English
                - `ES`: Spanish
                - `FR`: French
                - `HU`: Hungarian
                - `IS`: Icelandic
                - `IT`: Italian
                - `NL`: Dutch
                - `NO`: Norwegian
                - `PL`: Polish
                - `PT`: Portuguese
                - `SV`: Swedish
              type: string
              maxLength: 2
              enum:
                - CA
                - DA
                - DE
                - EN
                - ES
                - FR
                - HU
                - IS
                - IT
                - NL
                - 'NO'
                - PL
                - PT
                - SV
              example: EN
            storeAndForwardType:
              description: >
                Store and Forward is a mechanism used for handling transactions
                when the merchant's connection to the PXP gateway is disrupted.
                It securely stores transactions offline until communications are
                re-established with the gateway. The types are:

                Possible Values:

                - `None`: No store and forward mechanism is used.

                - `ForcedStoreAndForward`: Typically used in situations like
                cruise liners with poor satellite communications. Transactions
                are automatically forced into store and forward mode. Once
                communication is re-established, the transactions are sent to
                the gateway to perform online authorisation with the acquirer
                via the PXP gateway.
              enum:
                - None
                - ForcedStoreAndForward
              example: None
              type: string
            invokeKeyed:
              description: >-
                Indicates whether the merchant wants to initiate a keyed
                transaction on the device. Keyed transactions involve manually
                entering the card details on the point of sale (POS) device.
              type: boolean
              example: true
              default: false
        merchantTransactionId:
          description: >-
            Represents 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: This_is_my_merchant_transaction_id
          type: string
          maxLength: 50
        merchantTransactionDate:
          description: >-
            Specifies 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'
        amounts:
          description: >-
            Details of the amount including transaction and gratuity values and
            its associated currency.
          type: object
          required:
            - currencyCode
            - transaction
          properties:
            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.
              example: EUR
              type: string
              minLength: 3
              maxLength: 3
            transaction:
              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
            gratuity:
              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
        transactionMethod:
          description: >-
            The transaction method provides comprehensive details about the
            intent, capture method, and origin of a transaction.
          properties:
            entryType:
              description: >-
                Specifies 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:
                - Instore
              example: Instore
            fundingType:
              description: >-
                Specifies 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
            intent:
              description: >-
                Specifies the purpose or action of the transaction, indicating
                the intended money flow direction. This field is crucial for
                categorizing 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
                - EstimatedAuthorisation
                - Purchase
                - Payout
                - Refund
                - Verification
              example: Authorisation
          type: object
          required:
            - entryType
            - fundingType
            - intent
      required:
        - merchant
        - site
        - merchantTransactionId
        - merchantTransactionDate
        - amounts
        - transactionMethod
      type: object
    transactionRequestLegacy:
      description: >-
        The transactionRequest object encapsulates all essential details
        required for initiating and processing a transaction. It includes
        funding data, address verification, transaction amounts, merchant
        information, shopper details, recurring payment information, site
        identifier, 3D Secure details, and transaction method.
      properties:
        credentials:
          description: >-
            Credentials used for authentication. This is only to be used when
            processing transactions to the `PXP ANYpay` platform.
          properties:
            username:
              description: The username used for authentication.
            password:
              description: The password used for authentication.
        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
        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
        pointOfInteraction:
          description: >-
            The pointOfInteraction object captures detailed information about
            the device and environment where a card present transaction takes
            place. It includes various attributes that help identify and
            describe the capabilities and configurations of the point of sale
            (POS) device.
          properties:
            pointOfSaleId:
              type: string
              description: >
                "A PXP unique identifier for the specific point of sale device,
                often assigned by the merchant or payment processor."
              example: ACME-001
              maxLength: 20
            language:
              description: |
                "ISO 639-1 language code representing the display language."

                Possible Values:
                - `CA`: Catalan
                - `DA`: Danish
                - `DE`: German
                - `EN`: English
                - `ES`: Spanish
                - `FR`: French
                - `HU`: Hungarian
                - `IS`: Icelandic
                - `IT`: Italian
                - `NL`: Dutch
                - `NO`: Norwegian
                - `PL`: Polish
                - `PT`: Portuguese
                - `SV`: Swedish
              type: string
              maxLength: 2
              enum:
                - CA
                - DA
                - DE
                - EN
                - ES
                - FR
                - HU
                - IS
                - IT
                - NL
                - 'NO'
                - PL
                - PT
                - SV
              example: EN
            storeAndForwardType:
              description: >
                Store and Forward is a mechanism used for handling transactions
                when the merchant's connection to the PXP gateway is disrupted.
                It securely stores transactions offline until communications are
                re-established with the gateway. The types are:

                Possible Values:

                - `None`: No store and forward mechanism is used.

                - `ForcedStoreAndForward`: Typically used in situations like
                cruise liners with poor satellite communications. Transactions
                are automatically forced into store and forward mode. Once
                communication is re-established, the transactions are sent to
                the gateway to perform online authorisation with the acquirer
                via the PXP gateway.
              enum:
                - None
                - ForcedStoreAndForward
              example: None
              type: string
            invokeKeyed:
              description: >-
                Indicates whether the merchant wants to initiate a keyed
                transaction on the device. Keyed transactions involve manually
                entering the card details on the point of sale (POS) device.
              type: boolean
              example: true
              default: false
        merchantTransactionId:
          description: >-
            Represents 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: This_is_my_merchant_transaction_id
          type: string
          maxLength: 50
        merchantTransactionDate:
          description: >-
            Specifies 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'
        amounts:
          description: >-
            Details of the amount including transaction and gratuity values and
            its associated currency.
          type: object
          required:
            - currencyCode
            - transaction
          properties:
            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.
              example: EUR
              type: string
              minLength: 3
              maxLength: 3
            transaction:
              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
            gratuity:
              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
        transactionMethod:
          description: >-
            The transaction method provides comprehensive details about the
            intent, capture method, and origin of a transaction.
          properties:
            entryType:
              description: >-
                Specifies 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:
                - Instore
              example: Instore
            fundingType:
              description: >-
                Specifies 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
            intent:
              description: >-
                Specifies the purpose or action of the transaction, indicating
                the intended money flow direction. This field is crucial for
                categorizing 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
                - EstimatedAuthorisation
                - Purchase
                - Payout
                - Refund
                - Verification
              example: Authorisation
          type: object
          required:
            - entryType
            - fundingType
            - intent
      required:
        - merchant
        - site
        - merchantTransactionId
        - merchantTransactionDate
        - amounts
        - transactionMethod
      type: object
    transactionResponse:
      description: >-
        The transactionResponse object provides comprehensive details regarding
        the status and data associated with the transaction. It includes
        information about the current state of the transaction,
        transaction-specific details, funding data related information, and the
        response received from the payment provider.
      properties:
        state:
          description: The current state of the transaction.
          enum:
            - Authorised
            - Captured
            - Cancelled
            - Error
            - Refused
          example: Authorised
          type: string
        stateData:
          type: object
          description: Key value pair for various state data
          properties:
            code:
              description: This is the state Details Code
              type: string
            message:
              description: This is the state Details Message
              type: string
          example:
            code: '12345'
            message: Merchant not found
        approvalCode:
          description: >-
            A unique identifier code provided by the authorizing 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]
        merchantTransactionDate:
          description: >-
            Specifies 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: >-
            Represents 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: This_is_my_merchant_transaction_id
          type: string
          maxLength: 50
        systemTransactionId:
          description: >-
            The system transaction Id is a 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
        providerTransactionId:
          type: string
          description: >-
            A unique identifier assigned by the financial service provider for
            the transaction. It facilitates tracking, reconciliation, and
            support processes.
        fundingData:
          description: >-
            Funding data specifying the payment method used for the transaction.
            This object encapsulates 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:
            maskedPrimaryAccountNumber:
              description: >-
                The card's primary account number (PAN) masked for security,
                typically showing only the last four digits.
              type: string
              example: 463242******1234
            expiryMonth:
              description: This is the expiry month [MM] of the card.
              type: string
              example: '12'
            expiryYear:
              description: This is the expiry year [YYYY] of the card.
              type: string
              example: '2026'
            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]+$
            gatewayTokenId:
              description: >-
                The gateway token Id represents 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
            emvDataResponse:
              description: >-
                Response containing EMV (Europay, MasterCard, and Visa) data
                from a payment transaction.
              type: object
              properties:
                applicationId:
                  description: >-
                    A unique identifier for the application used during the EMV
                    transaction.
                  type: string
                  example: A0000000031010
                applicationLabel:
                  description: >-
                    The label or name of the application selected for the
                    transaction, typically representing the card brand.
                  type: string
                  example: VISA CREDIT
                authorisationResponseCode:
                  description: >-
                    The response code indicating the outcome of the
                    authorisation request.
                  type: string
                  example: '00'
                cardHolderVerificationMethodResults:
                  description: >-
                    The results of the Cardholder Verification Method (CVM) used
                    in the transaction, such as PIN verification or signature.
                  type: string
                  enum:
                    - Pin verified
                    - Signature verified
                    - No CVM required
                panSequenceNumber:
                  description: >-
                    The sequence number that differentiates cards with the same
                    Primary Account Number (PAN) issued to the same account
                    holder.
                  type: string
                  example: '01'
                preferredName:
                  description: >-
                    The preferred name of the application as displayed on the
                    terminal during the transaction.
                  type: string
                  example: Visa
            providerResponse:
              type: object
              description: >-
                The response from the payment provider containing details about
                the transaction processing outcome.
              properties:
                provider:
                  description: The name of the provider that processed the transaction.
                  example: PXPFinancial
                  type: string
                code:
                  description: >-
                    The raw result code returned by the provider that processed
                    the transaction.
                  example: '00'
                  type: string
                message:
                  description: >-
                    The raw message associated with the result code from the
                    provider that processed the transaction.
                  example: Transaction Approved
                  type: string
                merchantId:
                  description: >-
                    This is the unique identifier assigned by the provider to
                    represent the merchant involved in the transaction
                    processing.
                  example: '77772182'
                  type: string
                terminalId:
                  description: >-
                    This is the unique identifier assigned by the provider to
                    represent the terminall involved in the transaction
                    processing.
                  example: '7777218212'
                  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.
                  example: PAR12345678901234567890
                  pattern: ^[A-Z0-9]{22}$
                  type: string
                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'
                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
                        categorizes 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
                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'
                issuerResponseCode:
                  type: string
                  description: >-
                    A two-character code that indicates the result of the
                    transaction authorisation.
                  example: '00'
                  x-readme-ref-name: issuerResponseCode
      type: object
