Download the PHP package academe/opayo-pi without Composer

• Opayo Pi PSR-7 Message REST API Library
  • Package Development
  • Want to Help?
  • Overview; How to use
    • Installation
    • Create a Session Key
    • Get a Card Identifier
    • Submit a Transaction
    • Fetch a Transaction Result Again
    • Repeat Payments
    • Using 3D Secure
    • 3D Secure Versions 1
      • 3D Secure Version 1 Redirect
      • Final Transaction After 3D Secure
    • 3D Secure Versions 2
      • SCA: Strong Customer Authentication
      • 3D Secure Version 2 Redirect
      • 3D Secure Version 2 Notification Handling
    • Saving and Reusing Cards
  • Payment Methods

Note

This package is forked from academe/SagePay-Integration in a new repository due to the change in the composer package name.

Opayo Pi PSR-7 Message REST API Library

This package provides the data models for the Opayo Pi (was Sage Pay Integration) payment gateway. It does not provide the transport mechanism, so you can use what PSR-18 client you like for that, for example Guzzle (7+ or 6+HTTPlug adapter), curl or another PSR-7 library.

You can use this library as a PSR-7 message generator/consumer, or go a level down and handle all the data through arrays - both are supported.

This package has been updated to use the new Elavon URLs, that will be mandatory from March 2024.

Package Development

The Opayo Pi payment gateway is a RESTful API run by by Elavon.

You can apply for an account here (partner link).

From v3.0.0 this package is being rebranded for Opayo, gets a new composer name, and a new base namespace.

The PSR7 branch is now in maintenance mode only, and won't have any major changes - just bugfixes if they are reported. The aim is to release on the master branch as soon as a demo (and some units tests) are up and running.

The aim is for this package to support, at the backend, all functionality that the gateway supports.

Want to Help?

Issues, comments, suggestions and PRs are all welcome. So far as I know, this is the first API for the Opayo Pi REST API, so do get involved, as there is a lot of work to do.

Tests need to be written. I can extend tests, but have not got to the stage where I can set up a test framework from scratch.

More examples of how to handle errors is also needed. Exceptions can be raised in many places. Some exceptions are issues at the remote end, some fatal authentication errors, and some just relate to validation errors on the payment form, needing the user to fix their details. Temporary tokens expire over a period and after a small number of uses, so those all need to be caught and the user taken back to the relevant place in the protocal without losing anything they have entered so far (that has not expired).

Overview; How to use

Note that this example code deals only with using the gateway from the back-end. There is a JavaScript front-end too, with hooks to deal with expired session keys and card tokens. This library does provide support for the front end though, and this is noted where relevant.

Installation

Get the latest release:

composer.phar require academe/opayo-pi

Until this library has been released to packagist, include the VCS in composer.json:

"repositories": [
    {
        "type": "vcs",
        "url": "https://github.com/academe/SagePay-Integration.git"
    }
]

Create a Session Key

The CreateSessionKey message can be used like this:

The session key will be valid for 20 minutes, and allows the front end of your site to save card details at Opayo, using the form integration JavaScript or the Drop-In Checkout. This way the card details stay at the front end, and do not go near your server.

Get a Card Identifier

The Card Identifier (a temporary, tokenised card detail, where teh card is actually stored at Opayo) can be created using the equally temporary session key.

Normally it would be created on the front end, using an AJAX request from your browser, so the card details would never touch your application. For testing and development, the card details can be sent from your test script, emulating the front end, and that is detailed below.

At this point the card details are sane and have been saved in the remote API. Nothing has been checked against the bank, so we have no idea yet if these details will be authenticated or not.

What is a mystery to me is just why the card identifier is needed at all. The session key is only valid for one set of card details, so the session key should be all the Sage Pay needs to know to access those card details when the final purchase is requested. But no, this additional "card identifier" also needs to be sent to the gateway.

The merchantSessionKey identifies a short-lived storage area in the gateway for passing the card details from client to gateway. The cardIdentifier then identifies a single card within the storage area.

Submit a Transaction

A transaction can be initiated using the card identifier.

Fetch a Transaction Result Again

Given the TransactionId, you can fetch the transaction details. If the transaction was successful, then it will be available immediately. If a 3D Secure action was needed, then the 3D Secure results need to be sent to Sage Pay before you can fetch the transaction. Either way, this is how you do it:

Repeat Payments

A previous transaction can be used as a base for a repeat payment. You can amend the shipping details and the amount (with no limit) but not the payee details or address.

All other options remain the same as for the original transaction (though it does appear that giftAid can now be set in the API).

Using 3D Secure

Now, if you want to use 3D Secure (and you really should, and will be forced to in 2022).

