Worldpay Integration

Worldpay (from FIS) is one of the world's largest payment processors, serving enterprise merchants across all major card networks and alternative payment methods. LostChurn connects to Worldpay using your merchant credentials and processes order notification XML messages to detect and recover failed recurring payments.

Prerequisites

• An active Worldpay merchant account
• Access to the Worldpay Merchant Admin Interface (MAI) with admin permissions
• Your Worldpay Merchant Code, XML Username, and XML Password
• A LostChurn account with at least one workspace created

Connection Steps

1. Log in to the Worldpay Merchant Admin Interface (MAI).
2. Navigate to Profile > Merchant Profile.
3. Note your Merchant Code (displayed at the top of the page).
4. Navigate to Profile > Payment Service > XML Username/Password.
5. If XML credentials have not been set up, create them by clicking Set Up and following the prompts.
6. Copy your XML Username and XML Password.
7. In your LostChurn dashboard, go to Settings > Integrations and click Connect Worldpay.
8. Enter your Merchant Code, XML Username, and XML Password.
9. Select your environment: Test or Production.
10. Click Save and Verify. LostChurn makes a test API call to the Worldpay Order Inquiry service to confirm the credentials are valid.

Webhook Configuration

Worldpay uses Order Notifications (HTTP callbacks) to push transaction results to your server.

1. In the Worldpay MAI, navigate to Profile > Merchant Profile > Payment Service.
2. Under Order Notifications, configure the following:
   • HTTP Notification URL: Set to:

     https://webhooks.lostchurn.com/v1/worldpay

   • Notification Events: Enable notifications for:
     • AUTHORISED
     • REFUSED
     • CANCELLED
     • CAPTURED
     • CAPTURE_FAILED
     • REFUNDED
     • REFUND_FAILED
     • CHARGED_BACK
     • CHARGEBACK_REVERSED
     • INFORMATION_SUPPLIED
     • EXPIRED
     • SENT_FOR_AUTHORISATION
   • Format: XML
   • Content: Select All to include full order details in the notification.
3. Click Save.

Notification Authentication

Worldpay secures order notifications using HTTP Basic Authentication. Set a username and password in the Worldpay notification configuration and enter the same credentials in your LostChurn Worldpay integration settings under Notification Authentication.

LostChurn verifies the Authorization: Basic header on every incoming notification by decoding the base64 credentials and comparing them against your configured values. Notifications with missing or invalid credentials are rejected with a 401 response.

Verify Connection

1. Worldpay does not provide a dedicated "send test notification" button in the MAI.
2. To verify the connection, process a test transaction in Worldpay's test environment:
   • Use the Worldpay XML Direct API or hosted payment page with one of Worldpay's test card numbers:
     • Card 4444333322221111 with CVC 555 to simulate a successful authorization.
     • Card 4444333322221111 with CVC 999 to simulate a REFUSED result.
3. In your LostChurn dashboard, navigate to Events and confirm the transaction notification appears.

A successful connection shows a green Connected badge on the Worldpay card in Settings > Integrations.

Supported Events

Provider-Specific Notes

Test vs. Production Environment

Worldpay provides separate test and production environments:

• Test (secure-test.worldpay.com): Simulated transactions with test card numbers. No real charges.
• Production (secure.worldpay.com): Real transactions.

Each environment uses separate credentials. You can connect both to LostChurn simultaneously. Test events are labeled with a test badge.

ISO 8583 Response Codes

Worldpay returns ISO 8583 response codes for refused transactions. LostChurn maps these to its internal decline taxonomy:

• 05 — Do Not Honor: Generic decline, retry eligible after delay.
• 51 — Insufficient Funds: Retry on a different day (e.g., after typical payday).
• 54 — Expired Card: Triggers dunning email for payment method update.
• 14 — Invalid Card Number: Requires customer to re-enter payment details.
• 41 — Lost Card / 43 — Stolen Card: No automatic retry, flagged for review.
• 61 — Exceeds Withdrawal Limit: Retry with reduced amount or after delay.
• 91 — Issuer Not Available: Temporary issue, retry within hours.

The full ISO 8583 mapping is available in Settings > Integrations > Worldpay > Decline Code Mapping.

Tokenization

Worldpay supports token-based recurring payments. When you tokenize a customer's card during the initial payment, Worldpay returns a token that can be used for subsequent charges. LostChurn references these tokens when executing retries to charge the stored payment method.

Account Updater

Worldpay's Account Updater service automatically updates stored card details when a customer's bank issues a new card number or expiry date. LostChurn benefits from this by receiving updated token data, which improves retry authorization rates. If Account Updater is not enabled on your Worldpay account, contact your Worldpay relationship manager to activate it.

Worldpay Gateway API vs. Access Worldpay

Worldpay offers multiple API platforms:

• Worldpay Gateway (WPG): The traditional XML-based API. LostChurn's current integration targets WPG.
• Access Worldpay: The newer RESTful API. LostChurn will add Access Worldpay support in a future release.

If you are on Access Worldpay and need immediate integration, contact LostChurn support to discuss options.

Batch Processing

Worldpay supports batch file processing for high-volume merchants. LostChurn can consume batch result files via SFTP if real-time notifications are not available for your account configuration. Contact LostChurn support to set up batch file integration.

3D Secure

Worldpay supports 3D Secure 2 for Strong Customer Authentication (SCA). When a retry requires 3DS authentication, LostChurn sends the customer a secure link to complete the challenge. The authentication result flows back through Worldpay's order notification system.

Rate Limits

Worldpay does not publish fixed rate limits but monitors API usage per merchant account. LostChurn distributes retry requests to maintain a steady request rate of no more than 10 requests per second by default. For enterprise merchants with higher throughput needs, contact Worldpay and LostChurn support to coordinate capacity.

Multi-Currency and Multi-Entity

Worldpay supports complex multi-currency and multi-entity merchant configurations. LostChurn connects at the merchant code level. If you have multiple merchant codes (e.g., different currencies, regions, or business lines), connect each one separately. Cross-entity recovery reporting is available in the LostChurn analytics dashboard.

Order Modification

Worldpay supports order modifications (capture, cancel, refund) through the XML API. LostChurn uses the order modification API when executing retries on partially authorized or held orders, allowing flexible recovery strategies that go beyond simple re-authorization.

Automatic Payment Retry

LostChurn can automatically retry failed Worldpay payments using the WPG XML API. Key details:

• Retry method: Submits a new order via POST /xml/paymentService.dtd with tokenized card references (TOKEN-SSL).
• Token support: Uses Worldpay payment tokens stored during the original transaction. Ensure tokenization is enabled on your Worldpay merchant account.
• ISO 8583 handling: Retry eligibility is determined by the ISO 8583 response code. Codes like 05 (Do Not Honor) and 51 (Insufficient Funds) are retry-eligible, while 54 (Expired Card) and 41/43 (Lost/Stolen) trigger dunning only.
• Gateway cascade: Worldpay participates in LostChurn's multi-gateway cascade. If a retry fails on Worldpay, the system can automatically attempt recovery through another connected PSP.
• 3DS challenges: If a retry triggers a 3D Secure challenge, LostChurn falls back to dunning with a secure payment link for the customer to complete authentication.