README

Barclaycard ePDQ hosted payments for Craft CMS and Craft Commerce, by Made By Bramble.

Customers enter their payment details on the ePDQ hosted payment page. The plugin requests an immediate payment and verifies the signed result when the customer returns to Commerce.

DirectLink, saved cards, subscriptions, refunds, separate authorization/capture and server-to-server webhooks are not supported. Refunds must be handled in the ePDQ merchant portal.

Requirements and versions

Each Craft/Commerce generation has its own branch and plugin release line. Install the release that matches your project; upgrading this plugin alone does not upgrade Craft or Commerce.

Branch	Plugin version	Craft CMS	Craft Commerce	PHP
`commerce3`	`1.x`	`3.x`	`2.x` or `3.x`	`7.2.5+`
`commerce4`	`2.x`	`4.x`	`4.x`	`8.0.2+`
`commerce5`	`3.x`	`5.x`	`5.x`	`8.2+`

This is the Commerce 5 branch. Craft 5 uses the stable craftcms/commerce-omnipay 4.x integration; there is no requirement for an Omnipay 5.x package. The actual PHP requirement may be higher when your project selects newer dependencies.

Installation

From your Craft project directory:

composer require madebybramble/craft-barclaycard-epdq:^3.1

Then open Settings → Plugins in the Craft control panel and install Bramble Barclaycard ePDQ. Its handle is bramble-barclaycard-epdq.

For an unpublished local checkout, add a Composer path repository pointing at this directory and require madebybramble/craft-barclaycard-epdq:dev-commerce5. The published package version comes from its Git tag.

Replacing the discontinued plugin

This is a separate plugin with a new package, namespace and handle. It can be installed alongside the discontinued gateway plugin; it does not rename or uninstall that plugin, reuse its license, or automatically move its gateway records.

Install the matching Bramble release on staging.
Create a new Bramble Barclaycard ePDQ gateway under Commerce → Settings → Gateways and copy your merchant and layout settings. Keep the original gateway and its historical transactions intact.
Configure both SHA passphrases and test the complete hosted checkout, including return, cancellation and declined payments.
Update any checkout code that explicitly selects a gateway ID, then enable the Bramble gateway for customers and disable customer access to the original gateway. Let any payments already in progress finish through the original gateway.
Deploy the updated Composer requirements, project config and checkout templates together. Keep the original plugin installed while its gateway or historical transactions still require it.

The new gateway class is MadeByBramble\BarclaycardEpdq\gateways\Gateway.

Merchant configuration

Open Commerce → Settings → Gateways, add Bramble Barclaycard ePDQ, and enter:

Test Mode: enable this while using your ePDQ test account.
PSPID: your ePDQ merchant affiliation name.
SHA Version: match the algorithm in ePDQ's Technical information → Global security parameters. SHA-256 is the plugin default; SHA-1 and SHA-512 are also supported.
SHA In Password: the passphrase under Data and origin verification → Checks for e-Commerce.
SHA Out Password: the passphrase under Transaction feedback → All transaction submission modes.

PSPID and both passphrases accept Craft environment variable references, such as $EPDQ_PSPID, $EPDQ_SHA_IN and $EPDQ_SHA_OUT. Store the values in your deployment environment so secrets do not enter project config. Test and production merchant credentials must match the selected mode.

In ePDQ's Transaction feedback settings, enable “I would like to receive transaction feedback parameters on the redirection URLs”. Include ORDERID, AMOUNT, CURRENCY, PAYID, STATUS and NCERROR. The browser return uses GET. The plugin accepts only signed feedback for the original transaction, amount and currency; missing or invalid signatures are rejected.

Commerce supplies the completion URL. Keep that URL intact: it identifies the payment and verifies the result before Commerce redirects to your success page. The checkout form supplies the success and cancellation destinations.

Optional hosted-page layout settings are passed to ePDQ; their appearance depends on your ePDQ account and payment page configuration. See the ePDQ hosted payment documentation.

Checkout example

Capture the cart's email and billing address, and select the new gateway, before submitting payment. This is only the final payment step:

<form method="post">
    {{ csrfInput() }}
    {{ actionInput('commerce/payments/pay') }}
    {{ redirectInput('checkout/success') }}
    {{ hiddenInput('cancelUrl', url('checkout')|hash) }}
    <button type="submit">Continue to secure payment</button>
</form>

Only confirmed payment status 9 with no payment error is treated as captured. Authorization-only, cancelled, refused and uncertain results do not mark the payment successful. Because this gateway relies on the customer's browser returning, reconcile payments in the merchant portal when the customer closes the hosted page before returning.

Development checks

composer install --no-plugins
composer test

The install command disables Composer plugins because this repository is the plugin itself, rather than a Craft application. Install normally when adding the package to a Craft project.

The check runs against the installed Craft, Commerce and Omnipay classes without contacting ePDQ. It covers gateway and template registration, required SHA-OUT settings, hosted request signatures, test/live endpoints, and valid, tampered and mismatched payment callbacks.

Run phpstan analyse with PHPStan installed to check the code against the branch's PHP version. An actual ePDQ test-account payment and return remains part of release verification.

License and support

Proprietary license. See LICENSE.md.

Contact hello@madebybramble.co.uk for support.

madebybramble / craft-barclaycard-epdq

Package info

Security

Statistics