GF SagePay

SagePay payment gateway for GravityForms.

• Goal
• Features
• Not Supported / Not Implemented
• Minimum Requirements
• Installation
  • Composer (Recommended)
  • Build from Source (Not Recommended)
• Best Practices
  • HTTPS Everywhere
  • Payment Status
  • Fraud Protection
• Test Sandbox
• Common Issues
  • Missing Gift Aid Acceptance Box
  • GF SagePay is Missing on Form Settings
• Shipping Address
  • Use case: Not delivering any physical goods
  • Use case: Allow ship to billing address
• FAQ
  • Will you add support for older PHP versions?
  • It looks awesome. Where can I find more goodies like this?
  • Where can I give ⭐⭐⭐⭐⭐ reviews?
• Developing
  • Public API
    • Build URL for continuing confirmation
    • Redirect URL Retrieval Failure Handling
  • Required Reading List
  • Gravity Forms
  • Testing
• Feedback
• Change Log
• Security
• Credits
• License

Goal

Allow Gravity Forms accepts SagePay one-off payments via SagePay Server.

Features

• SagePay Server
• Gift Aid
• 3D Secure
• AVS/CV2
• Gravity Forms Logging
• Gravity Forms Notification Events
• Gravity Forms Confirmation
• Gravity Forms Conditional Logic

Not Supported / Not Implemented

Although these features are not supported by this plugin, but you might able to do so via MySagePay:

• Card reference
• Token billing
• Deferred payment
• Recurring payment
• Void
• Refund
• Abort
• Basket
• Surcharges
• Account Type M – for telephone (MOTO) transactions
• Account Type C – for repeat transactions

Pull requests are welcomed.

Minimum Requirements

• PHP v7.2
• PHP cURL Extension
• WordPress v4.9.5
• Gravity Forms v2.4.14.4

Installation

Composer (Recommended)

composer require itinerisltd/gf-sagepay

Build from Source (Not Recommended)

# Make sure you use the same PHP version as remote servers.
# Building inside docker images is recommanded.
php -v

# Checkout source code
git clone https://github.com/ItinerisLtd/gf-sagepay.git
cd gf-sagepay
git checkout <the-tag-or-the-branch-or-the-commit>

# Build the zip file
composer release:build

Then, install release/gf-sagepay.zip as usual.

Best Practices

HTTPS Everywhere

Although SagePay accepts insecure HTTP sites, you should always use HTTPS to protect all communication.

Payment Status

Always double check payment status on MySagePay.

Fraud Protection

To prevent chargebacks, enforce 3D Secure and AVS/CV2 rules whenever possible.

Test Sandbox

Always test the plugin and your fraud protection rules in test sandbox before going live.

If you can't whitelist test server IPs, use protxross as Vendor Code.

Use ngrok to make local notification URLs publicly accessible.

Use one of the test credit cards.

Common Issues

Missing Gift Aid Acceptance Box

Only registered charities can use Gift Aid through the Sage Pay platform. The gift aid acceptance box only appears if your vendor account is Gift Aid enabled and using Donation as transaction type.

GF SagePay is Missing on Form Settings

Make sure you meet the minimum requirements. Check your environment details at the System Status Page.

Shipping Address

OmniPay requires both billing address and shipping address.

Use case: Not delivering any physical goods

Map the shipping address fields to the billing ones.

Use case: Allow ship to billing address

This is similar to the the WooCommerce way.

Use Gravity Forms' built-in feature: Display option to use the values submitted in different field

FAQ

Will you add support for older PHP versions?

Never! This plugin will only work on actively supported PHP versions.

Don't use it on end of life or security fixes only PHP versions.

It looks awesome. Where can I find more goodies like this?

• Articles on Itineris' blog
• More projects on Itineris' GitHub profile
• More plugins on Itineris and TangRufus wp.org profiles
• Follow @itineris_ltd and @TangRufus on Twitter
• Hire Itineris to build your next awesome site

Where can I give ⭐⭐⭐⭐⭐ reviews?

Thanks! Glad you like it. It's important to let my boss knows somebody is using this project. Please consider:

• leave a 5-star review on wordpress.org
• tweet something good with mentioning @itineris_ltd and @TangRufus
• ⭐ star this Github repo
• 👀 watch this Github repo
• write blog posts
• submit pull requests
• hire Itineris

Developing

Public API

Build URL for continuing confirmation

ConfirmationHandler::buildUrlFor(Entry $entry, int $ttlInSeconds = 3600): string

Usage:

$entryId = 123;
$rawEntry = GFAPI::get_entry($entryId);
if (is_wp_error($rawEntry)) {
    wp_die('Entry not found');
}

$url = ConfirmationHandler::buildUrlFor(
    new Entry($rawEntry),
    86400 // expires in 24 hours (24*3600=86400)
);

echo $url;
// https://example.com?entry=123&gf-sagepay-token=XXXXXXXXXXXX

Use Case: With "using confirmation query strings to populate a form based on another submission":

1. User fills in formA
2. User completes SagePay checkout form
3. User comes back and hits CallbackHandler
4. CallbackHandler sends user to formB according to confirmation settings
5. User arrives formB url with merged query strings

If the user quits before completing formB, you could use ConfirmationHandler::buildUrlFor generate a single-use, short-lived url for the user to resume formB.

Note:

• The url continues Gravity Forms confirmation
• Whoever got the url will go on confirmation, no authentication performed
• The confirmation will use latest field values from database which could have changed
• No payment status checking

Redirect URL Retrieval Failure Handling

After form submit, this plugin sends order information to SagePay in exchange for a redirect URL(the SagePay hosted checkout form URL).

By default, when redirect URL retrieval fails:

1. Mark entry payment status as Failed
2. Log the error
3. wp_die immediately

Common failure reasons:

• Incorrect vendor code
• Server IP not whitelisted

Tips: Check the log.

You can use 'gf_sagepay_redirect_url_failure_wp_die' filter to:

• continue Gravity Forms' feed and confirmation flow
• perform extra operations
• redirect to a different error page

Important: If this filter returns false, normal Gravity Forms' feed and confirmation flow continues. Improper settings might lead to disasters.

Example:

add_filter('gf_sagepay_redirect_url_failure_wp_die', function(bool $shouldWpDie, ServerAuthorizeResponse $response, Entry $entry, GFPaymentAddOn $addOn): bool {

    // Do something.

    return true; // Do `wp_die`
    return false; // Don't `wp_die`, continue normal flow
    return $shouldWpDie; // Undecisive
}, 10, 4);

Required Reading List

Read the followings before developing:

• SagePay Server: Understanding the process
• SagePay Server integration kits, protocols and documents
• Gravity Forms: GFPaymentAddOn
• Gravity Forms: Entry Object
• Omnipay: Sage Pay
• thephpleague/omnipay-sagepay#45 (comment)
• thephpleague/omnipay-sagepay#255 (comment)

Gravity Forms

Gravity Forms has undocumented hidden magics, read its source code.

Testing

composer style:check

Pull requests without tests will not be accepted!

Feedback

Please provide feedback! We want to make this library useful in as many projects as possible. Please submit an issue and point out what you do and don't like, or fork the project and make suggestions. No issue is too small.

Change Log

Please see CHANGELOG for more information on what has changed recently.

Security

If you discover any security related issues, please email dev@itineris.co.uk instead of using the issue tracker.

Credits

GF SagePay is a Itineris Limited project created by Tang Rufus.

Full list of contributors can be found here.

License

GF SagePay is released under the MIT License.