README

Gravity forms add-on for WorldPay.

Minimum Requirements
Installation
Setup
Security Concerns about WorldPay HTML API
Not Issue
Features
Not Supported / Not Implemented
Best Practices
- HTTPS Everywhere
- Payment Status
Test Sandbox
FAQ
- GF WorldPay is Missing on Form Settings
Public API
- Build URL for continuing confirmation
- Redirect URL Retrieval Failure Handling
Preflight
Coding
- Required Reading List
- Gravity Forms
Author Information
Feedback
Change log
License

Minimum Requirements

PHP v7.2
php-curl
WordPress v4.9.8
Gravity Forms v2.3.3.2

Installation

$ composer require itinerisltd/gf-worldpay

Setup

Payment response(redirection) and Enhancing security with MD5 are mandatory.

In the Integration Setup for your installation using the Merchant Interface > Installations option:

Enable Enable the Shopper Response
Enable Payment Response enabled?
Enter <wpdisplay item=MC_callback> as Payment Response URL
Enter a 25-char random passphrase as Payment Response password
Enter a 30-char random passphrase as MD5 secret for transactions
Enter instId:amount:currency:cartId as SignatureFields

Note that WorldPay truncate long Payment Response password without notices!

Security Concerns about WorldPay HTML API

Leaking MD5 secret for transactions
- Allow evil hackers to set up fake checkout pages, pretending to be the merchant
- WorldPay would accept these checkouts and charges the credit cards
- Money goes into the merchant's account
Leaking Payment Response password
- Allow evil hackers to pretending to be WorldPay
- WordPress would accept evil hackers' payment callbacks and changes entries' payment statuses

Not Issue

If Payment Response password(also known ascallbackPW) is incorrect, InvalidResponseException is throw to stop the world. Credit card holders see white screen of death or stuck in "wait for redirection" page in such case.

Features

Not Supported / Not Implemented

Shipping address
Reject according to fraud check results
Token payment
Recurring payment
Refund
Void

Best Practices

HTTPS Everywhere

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

Payment Status

Always double check payment status on WorldPay Merchant Interface.

Test Sandbox

Use this test credit card.

FAQ

GF WorldPay is Missing on Form Settings

Gravity Forms capabilities behave differently on multi-user sites and its documents are incomplete. If GF WorldPay is missing on form settings, grant yourself gf_worldpay and gf_worldpay_uninstall capabilities. See: https://docs.gravityforms.com/role-management-guide/

Public API

Build URL for continuing confirmation

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

Usage:

<?php
$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-worldpay-token=XXXXXXXXXXXX

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

User fills in formA
User completes WorldPay checkout form
User comes back and hits CallbackHandler
CallbackHandler sends user to formB according to confirmation settings
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 WorldPay in exchange for a redirect URL(the WorldPay hosted checkout form URL).

By default, when redirect URL retrieval fails:

Mark entry payment status as Failed
Log the error
wp_die immediately

Common failure reasons:

Incorrect vendor code
Server IP not whitelisted

Tips: Check the log.

You can use 'gf_worldpay_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_worldpay_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);

Preflight

This plugin provides built-in support for preflight-command. No extra setup steps required.

Checker ID: gf-worldpay-production-mode

ensure all gf-worldpay feeds are in production mode (i.e: not in test mode)
can't be disabled
no config options available

Coding

Required Reading List

Read the followings before developing:

Gravity Forms

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

Author Information

gf-worldpay is a Itineris Limited project created by Tang Rufus.

Full list of contributors can be found here.

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.

License

gf-worldpay is released under the MIT License.

itinerisltd / gf-worldpay

Maintainers

Details