# Create a POS modification

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.

Endpoint: POST /soft-pos-transactions/{systemTransactionId}/modifications
Version: 1.0.0

## Path parameters:

  - `systemTransactionId` (string, required)
    The unique systemTransactionId with which you want to process the operation.
    Example: "1ed768bb-e88a-4636-91ae-67927ccbb02b"

## Request fields (application/json):

  - `operation` (string, required)
    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"

  - `amounts` (object, required)
    Details about the amount.

  - `amounts.currencyCode` (string, required)
    The currency code associated with the transaction, in ISO 4217 format.
    Example: "EUR"

  - `amounts.transaction` (number, required)
    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

  - `merchantTransactionDate` (string, required)
    The date and time when you initiated the transaction, in ISO 8601 format.
    Example: "2021-10-27 08:51:02.826445+00:00"

  - `merchantTransactionId` (string, required)
    Your unique identifier for this transaction. Used to track and reference the transaction when communicating with PXP.
    Example: "This_is_my_merchant_transaction_id"

  - `site` (string, required)
    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"

  - `merchant` (string, required)
    Your unique merchant identifier, as assigned by PXP. Used to route transactions to the correct account.
    Example: "MERCHANT-1"

  - `merchantDeeplink` (string)
    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.
    Example: "myapp://payment/callback"

