gf-worldpay

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:

1. Enable Enable the Shopper Response
2. Enable Payment Response enabled?
3. Enter <wpdisplay item=MC_callback> as Payment Response URL
4. Enter a 25-char random passphrase as Payment Response password
5. Enter a 30-char random passphrase as MD5 secret for transactions
6. 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

• Enhancing security with MD5
• Gravity Forms Logging
• Gravity Forms Notification Events
• Gravity Forms Confirmation
• Gravity Forms Conditional Logic

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":

1. User fills in formA
2. User completes WorldPay 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 WorldPay in exchange for a redirect URL(the WorldPay 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_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:

• WorldPay HTML API
• Gravity Forms: GFPaymentAddOn
• Gravity Forms: Entry Object
• Omnipay: WorldPay
• thephpleague/omnipay#255 (comment)

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.