Worldpay Corporate Gateway

Worldpay is a global payment service provider headquartered in the United States.

note

This article is for Worldpay Corporate Gateway only. If you have a Worldpay Business Gateway 350 account, please go to the BG350 configuration article.

Multi-merchant	Multi-currency

Payment Method	One-time	Recurring	Refunds
Card

Pre-requisites

• FinDock is installed and configured.
• A working connection to ProcessingHub and WebHub.

Install and activate Worldpay extension

Follow the standard procedure for installing and activating the payment extension (the WorldPayCorporate for PaymentHub package). Activate the PaymentHub-WorldPay processor and the credit card payment method.

Check and assign the required permissions for FinDock and Worldpay features. Ensure all package-specific permission sets are correctly assigned.

Set up Worldpay account

Before configuring the Worldpay extension, you need to do some configuration in the Worldpay merchant portal. Your organization should have a corporate account with Worldpay. Use those account credentials here: Worldpay login.

After logging in, you need to select a merchant code and application if your organization has more than one. For further information about the Merchant Admin Interface, please visit the Worldpay support documentation.

note

Testing of the Worldpay integration requires a test setup with Production Mode.

To set up Worldpay integration with FinDock:

1. In the left-hand menu, enable Production Mode.
   
2. Click INTEGRATION in the left-hand menu, and then select the Merchant Channel tab.
   
3. Under Merchant Channels (test or production, depending on what phase of development you are in), set the http protocol to active, select xml as the content type, and then add the callback URL of your WebHub that will use Worldpay in the address field. E.g. https://notifications.test.findock.com/xxxxxxx/PaymentHub-WorldPay
4. Click Save Settings when you are done.
5. Keep the Merchant Admin Interface open while you configure FinDock. Some information from your Worldpay account is needed for the FinDock settings.

Configure Worldpay extension

After you have finished the Worldpay merchant account setup, you can configure the Worldpay extension in FinDock.

To configure the Worldpay extension:

1. Launch the FinDock app and click Setup.
2. Click on the PaymentHub-Worldpay tile under Extensions - PSP.
   
3. Fill in the settings as described below.
   
   • Notification URL: this value is automatically filled by the Notification Gateway.
   • Endpoint: the Worldpay service endpoint for authorizations and transactions. Enter the endpoint depending on whether you are configuring a sandbox (test) or production org.
     • Test: https://secure-test.worldpay.com/jsp/merchant/xml/paymentService.jsp
     • Production: https://secure.worldpay.com/jsp/merchant/xml/paymentService.jsp
   • Merchant Code: enter here your code from the ACCOUNT page of the Worldpay Merchant Admin Interface.
   • Username: enter here the Original XML Username from the ACCOUNT page of the Worldpay Merchant Admin Interface.
   • Password: enter here the XML Password from the ACCOUNT page of the Worldpay Merchant Admin Interface
4. When you have entered all the details, click Save.

Create a Worldpay target

When using Worldpay to collect recurring credit card transactions in bulk, you need a Target that allows the bulk upload to be correctly routed to Worldpay.

To create a target for Worldpay:

1. Launch the FinDock app and click Setup.
2. Click on the ProcessingHub tile under Extensions - System.
3. Click on the Targets tab.
4. Click the Add Target button and on the New Target dialog, give a transparent name that indicates its purpose.
5. Select the Target type PaymentHub Worldpay and click Save.
   
6. You are automatically returned to the Targets tab. Click the button to the right of the target you just created and select Settings.
   
7. Fill in the Worldpay target settings as described below.
   • BATCH_XML_VERSION: change the default version only if you have a specific reason for doing so
   • CURRENCY: Enter your default currency. If your org has multi-currency support enabled, this setting is ignored, and the currency from the installment is used instead.
   • MERCHANT_CODE: your code from the Merchant Admin Interface
   • RECORDS_PER_FILE: unless otherwise decided, leave this at the default value. If the number of transactions exceeds this threshold, FinDock creates multiple files for bulk collection
   • Upload Copy to Chatter: enable if you want the generated bulk payment file that is sent to Worldpay to also be uploaded to Chatter
   • XML_API_ENDPOINT: use the same endpoint here as in the Worldpay extension settings
   • XML_API_USERNAME: use the same username here as in the Worldpay extension settings
   • XML_API_PASSWORD: use the same password here as in the Worldpay extension settings
   • Use 0-authorization: Enable zero authorization for setting up recurring payment is set up. Do not enable until this feature is activated for you. See below for details.
