# How to Integrate Retool with Worldpay

- Tool: Retool
- Difficulty: Advanced
- Time required: 45 minutes
- Last updated: April 2026

## TL;DR

Connect Retool to Worldpay using a REST API Resource with API key authentication against Worldpay's JSON API. Build enterprise payment operations panels that display transaction data, manage dispute workflows, track settlement reports, and monitor payment success rates across global merchant accounts. Worldpay serves high-volume enterprise merchants with complex multi-currency and cross-border payment requirements.

## Build a Worldpay Enterprise Payment Operations Panel in Retool

Worldpay is one of the world's largest payment processors, serving enterprise merchants who process high volumes of transactions across multiple currencies, countries, and payment methods. Operations teams at these organizations need custom dashboards that provide faster, more targeted views of transaction data, dispute queues, and settlement reports than Worldpay's standard merchant portal allows.

A Retool integration with Worldpay enables building an operations command center: a transaction search panel that filters by payment method, currency, outcome, and date range; a disputes dashboard that surfaces open chargebacks with aging timers and documentation upload capabilities; and settlement reconciliation reports that match Worldpay's settlement data against your internal order management system. These panels are particularly valuable for finance teams, fraud operations analysts, and customer service teams who need payment data alongside other internal data sources.

Worldpay's API landscape requires careful attention because the FIS acquisition consolidated multiple legacy platforms. Merchants on the older Worldpay UK platform use different endpoints and authentication from those on the newer Worldpay from FIS platform. This guide covers both patterns and helps you identify which applies to your merchant account. Because Retool proxies all API requests server-side, your Worldpay credentials never reach end users' browsers, and CORS is not a concern for any Worldpay endpoint.

## Before you start

- A live Worldpay merchant account with API access enabled — contact your Worldpay relationship manager to request API credentials (self-serve API access is not available for all merchant tiers)
- Your Worldpay API credentials: service key (for older Worldpay UK platform) or client key + service key pair (for newer platform) — these are provided by your Worldpay account manager
- Knowledge of which Worldpay platform you are on: legacy Worldpay UK (api.worldpay.com) vs Worldpay from FIS (access.worldpay.com) — check your merchant portal URL to determine this
- A Retool account with permission to create Resources and Configuration Variables
- Understanding of payment processing concepts: authorization, settlement, chargebacks, interchange

## Step-by-step guide

### 1. Identify your Worldpay API platform and obtain credentials

Worldpay operates multiple API platforms due to mergers and acquisitions over the years. Before configuring Retool, you must identify which platform your merchant account uses, as the base URLs, authentication methods, and endpoint structures differ significantly. Check your Worldpay merchant portal URL: if it is merchant.worldpay.com, you are on the legacy UK platform (api.worldpay.com/v1/); if it is online.worldpay.com or Worldpay from FIS portal, you are on the newer platform (access.worldpay.com/). Contact your Worldpay relationship manager or support team to request API access and obtain your credentials. For the legacy platform, you receive a Service Key (a 64-character string starting with 'T_S_' for test mode or 'L_S_' for live). For the newer FIS platform, you may receive a separate Client Key and Service Key plus a Merchant ID. For Worldpay's Online Payments REST API, the base URL is https://api.worldpay.com/v1 with Basic Auth using the Service Key as the username and an empty password. In Retool's Settings → Configuration Variables, add WORLDPAY_SERVICE_KEY and WORLDPAY_MERCHANT_ID (if applicable), marking both as secret. For test mode credentials (T_S_ prefix), always build and test your integration in test mode before requesting live credentials. Worldpay test environment: https://api.worldpay.com/v1 with test key. The same API structure applies to both test and live; only credentials and behavior differ.

**Expected result:** You have identified your Worldpay platform type, obtained API credentials from your relationship manager, and stored them as secret configuration variables in Retool.

### 2. Create the Worldpay REST API Resource in Retool