To turn on 3D Secure, use the appropriate option when sending the payment:

3D Secure Versions 1

This is being phased out in the EC by the end 2021 and the the UK by March 2022. Please use Version 2, which will be mandatory.

3D Secure Version 1 Redirect

The result of the transaction, assuming all is otherwise fine, will be a Secure3DRedirect object. This message will return true for isRedirect(). Given this, a POST redirection is needed. Note also that even if the card details were invalid, a 3D Secure redirect may still be returned. It is not clear why the banks do this, but you need to be ready for it.

This minimal form will demonstrate how the redirect is done:

The above example does not take into account how you would show the 3D Secure form in an iframe instead of inline. That is out of scope for this simple description. Two main things need to be considered when using an iframe: 1) the above form must target the iframe by name; and 2) on return to the $termUrl, the page must break itself out of the iframe. That's the absolute essentials.

This form will then take the user off to the 3D Secure password page. For Sage Pay testing, use the code password to get a successful response when you reach the test 3D Secure form.

Now you need to handle the return from the bank. Using Guzzle you can catch the return message as a PSR-7 ServerRequest like this:

or

Both will work fine, but it's just about what works best for your framework and application.

Handling the 3D Secure result involves two steps:

1. Passing the result to Sage Pay to get the 3D Secure state (CAUTION: see note below).
2. Fetching the final transaction result from Sage Pay.

Final Transaction After 3D Secure

Whether 3D Secure passed or not, get the transaction. However - do not get it too soon. The test instance of Sage Pay has a slight delay between getting the 3D Secure result and being able to fetch the transaction. It is safer just to sleep for one second at this time, which is an arbitrary period but seems to work for now. A better method would be to try immediately, then if you get a 404, back off for a short time and try again, and maybe once more if necessary. This is supposed to have been fixed in the gateway several times, but still gets occasionally reported as still being an issue.

3D Secure Versions 2

This will be mandatory worldwide in 2022, so start using it now.

SCA: Strong Customer Authentication

3D Secure version 2 flow is triggered by supplying SCA information. The following example is a minimal SCA object. There is no guidance on the Opayo site on how all this information is gathered and how it is used, and there are very few defaults, so some experimentation is needed.

Note that unlike 3DS v1, the notification URL - where the user is sent back with the results - are supplied right at the start, whether a redirect is needed or not.

This is passed in as an additional option when creating the paymennt.

3D Secure Version 2 Redirect

The bank or 3DS rules may decide that no further authentication is needed, and so no redirect is necessary, then you will get the transaction details back immediately.

If a redirect is needed, then it is done through a POST like 3DS v1.

3D Secure Version 2 Notification Handling

After the redirect, the ACS will return the user to your notificartion URL with a result. Check the response has come from the ACS and instantiate the server request object:

Finally use that result to get the transaction authorisation result. The $transactionId should be the returned value from the original CreatePayment request.

Saving and Reusing Cards

See the Opayo documentation for reusable tokens.

A previous transaction can be used as a base for a repeat payment. This must be set correctly in your initial request:

After the 3D secure response you can save the card details returned:

In future requests you can then reuse the token. You can amend the shipping details and the amount (with no limit) but not the payee details or address.

Merchants / admin users can place orders on a customers behalf using their saved cards. They can bypass the need for a CVC entirely, but you need a telephone/MOTO facility enabled with Opayo (not available in Sandboxes).

You will also need to provide a credential type with your requests.

Payment Methods

At this time, Sage Pay Pi supports just card payment types. However, there are three different types of card object:

1. SingleUseCard - The fist time a card is used. It has been tokenised and will be held against the merchant session key for 400 seconds before being discarded.
2. ReusableCard - A card that has been saved and so is reusable. Use this for non-interaractive payments when no CVV is being used.
3. ReusableCvvCard - A card that has been saved and so is reusable, and has been linked to a CVV and merchant session. Use this for interactive reuse of a card, where the user is being asked to supply their CVV for additional security, but otherwise do not need to reenter all their card details. The CVV is (normally) linked to the card and the merchant session on the client side, and so will remain active for a limited time (400 seconds).

The ReusableCard does not need a merchant session key. ReusableCvvCard does require a merchant session key and a call to link the session key + card identifier + CVV together (preferably on the client side, but can be done server-side if appropriately PCI accredited or while testing).

A CVV can be linked to a reusable card with the LinkSecurityCode message:

To save a reusable card, take the PaymentMethod from a successful payment. Note: it is not possible at this time to set up a reusable card without making a payment. That is a restriction of the gateway. Some gateways will allow you to create zero-amount payments just to authenticate and set up a reusable card, but not here.