8. When you are done filling in the settings, click Save.

Refund and other status handling

Worldpay for FinDock supports both partial and full refunds. The refund handling differs based on the refund type:

• Full refund: the status of the installment is set to Reversed and a negative payment with the full refund amount is created.
• Partial refund: the status of installment is set to Partially paid and a negative payment with the amount of the partial refund is created.

The following table contains the full range of status mappings between Worldpay CG and FinDock.

Worldpay status	FinDock status
SENT_FOR_AUTHORISATION	Pending Processing
AUTHORISED	Collected
CAPTURED	Collected
SETTLED	Collected
CHARGED_BACK	Reversed*
REFUSED	Failed
ERROR	Failed
CANCELLED	Failed
EXPIRED	Failed
REFUNDED	Reversed*
REFUNDED_BY_MERCHANT	Reversed*

^* Or the status is set to Partially paid if amount is less than installment amount.

Zero authorization for recurring payments

LIMITED AVAILABILITY

Zero authorization is not yet available to all FinDock Worldpay Corporate Gateway customers. It is currently in closed testing as part of the FinDock MOTO Worldpay pilot.

When creating a new recurring card payments through Worldpay, you normally need to include a nominal initial one-time payment. The initial payment is used to verify the cardholder details.

For online payments via the Payment API, if the payer entered incorrect information, that initial payment fails. The payer learns this immediately from the Worldpay hosted payment page.

For MOTO payments, the recurring payment setup separates the verification (shopper tokenization) from the payment request, bypassing the need for an initial payment. This process ensures the recurring payment authorization, but if something is incorrect with the cardholder information, the actual payment collection fails. This is difficult to rectify as the payer is no longer present to correct the information.

ACTION REQUIRED

You need to contact Worldpay to have them enable zero authorization for your account (per merchant code) before you can use it with FinDock.

The zero authorization (0-authorization) flow offers immediate cardholder verification without requiring an initial nominal amount for a new recurring payment. In other words, 0-authorization is a method of validating cardholder details by using a payment with an amount of 0.

With this flow, FinDock uses a different callout to Worldpay that combines the shopper token setup with the recurring payment request. For MOTO payments, for example, this allows immediate verification of the cardholder details with the card issuer. If there is a problem, agents will see the errors in the FinDock Payment component so they can be fixed while the payer is still present.

For MOTO payments, 0-authorization is automatically used to set up recurring payments when this 0-authorization is enabled on the selected target. For payments via the FinDock Payment API, 0-authorization is optional even when enabled for the given target. To use 0-authorization via the API, you simply leave out the otherwise mandatory OneTime object from the recurring payment API request.

Payment API

To test your Worldpay configuration for one-time payments, you can use the following API messages.

If your configuration is correct, you should be able to navigate to the RedirectURL provided in the response and pay the amount specified. When a redirect ends in an unexpected error, the error message is stored in the last status reason of the installment.

note

In production, recurring credit card tokens are created with an initial lifetime of four years. In testing, tokens are created with a lifetime of seven days.

This following request initiates a one-time credit card transaction with Worldpay.

{
    "SuccessURL": "https://www.example.com/success",
    "FailureURL": "https://www.example.com/error",
    "Payer": {
        "Contact": {
            "SalesforceFields": {
                "FirstName": "Eric",
                "LastName": "Johnson",
                "Email": "eric@johnson.com"
            }
        }
    },
    "OneTime": {
        "Amount": "15"
    },
    "PaymentMethod": {
        "Name": "CreditCard",
        "Processor": "PaymentHub-WorldPay"
    },
    "Settings": {
        "SourceConnector": "PaymentHub"
    }
}

The following request initiates a recurring payment.

{
    "SuccessURL": "https://www.example.com/success",
    "FailureURL": "https://www.example.com/error",
    "Payer": {
        "Contact": {
            "SalesforceFields": {
                "FirstName": "Eric",
                "LastName": "Johnson",
                "Email": "eric@johnson.com"
            }
        }
    },
    "OneTime" : {
        "Amount" : "0.01"
    },
    "Recurring": {
        "Amount": "25",
        "Frequency": "Monthly",
        "StartDate": "2020-12-05"
    },
  "PaymentMethod": {
        "Name": "CreditCard",
        "Processor": "PaymentHub-WorldPay",
        "Parameters":{
              "Description":"test"
            }
    },
    "Settings": {
        "SourceConnector": "PaymentHub"
    }
}