## Response 200 fields (application/json):

  - `state` (string, required)
    The current state of the transaction.
    Enum: "Authorised", "Captured", "Cancelled", "Error", "Refused"

  - `stateData` (object)
    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).
    Example: {"code":"CRD000","message":"Approved"}

  - `stateData.code` (string)
    The state details code.
    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"

  - `stateData.message` (string)
    The state details message.
    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"

  - `approvalCode` (string)
    A unique identifier code provided by the authorising entity, indicating approval or reference for the transaction.
    Example: "123456"

  - `merchantTransactionId` (string)
    Your unique identifier for this transaction. Used to track and reference the transaction when communicating with PXP.
    Example: "This_is_my_merchant_transaction_id"

  - `systemTransactionId` (string)
    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"

  - `merchantTransactionDate` (string)
    The date and time when you initiated the transaction, in ISO 8601 format.
    Example: "2021-10-27 08:51:02.826445+00:00"

  - `fundingData` (object)
    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.

  - `fundingData.maskedPrimaryAccountNumber` (string)
    The card's primary account number (PAN) masked for security, typically showing only the last four digits.
    Example: "************1234"

  - `fundingData.expiryMonth` (string)
    The expiry month of the card (MM).
    Example: "12"

  - `fundingData.expiryYear` (string)
    The expiry year of the card (YY or YYYY format).
    Example: "25"

  - `fundingData.cardScheme` (string)
    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"

  - `fundingData.gatewayTokenId` (string)
    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"

  - `fundingData.pointOfInteraction` (object)
    The point of interaction used for the transaction.

  - `fundingData.pointOfInteraction.entryType` (string)
    The entry type used for the transaction (e.g. Contactless).
    Example: "Contactless"

  - `fundingData.emvDataResponse` (object)
    Response containing EMV (Europay, MasterCard, and Visa) data from a payment transaction.

  - `fundingData.emvDataResponse.applicationId` (string)
    A unique identifier for the application used during the EMV transaction.
    Example: "A0000000031010"

  - `fundingData.emvDataResponse.applicationLabel` (string)
    The label or name of the application selected for the transaction, typically representing the card brand.
    Example: "VISA CREDIT"

  - `fundingData.emvDataResponse.authorisationResponseCode` (string)
    The response code indicating the outcome of the authorisation request.
    Example: "00"

  - `fundingData.emvDataResponse.cardHolderVerificationMethodResults` (string)
    The results of the Cardholder Verification Method (CVM) used in the transaction, such as PIN verification or signature.

  - `fundingData.emvDataResponse.panSequenceNumber` (string)
    The sequence number that differentiates cards with the same Primary Account Number (PAN) issued to the same account holder.
    Example: "01"

  - `fundingData.emvDataResponse.preferredName` (string)
    The preferred name of the application as displayed on the terminal during the transaction.
    Example: "Visa"

  - `fundingData.providerResponse` (object)
    The response from the payment provider containing details about the transaction processing outcome.

  - `fundingData.providerResponse.provider` (string)
    The name of the provider that processed the transaction.
    Example: "PXPFinancial"

  - `fundingData.providerResponse.code` (string)
    The raw result code returned by the provider that processed the transaction.
    Example: "00"

  - `fundingData.providerResponse.message` (string)
    The raw message associated with the result code from the provider that processed the transaction.
    Example: "Transaction Approved"

  - `fundingData.providerResponse.merchantId` (string)
    The unique identifier assigned by the provider to represent the merchant involved in the transaction processing.
    Example: "77772182"

  - `fundingData.providerResponse.terminalId` (string)
    The unique identifier assigned by the provider to represent the terminall involved in the transaction processing.
    Example: "7777218212"

  - `fundingData.providerResponse.paymentAccountReference` (string)
    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"

  - `fundingData.providerResponse.schemeTransactionId` (string)
    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"

  - `fundingData.providerResponse.issuerResponseCode` (string)
    A two-character code that indicates the result of the transaction authorisation.
    Example: "00"

  - `fundingData.providerResponse.schemeTransactionLinkId` (string)
    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"

  - `fundingData.providerResponse.merchantAdvice` (object)
    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.

  - `fundingData.providerResponse.merchantAdvice.code` (string)
    An advisory code provided by the card network that categorises the type of advice or recommendation.

  - `fundingData.providerResponse.merchantAdvice.message` (string)
    A human-readable message that provides further details or clarification about the advice code, potentially suggesting next steps or reasons for the transaction refusal.

  - `fundingData.providerResponse.settlementDate` (string)
    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"

  - `dccData` (object)
    Details about the Dynamic Currency Conversion (DCC) for the transaction, including rate selection, amounts in local and cardholder currencies, exchange rate, and provider details.

  - `dccData.dccSelectedIndicator` (string)
    The DCC selection state indicating whether DCC was selected, not selected, or unavailable due to an error or eligibility issue.
    Enum: "NotSelected", "Selected", "ErrorRetrievingDccData", "DccNotEligible", "InvalidDccTerminalId", "InvalidDccMerchantId", "NoDccSupported", "NoDccRateAvailable", "ServerErrorRetrievingDccData", "InvalidDccRequest", "DccTimeout"

  - `dccData.amounts` (object)
    Details about the transaction amount in the local currency and the cardholder's currency.

  - `dccData.amounts.local` (object, required)
    Details about the transaction amount in the local (merchant) currency.

  - `dccData.amounts.local.transaction` (number, required)
    The transaction amount in the local currency.
    Example: 100

  - `dccData.amounts.local.currencyCode` (string, required)
    The currency code associated with the transaction, in ISO 4217 format.
    Example: "EUR"

  - `dccData.amounts.cardholder` (object, required)
    Details about the transaction amount in the cardholder's currency.

  - `dccData.amounts.cardholder.transaction` (number, required)
    The transaction amount in the cardholder's currency.
    Example: 85.5

  - `dccData.amounts.cardholder.currencyCode` (string, required)
    The currency code associated with the transaction, in ISO 4217 format.
    Example: "EUR"

  - `dccData.exchangeRate` (number)
    The exchange rate used for the DCC conversion.
    Example: 0.855

  - `dccData.markupRate` (number,null)
    The markup rate applied to the DCC transaction.
    Example: 3.92

  - `dccData.disclaimer` (string,null)
    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."

  - `dccData.providerData` (object)
    Details about the DCC provider.

  - `dccData.providerData.provider` (string)
    The name of the DCC provider.
    Example: "Elavon"

  - `dccData.providerData.referenceId` (string,null)
    The reference ID provided by the DCC provider.
    Example: "REF123456789"

  - `dccData.providerData.merchantId` (string,null)
    The merchant ID assigned by the DCC provider.
    Example: "MERCH001"

  - `dccData.providerData.terminalId` (string,null)
    The terminal ID assigned by the DCC provider.
    Example: "TERM001"

  - `dccData.providerData.markupTextIndicator` (integer,null)
    The markup text indicator for the DCC provider.
    Example: 1

## Response 400 fields (application/json):

  - `correlationId` (string, required)
    A unique identifier generated to correlate the error with a specific transaction attempt, facilitating easier tracking and resolution of issues.

  - `details` (array)
    TBC
    Example: ["''$.site - The site field is required."]

  - `errorCode` (string, required)
    The error code returned for the operation.
    Example: "INVALID_REQUEST"

  - `errorReason` (string, required)
    The error reason returned for the operation.
    Example: "One or more validation errors occurred."