pps-platform-transaction

Overview

The PPS Transaction API gives direct visibility of transactions processed by the PPS platform. A transaction represents one of the following activities:

• A movement of funds between two parties. Examples of such financial transactions include purchases or refunds from stores, bank payments and other back-office activities. It is not possible to change an account balance without a corresponding transaction record.
• A request by one party to perform some non-financial activity. Typical non-financial transactions are balance enquires or card block activities. Note that where a fee is charged for a non-financial transaction it may also represent a movement of funds between the two parties.

The Transaction API presents a consistent representation of a transaction regardless of the payment channel. The following sections summarise the key fields and concepts involved in transaction processing on the PPS platform.

The PPS Transaction

Payment Schemes

A scheme represents a channel or entity capable of initiating transactions. Examples of schemes include Mastercard, Faster Payments and PPS Web Authorisation amongst many others. Contact PPS to determine the specific schemes applicable to a programme.

The supported lifecycle of a transaction is defined by the payment scheme which may specify:

• A single transaction event or a separate authorisation and clearing phase
• The ability to cancel (reverse) previous transaction activity
• Restrictions on the ability of the processor to approve or decline transactions
• Additional features or capabilities of the payment network

Authorisation

Authorisation is the processes of arriving at a decision to allow or decline a request for payment. Such decisions may be made on a wide variety of criteria bit will typically ask questions such as:

• Does the account balance have sufficient funds or remaining credit to cover the transaction?
• Does a purchase exceed any limits defined to guard against fraud (e.g. a daily ATM spend limit)?
• Has the card reached its expiry date?

Depending on the payment scheme an authorisation decision may indicate the completion of the transaction (a financial movement of funds) or simply a temporary reservation of funds where a separate clearing phase is mandated.

Clearing

Payment schemes that mandate a separate clearing phase will typically submit clearing or settlement instructions relating to previously approved authorisations. Such instructions may be received in real-time (usually soon after the related authorisation) or submitted in batches at an agreed interval. In general, such instructions, are considered to represent the final state of a transaction and cannot be declined. Clearing instruction may typically confirm the original authorisation details but may also change financial amounts and include additional data.

While clearing instructions cannot typically be declined, payment schemes may provide further mechanisms by which unapproved transactions values can be reclaimed. For example, if a clearing record exceeds the amount of the original authorisation and the account is unable to cover the additional cost, Mastercard would allow losses to be reclaimed through its Chargeback process.

Many payment schemes with separate authorisation and clearing phases mandate, in some circumstances, the acceptance of clearing records that have not been previously authorised. Such transactions, termed 'offline', may require a dispute mechanism where the funds cannot be covered by the account.

Key Fields

PPS supply a large number of properties to describe a transaction although not all properties will be relevant for all payment schemes and transaction types. See the API documentation for full details of available fields.

The following key fields are mandated or typically present and are required to understand the Transaction and its lifeycle.

Id

Every transaction is assigned a unique identifier by PPS. The id will not change despite multiple activities on the transaction (e.g. clearing).

Scheme Id

While the Transaction abstracts many details of the underlying payment scheme the Scheme Id provides a unique identifier for each payment scheme. Contact PPS for the list of possible Scheme Ids for a programme.

Transaction Lifecycle Status

PPS provide a standardised representation of a Transaction across payment schemes. In order to interpret Transactions on the PPS platform it is important to understand the Transaction lifecycle.

The Transaction Lifecycle Status is present on all Transaction resources and indicates the current phase of transaction processing for all payment schemes and transaction types. As such, and depending on subscribed features, a client may see the same Transaction at different stages in its lifecycle.

The allowed lifecycle statuses are:

The Transaction Lifecycle state model

Transaction Result

The Transaction Result indicates the authorisation decision taken by PPS or by the External Authorisation Endpoint. The Transaction Result may have one of the following values:

Note that the Transaction Result must be considered with the Transaction Lifecycle Status to understand the true status of a Transaction. For example a Transaction with a Transaction Result of 'Approved' (the authorisation decision) may have a Transaction Lifecycle Status of 'Cancelled' or 'Expired'. In such a case any funds reserved or debited by the Transaction because of the approval should be reversed. Only transactions with a 'Completed' lifecycle state and an 'Approved' or 'Approved with Exception' result may be considered a completed movement of funds.

Payee and Payer

The Payee and Payer define the parties involved in the transaction.

In a financial Transaction the Payee is always the party in receipt of funds represented by the Transaction. Where the Payee is a PPS account we would expect the balance to be credited by the amount of the transaction. For a non-financial Transaction the Payee is the party requesting the non-financial activity.

In a financial Transaction the Payer is always the party providing the funds represented by the Transaction. Where the Payer is a PPS account we would expect the balance to be debited by the amount of the transaction. For a non-financial Transaction the Payer is the party performing the non-financial activity (e.g. the account being blocked).

Supported Payee and Payer types are:

See the API documentation for full details of the specific properties provided for each Payee/Payer type.

Transaction Amounts

A Transaction defines the following financial amounts:

Where a payment scheme supports a separate authorisation and clearing phase the Transaction may include two sets of currency amounts under the Authorisation and Clearing properties. Note that when present (only when the scheme has a separate clearing phase) the Clearing amounts should always take precedence as the true value of the Transaction.