In Retool, navigate to the Resources tab and click Add Resource. Select REST API from the resource type list. Name it 'Worldpay API'. For the Base URL, use the URL appropriate for your platform: https://api.worldpay.com/v1 for the legacy UK platform, or https://access.worldpay.com for the newer FIS platform. If you do not know which applies, use the legacy URL as a starting point — your account manager can confirm. Scroll to the Authentication section. For the legacy Worldpay platform, select Basic Auth. In the Username field, enter {{ retoolContext.configVars.WORLDPAY_SERVICE_KEY }}. Leave the Password field blank (Worldpay uses the service key as the username with no password). For the FIS platform, select API Key from the authentication dropdown and configure the key header name and value as instructed by your Worldpay account manager — FIS authentication varies by product tier. In the Headers section, add: Content-Type = application/json and Accept = application/json. Some Worldpay endpoints also require a specific API version header — check your Worldpay API documentation for the current version header requirement. Click Save Changes. You will verify the connection when you create your first query. If your organization uses Worldpay Self Service (the smaller merchant tier), note that the available API endpoints and data access levels may be more limited than enterprise tier access.

**Expected result:** A 'Worldpay API' resource appears in the Retool Resources list configured with Basic Auth using your service key.

### 3. Build transaction query and search functionality

Worldpay's transaction search is a core capability for operations dashboards. In the Retool Code panel, create a new query, select the Worldpay API resource, set Method to GET, and enter a path appropriate to your platform. For the legacy Worldpay REST API, orders are accessible at /orders/{orderCode} for individual orders or via reporting endpoints if your account has reporting API access. For the Worldpay Reporting API (a separate product requiring enterprise enablement), the base URL and endpoints differ — contact your account manager for access. For the most common setup (legacy UK platform), create a query at /orders/{{ orderCodeInput.value }} to retrieve a specific order by code. Add URL parameters for date filtering where supported: 'fromDate' = {{ dateRange.startDate }} and 'toDate' = {{ dateRange.endDate }}. A more powerful approach for transaction reporting is Worldpay's Batched Reports API, which generates downloadable settlement and transaction reports. Create a second query with Method GET and path /reports to list available reports. Write a JavaScript transformer to parse the payment data from Worldpay's response structure, which nests transaction details under a 'paymentResponse' object. Map payment state codes ('AUTHORIZED', 'SETTLED', 'REFUNDED', 'FAILED') to human-readable labels in the transformer. Note that Worldpay's API documentation is accessible at developer.worldpay.com — bookmark the specific section for your account type.

```
// Transformer: normalize Worldpay order/transaction response
const order = data;
if (!order || order.httpStatusCode) {
  return [{ error: order?.message || 'No order found' }];
}

const paymentState = {
  'AUTHORIZED': 'Authorized',
  'SETTLED': 'Settled',
  'REFUNDED': 'Refunded',
  'PARTIALLY_REFUNDED': 'Partial Refund',
  'FAILED': 'Failed',
  'CANCELLED': 'Cancelled',
  'EXPIRED': 'Expired'
};

return [{
  order_code: order.orderCode,
  amount: order.amount ? `${(order.amount / 100).toFixed(2)} ${order.currencyCode}` : 'N/A',
  status: paymentState[order.paymentStatus] || order.paymentStatus,
  card_scheme: order.paymentResponse?.cardType || 'N/A',
  last_four: order.paymentResponse?.maskedCardNumber?.slice(-4) || 'N/A',
  created_at: order.createdOn || 'N/A',
  settlement_currency: order.settlementCurrency || order.currencyCode
}];
```

**Expected result:** The transaction query returns a normalized order record with status, amount, card details, and settlement information visible in the Results panel.

### 4. Build the payment monitoring dashboard UI

