{ "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.\n", "example": "INVALID_REQUEST", "type": "string" }, "errorReason": { "description": "The error reason returned for the operation.\n", "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" } } } } } }