A transaction is the complete record of a payment attempt, from initial request through to final settlement, including all associated security checks, payment processing steps, and resulting status information.

The Transactions API is your primary interface for processing one-off or recurring payments with PXP. It allows you to initiate new transactions and modify existing transactions that haven't been fully processed yet.

The API supports various card payment methods and comes with a variety of built-in security features.

How it works

Sending a request

When you initiate a transaction, you have to provide key information about the transaction method, as well as the amount and currency.

The transaction method is made up of three elements:

The entry type, which describes the origin of the transaction and determines the supported payment methods and available features.
The funding type, which describes the method used to fund the transaction.
The intent, which describes the purpose of a transaction, indicating the intended money flow direction. Each intent dictates a specific transaction flow and affects how the transaction is handled by the system.

Intents

The following table describes the possible intents that you can set when you initiate a transaction.

Intent	Description
`Authorisation`	Reserve funds on the customer's payment method.
`EstimatedAuthorisation`	Reserve funds on the customer's payment method, based on an estimated amount. This method is particularly useful in environments such as hotels, car rental agencies, and fuel stations, where the final charge may vary based on additional services or usage.
`Purchase`	Capture funds immediately after authorisation.
`Payout`	Send funds to a recipient.
`Refund`	Return funds to a customer.
`Verification`	Verify that a card is legitimate and active, without reserving any funds or completing a purchase. This method is particularly useful in environments such as hotels, car rental agencies, and other scenarios where it's important to validate the card upfront, but the final transaction amount may not be known or processed immediately.

Receiving a response

Once you've successfully submitted your request, you'll receive a 200 response. The content of this response will vary depending on your specific request, but there are several key elements to pay particular attention to.

These are:

The transaction state. This state describes which step of the payment flow a transaction has reached at a given point in time.
The gateway token ID. This token is generated and maintained by PXP and allows you to process recurring transactions or transactions using stored card details, without needing to provide full card details.
The provider response. This object contains raw data received directly from the provider, such as the Payment Account Reference (PAR).

States

The following table describes the possible states that a transaction can go through.

State	Description
`Authorised`	The card issuer has approved your request and the funds are reserved.
`Captured`	Funds have been transferred to your account.
`Cancelled`	The transaction has been successfully voided by you.
`Error`	An error has occurred.
`Refused`	The transaction has been declined. This could be due to incorrect payment details or insufficient funds.

Provider response

The following table describes the different parameters included in a provider response.

Parameter	Description
`provider` string	The name of the provider that processed the transaction.
`code` string	The raw result code returned by the provider that processed the transaction.
`message` string	The raw message associated with the result code from the provider that processed the transaction.
`merchantId` string	The unique identifier assigned by the provider to represent the merchant involved in the transaction processing.
`cardVerificationCodeResult` string	The Card Verification Code (CVC) result returned by the provider. This is a raw data indicating the outcome of the CVC check performed during the transaction processing.
`addressVerificationServiceResult` string	The Address Verification Service (AVS) result returned by the provider. This is a raw data indicating the outcome of the AVS check performed during the transaction processing.
`emvDataResponse` object	Response data from an EMV (Europay, Mastercard, and Visa) transaction.
`paymentAccountReference` string	The Payment Account Reference (PAR) is a unique identifier assigned to a payment account, independent of the card number. It remains constant over the account's lifetime, even if the card number (PAN) changes. PAR enhances transaction security and privacy, serving as a secure reference point for cardholders, merchants, and issuers. It is used in digital transaction processing to reliably link transactions and accounts without exposing the actual card number.
`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.
`electronicCommerceIndicatorAdjustment` string	The `electronicCommerceIndicatorAdjustment` field represents the Electronic Commerce Indicator (ECI) adjustment made by the payment scheme after the initial transaction authorisation. The ECI signifies the level of security applied to an online transaction, indicating the authentication and verification methods used. Adjustments to the ECI reflect a re-evaluation of the transaction's security level, which can be due to various factors such as risk assessment updates, compliance with security standards, outcomes of authentication processes, interchange fee considerations, or error corrections. An ECI adjustment can either upgrade or downgrade the transaction's security indicator, impacting interchange fees, chargeback liability, and the transaction's overall security assurance. Possible values: `01`: Transaction processed with SSL or equivalent but without cardholder authentication (considered less secure, higher risk). `02`: Transaction processed with cardholder authentication (e.g., 3D Secure), indicating a higher level of security. `05`: Transaction processed with 3D Secure authentication, cardholder authenticated successfully (high security). `06`: Transaction attempted 3D Secure authentication but could not be completed; cardholder not authenticated (medium security). `07`: Transaction processed without 3D Secure authentication, due to issuer or cardholder not participating in 3D Secure (considered less secure, higher risk).
`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 you to take corrective action or understand the refusal context.
`settlementDate` date	The date on which the transaction funds are settled between banks for MasterCard payments. This field is applicable and provided only for transactions processed using MasterCard. The settlement date is crucial for financial reconciliation and is formatted as `YYYY-MM-DD`.

Supported payment methods

The following table describes the payment methods currently supported by the Transactions API.

Payment method	Description	E-commerce	MOTO	In-store
Apple Pay	Apple Pay transaction details, encapsulating the tokenised payment information. The token includes encrypted payment data, enhancing security and facilitating fraud prevention.
Physical card (Card present)	Card-related information, whether the data is captured using point-to-point encryption (P2PE) or not. The API supports various methods of card data capture including: manual key entry, swiped, chip and PIN, and contactless.
Card details (Card not present)	Card details needed to process a transaction where the physical card is not present. These include the primary account number, expiry date, card verification code (CVC), holder's name, and an optional gateway token ID for transactions using stored card information. Card details ensure secure and efficient processing of card transactions by encapsulating all card-related information.
Scheme token	A token generated by card networks such as Visa or Mastercard that enables secure transaction processing. Tokens replace sensitive card details with a unique identifier. They're particularly useful for handling recurring transactions and lightening the load of PCI DSS compliance, offering a safer alternative to transmitting complete card numbers. The scheme token is specifically designed for transactions funded by cards.

Features

The following table describes the features available with the Transactions API.

Feature	Description	E-commerce	MOTO	In-store
3D Secure (3DS)	Uses the 3D Secure protocol to verify a cardholder's identity. It works by redirecting them to their bank's authentication page during checkout, where they need to verify their identity (usually through a code sent to their phone, biometrics, or banking app), helping to prevent unauthorised card usage and reduce fraud in e-commerce transactions.
Address verification (AVS)	Checks whether the provided address matches the address on file for a specific cardholder.
Dynamic descriptor	Enables you to provide a detailed description of the transaction, so that the cardholder can more easily recognise it.
Identity verification	Checks whether the provided name matches the name on file for a specific cardholder.
Store and forward	Allows transactions to be authorised offline when the device is unable to connect to the host. Once connectivity is restored, the transactions are forwarded to the PXP host for authorisation.
Tokenisation	Substitutes sensitive data with a non-sensitive equivalent to help secure payment information.