With queries configured, build the operations dashboard. From the component panel, drag a Text Input component named 'orderCodeInput' for single-order lookup, and a Date Range Picker for period-based reporting. Add a Button labeled 'Search' that triggers your transaction query on click. Below the search controls, drag a Table component bound to {{ getTransactions.data }}. Configure columns for: order_code (rendered as a clickable link), amount, status (with conditional formatting: green for SETTLED, blue for AUTHORIZED, red for FAILED/REFUNDED), card_scheme, last_four, and created_at. Add a Stats row at the top using Stat components showing: total transaction count ({{ getTransactions.data?.length || 0 }}), total settled amount (computed with a JavaScript query that sums amounts where status is 'Settled'), and decline rate (declined count / total count as a percentage). For a disputes/chargebacks panel, create a second tab in a Tab Container. Build a disputes query targeting Worldpay's dispute endpoints if your account tier has access, or create a manual disputes tracker using Retool Database where operations staff log dispute details and deadlines. Add a Chart component showing transaction volumes by day using data from your settlement reports, configured as a Bar Chart with date on the X-axis and total settled value on the Y-axis. For enterprise deployments managing multiple merchant accounts or Worldpay entities, RapidDev's team can help design a multi-entity architecture that aggregates payment data across accounts in Retool.

```
// JavaScript query: calculate payment summary metrics
const transactions = getTransactions.data || [];
const settled = transactions.filter(t => t.status === 'Settled');
const failed = transactions.filter(t => t.status === 'Failed');

const totalSettledAmount = settled.reduce((sum, t) => {
  const amount = parseFloat(t.amount.split(' ')[0]) || 0;
  return sum + amount;
}, 0);

return {
  total_count: transactions.length,
  settled_count: settled.length,
  failed_count: failed.length,
  decline_rate: transactions.length > 0
    ? ((failed.length / transactions.length) * 100).toFixed(1) + '%'
    : '0%',
  total_settled: `${totalSettledAmount.toFixed(2)} ${settled[0]?.amount?.split(' ')[1] || ''}`
};
```

**Expected result:** A payment operations dashboard displays transaction search results with summary stats, status-colored Table rows, and a volume Chart, all updated when the search form is submitted.

### 5. Implement dispute management and refund workflows

For operations teams handling chargebacks and customer refunds, add workflow capabilities to the dashboard. Create a refund query: in the Code panel, add a new query on the Worldpay API resource with Method POST, Path /orders/{{ transactionsTable.selectedRow.order_code }}/refund. Set Body Type to JSON and Body to a Worldpay refund request object: { "amount": {{ parseInt(parseFloat(refundAmountInput.value) * 100) }}, "currencyCode": "{{ transactionsTable.selectedRow.currency_code }}" }. Name this query 'initiateRefund'. Add an event handler on the refund query's On Success: 'Show notification' with message 'Refund initiated for order ' + transactionsTable.selectedRow.order_code, then 'Trigger query → getTransactions' to refresh the data. Wrap the refund button in a Confirm Modal to prevent accidental refunds — add the modal via the Button's event handler with confirmation message 'Refund {{ refundAmountInput.value }} for order {{ transactionsTable.selectedRow.order_code }}?'. For chargebacks, Worldpay's dispute management API availability depends on your merchant tier. If available, create a GET query to /disputes with status filter parameters to list open disputes. If dispute API access is not included in your tier, build a manual dispute tracking panel using Retool Database: create a 'disputes' table with columns for worldpay_order_code, reason_code, amount, deadline_date, status, and evidence_notes. This gives your team a structured workflow even without direct API dispute access.

```
{
  "method": "POST",
  "path": "/orders/{{ transactionsTable.selectedRow.order_code }}/refund",
  "body": {
    "amount": {{ parseInt(parseFloat(refundAmountInput.value) * 100) }},
    "currencyCode": "{{ transactionsTable.selectedRow.currency_code || 'GBP' }}"
  }
}
```

**Expected result:** Refund workflows function correctly with confirmation dialogs, and dispute tracking is operational either via Worldpay API or Retool Database fallback.

## Best practices

