openapi: 3.0.3
info:
  title: Tap+ transactions API
  description: >-
    This is an API reference for Tap+ transactions. [Learn more about
    Tap+](../guides/tap-plus).
  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:
  /soft-pos-transactions:
    post:
      x-hideReplay: true
      summary: Initiate a POS transaction
      description: >-
        The `/soft-pos-transactions` endpoint enables you to initiate instore
        transactions for Tap+. It supports various transaction methods,
        including card and alternative payments.
      operationId: initiate-pos-transaction
      requestBody:
        description: Initiate a transaction
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SoftPosInitiationRequest'
            examples:
              Purchase:
                value:
                  transactionMethod:
                    entryType: Instore
                    fundingType: Card
                    intent: Purchase
                  amounts:
                    currencyCode: GBP
                    transaction: 10.5
                  merchantTransactionDate: '2025-12-02T10:30:00Z'
                  merchantTransactionId: TXN-12345-ABCDE
                  pointOfInteraction:
                    pointOfSaleId: POS001
                    invokeKeyed: false
                    language: EN
                    storeAndForwardType: None
                  site: SITE001
                  merchant: MERCHANT001
                  merchantDeeplink: myapp://payment/callback
              Standalone refund:
                value:
                  transactionMethod:
                    entryType: Instore
                    fundingType: Card
                    intent: StandaloneRefund
                  amounts:
                    currencyCode: EUR
                    transaction: 30.32
                  merchantTransactionDate: '2024-01-27T08:51:02.826Z'
                  merchantTransactionId: TXN-12345-ABCDE
                  pointOfInteraction:
                    pointOfSaleId: POS-1
                    invokeKeyed: false
                    language: EN
                    storeAndForwardType: None
                  site: SITE-1
                  merchant: MERCHANT-1
                  merchantDeeplink: myapp://payment/callback
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  state:
                    $ref: '#/components/schemas/state'
                  stateData:
                    $ref: '#/components/schemas/stateData'
                  approvalCode:
                    $ref: '#/components/schemas/approvalCode'
                  merchantTransactionDate:
                    $ref: '#/components/schemas/merchantTransactionDate'
                  merchantTransactionId:
                    $ref: '#/components/schemas/merchantTransactionId'
                  systemTransactionId:
                    $ref: '#/components/schemas/systemTransactionId'
                  providerTransactionId:
                    $ref: '#/components/schemas/providerTransactionId'
                  amounts:
                    description: Amount details returned in the response.
                    type: object
                    properties:
                      gratuity:
                        description: The gratuity amount, if applicable.
                        type: number
                        example: 0
                  fundingData:
                    $ref: '#/components/schemas/fundingDataResponse'
                  dccData:
                    $ref: '#/components/schemas/dccData'
                type: object
              examples:
                Card authorised:
                  value:
                    state: Authorised
                    stateData:
                      code: CRD000
                      message: Approved
                    approvalCode: '123456'
                    merchantTransactionDate: '2025-12-02T14:30:00Z'
                    merchantTransactionId: SALE-20251202-001
                    systemTransactionId: TXN-ABC123-XYZ789
                    providerTransactionId: PROV-98765
                    fundingData:
                      maskedPrimaryAccountNumber: '************1234'
                      expiryMonth: '12'
                      expiryYear: '25'
                      cardScheme: VISA
                      gatewayTokenId: TOKEN-123456
                      pointOfInteraction:
                        entryType: Contactless
                      emvDataResponse:
                        applicationId: A0000000031010
                        applicationLabel: VISA DEBIT
                        authorisationResponseCode: '00'
                        cardHolderVerificationMethodResults: 1F0302
                        panSequenceNumber: '01'
                        preferredName: VISA DEBIT
                      providerResponse:
                        provider: Unity
                        code: '00'
                        message: Approved
                        merchantId: MERCHANT001
                        terminalId: TERM001
                        paymentAccountReference: PAR123456789
                        schemeTransactionId: SCHEME-TXN-001
                        issuerResponseCode: '00'
                        schemeTransactionLinkId: LINK-001
                        merchantAdvice:
                          code: ''
                          message: ''
                        settlementDate: '2025-12-02T00:00:00Z'
                Card error (general):
                  value:
                    state: Error
                    stateData:
                      code: CRD183
                      message: Timeout / Malfunction
                    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
                Card error (communication timeout):
                  value:
                    state: Error
                    stateData:
                      code: CRD183
                      message: Timeout / Malfunction
                    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:
                $ref: '#/components/schemas/error'
              example:
                correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                details: []
                errorCode: CAR0003
                errorReason: Invalid Card Details Provided
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              example:
                correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                details: []
                errorCode: CAR0004
                errorReason: Authentication Failed for Card Transaction
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              example:
                correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                details: []
                errorCode: CAR0005
                errorReason: Transaction Not Permitted
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              example:
                correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                details: []
                errorCode: CAR0006
                errorReason: Card Transaction Details Not Found
        '413':
          description: Payload too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              example:
                correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                details: []
                errorCode: TOK0004
                errorReason: Token Request Payload Too Large
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              example:
                correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                details: []
                errorCode: CAR0010
                errorReason: Invalid Transaction Data Format
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              example:
                correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                details: []
                errorCode: GEN0008
                errorReason: Unexpected Internal Error
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
  /soft-pos-transactions/{systemTransactionId}/modifications:
    post:
      summary: Create a POS modification
      description: >-
        This endpoint enables the processing of modifications on previously
        initiated transactions that have not yet been fully processed or
        captured. 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 the
            operation.
          required: true
          style: simple
          explode: false
          schema:
            $ref: '#/components/schemas/systemTransactionId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/modificationRequest'
            examples:
              Refund:
                value:
                  operation: Refund
                  amounts:
                    currencyCode: GBP
                    transaction: 10.5
                  merchantTransactionDate: '2025-12-02T15:30:00Z'
                  merchantTransactionId: MOD-12345-ABCDE
                  site: SITE001
                  merchant: MERCHANT001
                  merchantDeeplink: myapp://payment/callback
              Void:
                value:
                  operation: Void
                  amounts:
                    currencyCode: GBP
                    transaction: 10.5
                  merchantTransactionDate: '2025-12-02T15:30:00Z'
                  merchantTransactionId: MOD-12345-VOID
                  site: SITE001
                  merchant: MERCHANT001
        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:
                    $ref: '#/components/schemas/state'
                  stateData:
                    $ref: '#/components/schemas/stateData'
                  approvalCode:
                    $ref: '#/components/schemas/approvalCode'
                  merchantTransactionId:
                    $ref: '#/components/schemas/merchantTransactionId'
                  systemTransactionId:
                    $ref: '#/components/schemas/systemTransactionId'
                  merchantTransactionDate:
                    $ref: '#/components/schemas/merchantTransactionDate'
                  fundingData:
                    $ref: '#/components/schemas/fundingDataResponse'
                  dccData:
                    $ref: '#/components/schemas/dccData'
                required:
                  - state
              examples:
                Refund (Authorised):
                  value:
                    state: Captured
                    stateData:
                      code: CRD000
                      message: Approved
                    approvalCode: '654321'
                    merchantTransactionId: REFUND-20251202-001
                    systemTransactionId: MOD-DEF456-UVW123
                    merchantTransactionDate: '2025-12-02T16:30:00Z'
                    fundingData:
                      maskedPrimaryAccountNumber: '************1234'
                      expiryMonth: '12'
                      expiryYear: '25'
                      cardScheme: VISA
                      gatewayTokenId: TOKEN-123456
                      emvDataResponse:
                        applicationId: A0000000031010
                        applicationLabel: VISA DEBIT
                        authorisationResponseCode: '00'
                        cardHolderVerificationMethodResults: ''
                        panSequenceNumber: '01'
                        preferredName: VISA DEBIT
                      providerResponse:
                        provider: Unity
                        code: '00'
                        message: Approved
                        merchantId: MERCHANT001
                        terminalId: TERM001
                        paymentAccountReference: ''
                        schemeTransactionId: SCHEME-MOD-001
                        issuerResponseCode: '00'
                        merchantAdvice:
                          code: ''
                          message: ''
                        settlementDate: '2025-12-02T00:00:00Z'
                    dccData:
                      dccSelectedIndicator: Selected
                      amounts:
                        local:
                          transaction: 100
                          currencyCode: USD
                        cardholder:
                          transaction: 85.5
                          currencyCode: EUR
                Void (Authorised):
                  value:
                    state: Cancelled
                    stateData: {}
                    approvalCode: '  SALE'
                    merchantTransactionId: 020226_lv1
                    systemTransactionId: 864b2c15-8d06-4d05-945c-38a747f165f4
                    merchantTransactionDate: '2026-02-02T10:54:44.288000+07:00'
                    fundingData:
                      maskedPrimaryAccountNumber: 374245*****1007
                      expiryMonth: '12'
                      expiryYear: '2030'
                      cardScheme: AmericanExpress
                      gatewayTokenId: d865fe5e-1778-453c-97f4-e11c4c7a5d63
                      providerResponse:
                        provider: Elavon
                        code: A
                        message: APPROVAL
                        merchantId: '290010118'
                        terminalId: '29001011802'
                        paymentAccountReference: ''
                        schemeTransactionId: A202032841726750
                        issuerResponseCode: '00'
                        schemeTransactionLinkId: ''
                        merchantAdvice:
                          code: ''
                          message: ''
                        settlementDate: '2026-02-02T15:30:45.397169+07:00'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              example:
                correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                details: []
                errorCode: CAR0003
                errorReason: Invalid Card Details Provided
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              example:
                correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                details: []
                errorCode: CAR0004
                errorReason: Authentication Failed for Card Transaction
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              example:
                correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                details: []
                errorCode: CAR0005
                errorReason: Transaction Not Permitted
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              example:
                correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                details: []
                errorCode: CAR0006
                errorReason: Card Transaction Details Not Found
        '413':
          description: Payload too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              example:
                correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                details: []
                errorCode: TOK0004
                errorReason: Token Request Payload Too Large
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              example:
                correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                details: []
                errorCode: CAR0010
                errorReason: Invalid Transaction Data Format
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              example:
                correlationId: 81f32b80-2ba0-4430-8ecd-0b559274ba9c
                details: []
                errorCode: GEN0008
                errorReason: Unexpected Internal Error
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
components:
  schemas:
    SoftPosInitiationAmounts:
      description: >-
        Details about the transaction amount. Gratuity is not supported for
        Tap+.
      type: object
      required:
        - currencyCode
        - transaction
      properties:
        currencyCode:
          $ref: '#/components/schemas/currencyCode'
        transaction:
          $ref: '#/components/schemas/transaction'
    SoftPosInitiationRequest:
      description: >-
        The transactionRequest object encapsulates all essential details
        required for initiating and processing a transaction. It includes
        transaction method, amounts, merchant information, site identifier,
        point of interaction, and merchant deeplink for callback.
      type: object
      required:
        - transactionMethod
        - amounts
        - merchantTransactionDate
        - merchantTransactionId
        - pointOfInteraction
        - site
        - merchant
      properties:
        transactionMethod:
          $ref: '#/components/schemas/transactionMethod'
        amounts:
          $ref: '#/components/schemas/SoftPosInitiationAmounts'
        merchantTransactionDate:
          $ref: '#/components/schemas/merchantTransactionDate'
        merchantTransactionId:
          $ref: '#/components/schemas/merchantTransactionId'
        pointOfInteraction:
          $ref: '#/components/schemas/pointOfInteraction'
        site:
          $ref: '#/components/schemas/site'
        merchant:
          $ref: '#/components/schemas/merchant'
        merchantDeeplink:
          $ref: '#/components/schemas/merchantDeeplink'
    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 capitalised 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
    currencyCode:
      description: The currency code associated with the transaction, in ISO 4217 format.
      example: EUR
      type: string
      minLength: 3
      maxLength: 3
    dccAmounts:
      description: >-
        Details about the transaction amount in the local currency and the
        cardholder's currency.
      type: object
      required:
        - local
        - cardholder
      properties:
        local:
          type: object
          description: >-
            Details about the transaction amount in the local (merchant)
            currency.
          required:
            - transaction
            - currencyCode
          properties:
            transaction:
              type: number
              description: The transaction amount in the local currency.
              example: 100
            currencyCode:
              $ref: '#/components/schemas/currencyCode'
        cardholder:
          type: object
          description: Details about the transaction amount in the cardholder's currency.
          required:
            - transaction
            - currencyCode
          properties:
            transaction:
              type: number
              description: The transaction amount in the cardholder's currency.
              example: 85.5
            currencyCode:
              $ref: '#/components/schemas/currencyCode'
    dccData:
      description: >-
        Details about the Dynamic Currency Conversion (DCC) for the transaction,
        including rate selection, amounts in local and cardholder currencies,
        exchange rate, and provider details.
      type: object
      properties:
        dccSelectedIndicator:
          type: string
          enum:
            - NotSelected
            - Selected
            - ErrorRetrievingDccData
            - DccNotEligible
            - InvalidDccTerminalId
            - InvalidDccMerchantId
            - NoDccSupported
            - NoDccRateAvailable
            - ServerErrorRetrievingDccData
            - InvalidDccRequest
            - DccTimeout
          description: >-
            The DCC selection state indicating whether DCC was selected, not
            selected, or unavailable due to an error or eligibility issue.
          example: Selected
        amounts:
          $ref: '#/components/schemas/dccAmounts'
        exchangeRate:
          type: number
          description: The exchange rate used for the DCC conversion.
          example: 0.855
        markupRate:
          type: number
          description: The markup rate applied to the DCC transaction.
          example: 3.92
          nullable: true
        disclaimer:
          type: string
          description: The disclaimer text for the DCC transaction.
          example: >-
            You are offered to pay in EUR. This includes a 3.5% commission above
            the base rate.
          nullable: true
        providerData:
          $ref: '#/components/schemas/dccProviderData'
    dccProviderData:
      description: Details about the DCC provider.
      type: object
      properties:
        provider:
          type: string
          description: The name of the DCC provider.
          example: Elavon
          maxLength: 100
        referenceId:
          type: string
          description: The reference ID provided by the DCC provider.
          example: REF123456789
          maxLength: 80
          nullable: true
        merchantId:
          type: string
          description: The merchant ID assigned by the DCC provider.
          example: MERCH001
          nullable: true
        terminalId:
          type: string
          description: The terminal ID assigned by the DCC provider.
          example: TERM001
          maxLength: 30
          nullable: true
        markupTextIndicator:
          type: integer
          description: The markup text indicator for the DCC provider.
          example: 1
          nullable: true
    details:
      description: TBC
      example:
        - '''''$.site - The site field is required.'
      items: {}
      type: array
    entryType:
      description: >-
        The transaction entry environment and method. Determines applicable
        security and compliance requirements.
      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:
          $ref: '#/components/schemas/details'
        errorCode:
          $ref: '#/components/schemas/errorCode'
        errorReason:
          $ref: '#/components/schemas/errorReason'
      required:
        - correlationId
        - errorCode
        - errorReason
      type: object
    errorCode:
      description: |
        The error code returned for the operation.
      example: INVALID_REQUEST
      type: string
    errorReason:
      description: |
        The error reason returned for the operation.
      example: One or more validation errors occurred.
      type: string
    fundingType:
      description: >-
        The payment method used to fund the transaction (e.g., card, bank
        transfer). Determines the processing rules and security measures applied
        to the transaction.
      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
      type: string
    fundingDataResponse:
      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: '************1234'
        expiryMonth:
          description: The expiry month of the card (`MM`).
          type: string
          example: '12'
        expiryYear:
          description: The expiry year of the card (`YY` or `YYYY` format).
          type: string
          example: '25'
        cardScheme:
          $ref: '#/components/schemas/cardScheme'
        gatewayTokenId:
          $ref: '#/components/schemas/gatewayTokenId'
        pointOfInteraction:
          description: The point of interaction used for the transaction.
          type: object
          properties:
            entryType:
              description: The entry type used for the transaction (e.g. Contactless).
              type: string
              example: Contactless
        emvDataResponse:
          $ref: '#/components/schemas/emvDataResponse'
        providerResponse:
          $ref: '#/components/schemas/providerResponse'
    intent:
      description: >-
        The purpose or action of the transaction, indicating the intended money
        flow direction.
      type: string
      enum:
        - Purchase
        - StandaloneRefund
      example: Purchase
    merchant:
      description: >-
        Your unique merchant identifier, as assigned by PXP. Used to route
        transactions to the correct account.
      example: MERCHANT-1
      type: string
      maxLength: 20
    merchantDeeplink:
      description: >-
        The deeplink or URL to which the user is redirected after payment or
        modification completion. Used by Tap+ to return the customer to the
        merchant application.
      type: string
      example: myapp://payment/callback
    merchantAdvice:
      description: >-
        Provides additional guidance or recommendations from the card network
        regarding the transaction. This information is particularly useful for
        understanding the reasons behind a transaction's refusal and can offer
        suggestions for next steps. For instance, it might indicate that updated
        account information is available or suggest specific actions to resolve
        the refusal. The `merchantAdvice` object includes a `code` and `message`
        to detail this advisory information, making it easier for merchants to
        take corrective action or understand the refusal context.
      properties:
        code:
          type: string
          description: >-
            An advisory code provided by the card network that categorises the
            type of advice or recommendation.
        message:
          type: string
          description: >-
            A human-readable message that provides further details or
            clarification about the advice code, potentially suggesting next
            steps or reasons for the transaction refusal.
      type: object
    merchantTransactionDate:
      description: >-
        The date and time when you initiated the transaction, in ISO 8601
        format.
      type: string
      format: date-time
      example: '2021-10-27 08:51:02.826445+00:00'
    merchantTransactionId:
      description: >-
        Your unique identifier for this transaction. Used to track and reference
        the transaction when communicating with PXP.
      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, void, or capture.
      required:
        - operation
        - amounts
        - merchantTransactionDate
        - merchantTransactionId
        - site
        - merchant
      properties:
        operation:
          $ref: '#/components/schemas/operation'
        amounts:
          description: Details about the amount.
          type: object
          required:
            - currencyCode
            - transaction
          properties:
            currencyCode:
              $ref: '#/components/schemas/currencyCode'
            transaction:
              $ref: '#/components/schemas/transaction'
        merchantTransactionDate:
          $ref: '#/components/schemas/merchantTransactionDate'
        merchantTransactionId:
          $ref: '#/components/schemas/merchantTransactionId'
        site:
          $ref: '#/components/schemas/site'
        merchant:
          $ref: '#/components/schemas/merchant'
        merchantDeeplink:
          $ref: '#/components/schemas/merchantDeeplink'
      type: object
    operation:
      description: >-
        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:
        - Refund
        - Void
      example: Refund
      type: string
    approvalCode:
      description: >-
        A unique identifier code provided by the authorising entity, indicating
        approval or reference for the transaction.
      type: string
      example: '123456'
    paymentAccountReference:
      description: >-
        The unique identifier assigned to a payment account, independent of the
        card number. It remains constant over the account's lifetime, even if
        the card number (PAN) changes. PAR enhances transaction security and
        privacy, serving as a secure reference point for cardholders, merchants,
        and issuers. It is used in digital transaction processing to reliably
        link transactions and accounts without exposing the actual card number.
      example: PAR12345678901234567890
      type: string
    providerResponseName:
      description: The name of the provider that processed the transaction.
      example: PXPFinancial
      type: string
    providerResponseCode:
      description: >-
        The raw result code returned by the provider that processed the
        transaction.
      example: '00'
      type: string
    providerResponseMessage:
      description: >-
        The raw message associated with the result code from the provider that
        processed the transaction.
      example: Transaction Approved
      type: string
    providerResponseMerchantId:
      description: >-
        The unique identifier assigned by the provider to represent the merchant
        involved in the transaction processing.
      example: '77772182'
      type: string
    providerResponseTerminalId:
      description: >-
        The unique identifier assigned by the provider to represent the
        terminall involved in the transaction processing.
      example: '7777218212'
      type: string
    providerResponse:
      description: >-
        The response from the payment provider containing details about the
        transaction processing outcome.
      type: object
      properties:
        provider:
          $ref: '#/components/schemas/providerResponseName'
        code:
          $ref: '#/components/schemas/providerResponseCode'
        message:
          $ref: '#/components/schemas/providerResponseMessage'
        merchantId:
          $ref: '#/components/schemas/providerResponseMerchantId'
        terminalId:
          $ref: '#/components/schemas/providerResponseTerminalId'
        paymentAccountReference:
          $ref: '#/components/schemas/paymentAccountReference'
        schemeTransactionId:
          $ref: '#/components/schemas/schemeTransactionId'
        issuerResponseCode:
          type: string
          description: >-
            A two-character code that indicates the result of the transaction
            authorisation.
          example: '00'
        schemeTransactionLinkId:
          type: string
          description: >-
            The scheme-assigned identifier (MasterCard Transaction Link
            Identifier) of the initial transaction in a series. Submit it on
            subsequent economically-related transactions (e.g., recurring,
            unscheduled card-on-file, resubmission) to link them to the
            original, so the scheme treats them as part of the same agreement
            rather than independent payments.
          example: LINK-001
        merchantAdvice:
          $ref: '#/components/schemas/merchantAdvice'
        settlementDate:
          $ref: '#/components/schemas/settlementDate'
    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: The unique identifier for the specific point-of-sale device.
      example: ACME-001
      maxLength: 20
    storeAndForwardType:
      description: >-
        Store and Forward is a mechanism used for handling transactions when
        your connection to the PXP gateway is disrupted. It securely stores
        transactions offline until communications are re-established with the
        gateway. For Tap+ transactions, set this to `None`.
      enum:
        - None
        - ForcedStoreAndForward
      example: None
      type: string
    language:
      description: The ISO 639-1 language code representing the display language.
      type: string
      maxLength: 2
      enum:
        - CA
        - DA
        - DE
        - EN
        - ES
        - FR
        - HU
        - IS
        - IT
        - NL
        - 'NO'
        - PL
        - PT
        - SV
      example: EN
    pointOfInteraction:
      description: >-
        Details 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.
      required:
        - pointOfSaleId
        - language
      properties:
        pointOfSaleId:
          $ref: '#/components/schemas/pointOfSaleId'
        language:
          $ref: '#/components/schemas/language'
        storeAndForwardType:
          $ref: '#/components/schemas/storeAndForwardType'
        invokeKeyed:
          description: >-
            Whether you want 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
        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-time
      description: >-
        The date and time on which the transaction funds are settled between
        banks. This field is applicable and provided for transactions as
        applicable. The settlement date is crucial for financial reconciliation
        and is formatted as ISO 8601 date-time (e.g. YYYY-MM-DDTHH:mm:ssZ).
      example: '2025-12-02T00:00:00Z'
    site:
      description: >-
        The unique site identifier associated with the transaction, as assigned
        by PXP. This could represent a physical location, website, or any other
        distinct entity where the transaction occurs.
      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. [Learn more about how this
        works](https://developer.pxp.io/guides/tap-plus/how-it-works#state-data-response-codes).
      properties:
        code:
          $ref: '#/components/schemas/stateDataCode'
        message:
          $ref: '#/components/schemas/stateDataMessage'
      example:
        code: CRD000
        message: Approved
    stateDataCode:
      description: The state details code.
      type: string
      enum:
        - CRD000
        - CRD001
        - CRD002
        - CRD003
        - CRD004
        - CRD005
        - CRD006
        - CRD007
        - CRD100
        - CRD101
        - CRD102
        - CRD103
        - CRD104
        - CRD105
        - CRD106
        - CRD107
        - CRD108
        - CRD109
        - CRD110
        - CRD111
        - CRD112
        - CRD113
        - CRD114
        - CRD115
        - CRD116
        - CRD117
        - CRD118
        - CRD119
        - CRD120
        - CRD121
        - CRD122
        - CRD123
        - CRD124
        - CRD125
        - CRD126
        - CRD127
        - CRD128
        - CRD129
        - CRD180
        - CRD181
        - CRD182
        - CRD183
        - CRD184
        - CRD185
    stateDataMessage:
      description: The state details message.
      type: string
      enum:
        - Approved
        - Honour with identification
        - Approved for partial amount
        - Approved (VIP)
        - Approved, update track 3
        - Approved, account type specified by card issuer
        - Approved for partial amount, account type specified by card issuer
        - Approved, update ICC
        - Do not honour
        - Expired card
        - Suspected fraud
        - Card acceptor contact acquirer
        - Restricted card
        - Card acceptor call acquirer's security department
        - Allowable PIN tries exceeded
        - Refer to card issuer
        - Refer to card issuer's special conditions
        - Invalid merchant
        - Invalid amount
        - Invalid card number
        - PIN data required
        - Unacceptable fee
        - No account of type requested
        - Requested function not supported
        - Not sufficient funds
        - Incorrect PIN
        - No card record
        - Transaction not permitted to cardholder
        - Transaction not permitted to terminal
        - Exceeds withdrawal amount limit
        - Security violation
        - Exceeds withdrawal frequency limit
        - Violation of law
        - Card not effective
        - Invalid PIN block
        - PIN length error
        - PIN key sync error
        - Suspected counterfeit card
        - Retry in contact mode or SCA Ecom required
        - Pick up card
        - Bad format
        - Timeout / Malfunction
        - Card restricted
        - Refused by fraud or scoring system
    systemTransactionId:
      description: >-
        The unique identifier generated by PXP for each transaction. It serves
        as a reference for tracking and querying transactions within the PXP
        system. This Id is crucial for performing modifications or querying
        transaction details.
      example: 1ed768bb-e88a-4636-91ae-67927ccbb02b
      type: string
    transaction:
      description: >-
        The transaction amount. The number of decimal places must match the
        currency's minor unit (e.g., 2 for `GBP`/`EUR`, 3 for `BHD`, 0 for
        `JPY`). Values are zero-padded if needed. Transactions with incorrect
        decimal places are rejected.
      example: 30.32
      type: number
    transactionMethod:
      description: Details about the transaction method.
      type: object
      required:
        - entryType
        - fundingType
        - intent
      properties:
        entryType:
          $ref: '#/components/schemas/entryType'
        fundingType:
          $ref: '#/components/schemas/fundingType'
        intent:
          $ref: '#/components/schemas/intent'
