PPS ORIAN API

To integrate with the ORIAN Delegated Authorisation or Transaction Notification capability the integrator must be prepared to receive the ORIAN Transaction resource (data object). The ORIAN Transaction provides a standardised representation of transactions processed on a variety of underlying payment schemes . In order to integrate transactions through the ORIAN API it is necessary to understand certain ORIAN and more general transaction processing concepts.

Transaction Processing

Overview

A transaction, as published through the ORIAN API, may represent 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.
• 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.

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', would typically require a dispute mechanism where the funds cannot be covered by the account.

ORIAN Key Fields

ORIAN supplies 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 ORIAN Transaction and its lifeycle.

Id and Version

Every transaction has a unique identifier assigned by PPS that will be received for all versions of the Transaction. Two events received with the same Transaction Id should be assumed to represent the same Transaction.

The Version indicates the revision of the Transaction resource. For example, an Authorised transaction published to the ORIAN endpoint might have a Version of 1. Later when the same Transaction is cleared it may be published to the ORIAN endpoint with a version of 2.

It is important to consider the Version before taking action on any Transaction published to the endpoint. While PPS will make best effort to always deliver notifications in the order they occurred there exists the possibility that events could arrive out of sequence. In the case that a Transaction event is received with a Version lower than a Version already received for the same Transaction Id implementers should discard the event.

Note that PPS also reserve the right to re-submit the latest Version of a Transactions in order to respond to potential failure situations. The ORIAN endpoint is free to discard or re-apply the Transaction event if it has already been applied.

Scheme Id

While the ORIAN 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

ORIAN provides a standardised representation of a Transaction across payment schemes. In order to implement the ORIAN API to accommodate a wide variety of such schemes it is important to understand the ORIAN Transaction lifecycle.

The Transaction Lifecycle Status is submitted with all Transaction events and indicates the current phase of transaction processing for all payment schemes and transaction types. As such, and depending on subscribed features, an endpoint may see the same Transaction at different stages in its lifecycle.

The allowed lifecycle statuses are:

The ORIAN Transaction Lifeycle 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.

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.

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

An ORIAN 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 the Clearing amounts should always take precedence as the true value of the Transaction.

3DS Secure Auth Results