- Store Worldpay service keys and merchant credentials in Retool Configuration Variables marked as secret — payment processor credentials are among the most sensitive secrets in your organization and must never appear in query bodies or URL parameters
- Maintain separate Retool resources for test and live Worldpay environments and require explicit confirmation when switching a dashboard from test to live mode to prevent accidental live transactions
- Convert all amounts to minor currency units (pence, cents) before submitting to Worldpay's API, and explicitly handle zero-decimal currencies (JPY, HUF, TWD) where amounts are not multiplied by 100
- Log every refund and write operation to a Retool Database audit table before calling the Worldpay API — Worldpay does not provide webhook callbacks for all operations, so maintaining an internal audit trail is essential for reconciliation
- Use Worldpay's idempotency key support where available to prevent duplicate operations when refund or capture requests time out and are retried by operators
- Apply Retool's query caching (30-60 seconds) to transaction list queries to avoid hitting Worldpay's rate limits when multiple finance team members have the dashboard open simultaneously
- For dispute workflows, set deadline-based conditional formatting on Table rows using Retool's column color settings — highlight disputes due within 48 hours in orange and within 24 hours in red to prevent missed chargeback response deadlines

## Use cases

### Build a real-time transaction monitoring and search dashboard

Create a Retool operations panel that queries Worldpay transactions by date range, amount, currency, payment method, and outcome status. Display results in a filterable Table with columns for order reference, card scheme, currency, amount, settlement status, and risk score. Include one-click refund initiation for eligible transactions and export to CSV for reconciliation workflows.

Prompt example:

```
Build a Retool dashboard showing Worldpay transactions filterable by date range, currency, card scheme, and outcome (authorized/declined/refunded). Include a Table with transaction details and a refund button that triggers a Worldpay refund API call for the selected transaction.
```

### Build a dispute and chargeback management panel

Create a Retool dispute operations dashboard that pulls open Worldpay disputes/chargebacks with their reason codes, deadlines, and dispute amounts. Display a Table sorted by response deadline with color-coded urgency (red for disputes due within 24 hours), and include a Form to submit dispute evidence and update dispute status directly from Retool.

Prompt example:

```
Build a Retool chargeback management panel that shows all open Worldpay disputes sorted by response deadline, with columns for reason code, amount, days remaining, and a form to record dispute evidence and submit responses.
```

### Build a settlement reconciliation and reporting dashboard

Create a Retool finance dashboard that queries Worldpay settlement reports and displays net settlement amounts by currency, comparing expected vs actual settlement values. Combine Worldpay settlement data with your internal order database to flag discrepancies, and show Chart visualizations of daily settlement volumes and interchange fee breakdowns.

Prompt example:

```
Build a Retool settlement dashboard that fetches Worldpay settlement reports for a date range, joins settlement data with internal order records from PostgreSQL, and shows a Chart of daily net settlement amounts per currency with variance highlighting.
```

## Troubleshooting

### 401 Unauthorized on all Worldpay API queries despite correct credentials

Cause: Worldpay's legacy platform uses Basic Auth where the Service Key is the username and the password must be empty (not null or undefined). If Retool sends the password field with any content — even an empty string handled incorrectly — the authentication fails. Also, test keys (T_S_ prefix) only work against the test environment and live keys (L_S_ prefix) only against the live environment.

Solution: In the Retool resource settings, verify that the Authentication type is Basic Auth, the Username field contains only your Service Key, and the Password field is completely empty. Verify you are using a test key against the test base URL and a live key against the live URL. If still failing, regenerate the Service Key in your Worldpay merchant portal (Dashboard → API Keys) and update the Retool configuration variable.

### Worldpay API returns 404 Not Found for valid order codes

Cause: Worldpay order codes are case-sensitive and must match exactly as created in the payment request. Additionally, orders from different merchant account entities may not be accessible via the same API key, and orders older than the API's retention window (typically 13 months for the legacy UK platform) are not returned via the API.

Solution: Ensure the order code in the Retool query is transmitted with exact case matching. Check that the API key used in Retool corresponds to the same merchant entity that created the order — if your organization has multiple Worldpay merchant accounts, each uses separate credentials. For historical data beyond the API retention window, use Worldpay's reporting portal or downloadable settlement files instead.

