How it works

Learn about how the Transactions API works.

Overview

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 allows you to initiate and later modify transactions for e-commerce, MOTO, and in-store.

Diagram showing how the Transactions API 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`.