Worldpay Corporate Gateway

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

Pre-requisites

• FinDock is installed and configured
• A working connection to ProcessingHub and WebHub
• A contract for Corporate Gateway (now known as Payment Gateway) with one or more merchant codes

Install the Worldpay Corporate Gateway extension

Follow the standard procedure for installing payment processors to add the Worldpay payment extension and activate the card payment method.

Check and assign the required permissions. If you are using custom permission set groups, ensure the package-specific permission sets are assigned.

Configure Worldpay Corporate Gateway

Configuring the Worldpay extension requires actions in FinDock and in the Worldpay merchant portal. You will need to keep both open in separate types so you can copy-paste information between the two.

Prepare Worldpay merchant code

To configure the Worldpay extension, you first need to do a few things in the Worldpay merchant portal. Use your corporate account credentials for the Worldpay login.

After logging in, select the merchant code and application you want to integrate with FinDock. For further information about the Merchant Admin Interface, please visit the Worldpay support documentation.

To prepare a Worldpay merchant code for 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.
4. Pause here. Keep the admin interface open and in another tab, go to the FinDock setup.

Keep the Merchant Admin Interface open while you configure FinDock. Some information from your Worldpay account is needed for the FinDock settings.

Create a target for the merchant code

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:

Integrate FinDock with merchant code

Now you need to complete the integration by adding the generated Notification URL for your new target into the Worldpay Admin Interface.

1. Go back to the admin interface where you left off earlier.
2. Copy-paste the notification URL from your target setup into the the address field. If you are setting up a test org, the URL should look like this: https://notifications.test.findock.com/xxxxxxx/PaymentHub-WorldPay/<target-name>/
3. Click Save Settings when you are done.

Default target

Repeat the above procedures for each Worldpay merchant code you want to integrate with FinDock. When you are done, go to the Worldpay extension tile and set one of the targets as your default target. You need to save a default even if you have only one target configured.

Bulk payment collection

The Worldpay-FinDock integration is unique when it comes to collection recurring payments. Recurring card payments are collected through Worldpay using payment schedules. However, the Worldpay integration is hybrid of filed-based and API-based collection processes.

When you run a payment schedule for Worldpay, FinDock generates a file that is automatically sent to Worldpay. The file starts the payment collection process, but the follow-up, the reconciliation, is handled through notifications from Worldpay. In other words, the initiation happens in bulk, while the collection of each installment in that file is confirmed one by one through notifications.

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 and FinDock.

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

Zero authorization for recurring payments

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.

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, 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.

One-time credit card 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": "15"
    },
    "PaymentMethod": {
        "Name": "CreditCard",
        "Processor": "PaymentHub-WorldPay"
        "Target": "WorldPay2"
    },
    "Settings": {
        "SourceConnector": "PaymentHub"
    }
}

Recurring credit card payment without 0-auth

{
    "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",
        "Target": "WorldPay2",
        "Parameters":{
              "Description":"test"
            }
    },
    "Settings": {
        "SourceConnector": "PaymentHub"
    }
}

Recurring credit card payment with 0-auth

If 0-authorization is used for your Worldpay target, you need to exclude the one-time payment block from the message since it is not needed to set up the new 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"
            }
        }
    },
    "Recurring": {
        "Amount": "25",
        "Frequency": "Monthly",
        "StartDate": "2020-12-05"
    },
  "PaymentMethod": {
        "Name": "CreditCard",
        "Processor": "PaymentHub-WorldPay",
        "Target": "WorldPay2",
        "Parameters":{
              "Description":"test with 0-auth"
            }
    },
    "Settings": {
        "SourceConnector": "PaymentHub"
    }
}