### Refund API call returns 400 Bad Request with 'amount exceeds original order amount'

Cause: Worldpay validates that refund amounts do not exceed the original order amount minus any previously issued refunds. The refund amount must be submitted as an integer in the smallest currency unit (pence for GBP), not as a decimal. Passing a decimal value like 29.99 instead of the integer 2999 causes a validation error.

Solution: In the refund query body, convert the display amount to minor units using parseInt(parseFloat(refundAmountInput.value) * 100). For currencies with zero decimal places (JPY, KRW), do not multiply by 100. Retrieve the original order first using a GET query and display the remaining refundable amount in the UI to prevent over-refund attempts.

```
// Correct amount conversion for Worldpay
const displayAmount = parseFloat(refundAmountInput.value) || 0;
const minorUnits = parseInt(displayAmount * 100); // For 2-decimal currencies
```

### Settlement data in the dashboard does not match amounts in the Worldpay merchant portal

Cause: Worldpay's settlement amounts in the API reflect gross transaction values before interchange fees, scheme fees, and Worldpay processing fees are deducted. The merchant portal may show net settlement amounts after fee deductions, causing an apparent discrepancy.

Solution: Clarify with your Worldpay account manager which settlement figure the API returns (gross vs net). If you need net settlement amounts for reconciliation, request access to Worldpay's Reconciliation or Reporting API which returns itemized fee breakdowns alongside settlement values. Display the fee components separately in your Retool dashboard rather than relying on a single settlement figure.

## Frequently asked questions

### Does Retool have a native Worldpay connector?

No, Retool does not include a native Worldpay connector. You connect Worldpay via a REST API Resource configured with Basic Auth (Service Key as username, empty password) or the authentication method specified by your Worldpay account manager. The specific base URL and endpoint structure depends on which Worldpay platform your merchant account uses — legacy UK platform (api.worldpay.com) or Worldpay from FIS (access.worldpay.com).

### How do I get API access to Worldpay for a Retool integration?

Worldpay API access is not available for self-sign-up for most merchant tiers. Contact your dedicated Worldpay relationship manager or account manager and request API credentials. Specify that you need access to the Orders API and, if available for your tier, the Reporting API. You will receive test credentials (T_S_ prefix) first for integration testing, followed by live credentials (L_S_ prefix) after validation.

### Can I access Worldpay settlement and reconciliation data via API?

Settlement data accessibility via API depends on your merchant tier. The basic Worldpay API provides order-level transaction data, but detailed settlement reports with fee breakdowns are typically accessible through Worldpay's Reconciliation API or Reporting API, which are separate products available for enterprise merchant accounts. Ask your account manager about the Worldpay Reporting API access for your account. Alternatively, Worldpay provides downloadable settlement files via SFTP that can be imported into Retool Database for manual reconciliation dashboards.

### How do I handle Worldpay's different API versions and platforms?

Configure separate Retool REST API Resources for each Worldpay platform your organization uses (legacy UK vs FIS platform). Name resources clearly (e.g., 'Worldpay UK Legacy' and 'Worldpay FIS') and create query groups or Retool apps that target the appropriate resource. Avoid mixing queries from different platforms in the same app to prevent authentication and endpoint confusion.

### What is the recommended approach for multi-currency Worldpay dashboards?

When building dashboards that display transactions across multiple currencies, always preserve the original currency code alongside amounts rather than converting to a base currency in the transformer. Display amounts as '{amount} {currencyCode}' strings and use separate Chart series per currency for trend visualization. For cross-currency aggregation (e.g., total settled value in USD equivalent), use a separate FX rates API resource in Retool and join the data in a JavaScript transformer — never rely on Worldpay's settlement amounts for cross-currency comparisons without explicit FX rate context.

---

Source: https://www.rapidevelopers.com/retool-integrations/worldpay
© RapidDev — https://www.rapidevelopers.com/retool-integrations/worldpay