> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payrails.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code.
> Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it.
> Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code.
> Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation.
> Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent.
> Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format.
> Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code.

# Worldpay

> Connect Worldpay to Payrails for cards, wallets and local payment methods, covering the entity, credentials and webhook setup.

<Note>
  **Who should use this guide**

  This guide is intended for merchants who:

  * Use **Payrails** as a payment orchestrator
  * Use **Worldpay** (Access Worldpay) for card, wallet or local payment method processing
  * Have an active Worldpay account with API credentials and an entity
</Note>

***

## Create a Worldpay integration in Payrails

1. Log in to the **Payrails** portal.
2. Go to **Settings** → **Integrations**.
3. Select **Add instance** to create a new integration configuration.
4. Select the **workspaces** where this integration should be available.

<Note>
  **About workspaces**

  Workspaces determine where this integration is available. They let you isolate provider setups by region or business line, or share the same configuration across multiple workspaces.
</Note>

***

## Step 1: Choose the integration type

* Select **Payment**.
* Continue to the next step.

***

## Step 2: Choose the provider

* Select **Worldpay**.
* Continue to the next step.

<img src="https://mintcdn.com/payrails-42074109/G8QHkudphIMP7MDF/images/docs/worldpay-image-01.png?fit=max&auto=format&n=G8QHkudphIMP7MDF&q=85&s=b26dffa7c3801febdcc6ee65003f36cf" alt="A screenshot showing Worldpay selected as the provider." className="mx-auto block rounded-lg object-cover border border-gray-200" width="80%" data-path="images/docs/worldpay-image-01.png" />

***

## Step 3: Configure your Worldpay integration

<Tip>
  **What you'll need from Worldpay**

  Before you begin, make sure you have your Worldpay API username and password, your entity, and access to the Worldpay dashboard to set up webhooks.
</Tip>

***

### Integration instance name

> An integration instance is a specific payment provider setup in Payrails. You can create multiple instances for different regions, currencies, or business needs. Choose a clear, consistent name, as it is used in routing.

**In Payrails**

* Enter an **Instance name** for your integration, for example `merchant_worldpay`.

<img src="https://mintcdn.com/payrails-42074109/145W1v58K5wnDMNC/images/docs/orchestration/integrations/shared/integration-instance-name.png?fit=max&auto=format&n=145W1v58K5wnDMNC&q=85&s=470be58979509680650b0cbf8b5eecc4" alt="A screenshot showing the integration instance name field." className="mx-auto block rounded-lg object-cover border border-gray-200" width="80%" data-path="images/docs/orchestration/integrations/shared/integration-instance-name.png" />

***

### Account details

**In Payrails**

| Field | Value |
| :- | :- |
| **Entity** | The Worldpay entity that processes your payments: the merchant or business unit Worldpay set up for you |
| **Support Account Funding Transactions (AFTs)** | Refer to [Configure Worldpay settings](#configure-worldpay-settings) |
| **Support Mastercard Transaction Link Identifier (TLID)** | Refer to [Configure Worldpay settings](#configure-worldpay-settings) |

<img src="https://mintcdn.com/payrails-42074109/G8QHkudphIMP7MDF/images/docs/worldpay-image-02.png?fit=max&auto=format&n=G8QHkudphIMP7MDF&q=85&s=a7132c98340333549d2a0463cf935570" alt="A screenshot showing the Worldpay account details fields." className="mx-auto block rounded-lg object-cover border border-gray-200" width="80%" data-path="images/docs/worldpay-image-02.png" />

***

### Payment methods

**In Payrails**

* Select the payment methods to enable for this integration: **Card**, **Apple Pay**, **Google Pay** or the local payment methods Worldpay processes for you, such as [iDEAL](/docs/orchestration/payment-methods/ideal/worldpay), [Bancontact](/docs/orchestration/payment-methods/bancontact/worldpay), [Trustly](/docs/orchestration/payment-methods/trustly/worldpay), [Przelewy24](/docs/orchestration/payment-methods/przelewy24/worldpay), [SafetyPay](/docs/orchestration/payment-methods/safetypay/worldpay), [UnionPay](/docs/orchestration/payment-methods/unionpay/worldpay), [Multibanco](/docs/orchestration/payment-methods/multibanco/worldpay), [Konbini](/docs/orchestration/payment-methods/konbini/worldpay), [Alipay](/docs/orchestration/payment-methods/alipay/worldpay) and [WeChat Pay](/docs/orchestration/payment-methods/wechat-pay/worldpay).

<img src="https://mintcdn.com/payrails-42074109/G8QHkudphIMP7MDF/images/docs/worldpay-image-03.png?fit=max&auto=format&n=G8QHkudphIMP7MDF&q=85&s=1eb4d25c6fffcdc43968f166ca16bdb6" alt="A screenshot showing the Worldpay payment method selection." className="mx-auto block rounded-lg object-cover border border-gray-200" width="80%" data-path="images/docs/worldpay-image-03.png" />

***

### Credentials

**In Payrails**

| Field | Value |
| :- | :- |
| **Username** | Your Worldpay API username |
| **Password** | Your Worldpay API password |
| **HMAC Secret Key** | The secret key of your Worldpay webhook. Payrails uses it to verify Worldpay's notifications. |

Payrails sends requests to Worldpay's test environment in test mode and to Worldpay's live environment in live mode, so use the credentials for the matching environment.

<img src="https://mintcdn.com/payrails-42074109/G8QHkudphIMP7MDF/images/docs/worldpay-image-04.png?fit=max&auto=format&n=G8QHkudphIMP7MDF&q=85&s=988eaa8ec3eb7915794e2b86a5cf004a" alt="A screenshot showing the Worldpay credential fields." className="mx-auto block rounded-lg object-cover border border-gray-200" width="80%" data-path="images/docs/worldpay-image-04.png" />

***

### Webhooks or notifications

<Info>
  Payrails uses provider webhooks or notifications to receive asynchronous
  payment status updates.
</Info>

<Warning>
  Create webhooks in the same mode (test or live) as your Payrails integration.
</Warning>

**In Payrails**

* Copy the **Notification URL** shown under **Account configuration** at the top of the integration form.

**In Worldpay**

1. In the Worldpay dashboard, create a webhook with the Payrails notification URL.
2. Subscribe it to the payment events: sent for authorization, authorized, refused, sent for settlement, settlement failed, sent for refund, refund failed, cancelled, expired, error and token created.
3. Set the webhook to sign events with an HMAC secret key, and enter the same key in **HMAC Secret Key** in Payrails.

***

## Request fields for Worldpay

Send these fields in the [authorize request](/reference/authorizeaction) for card payments, in addition to the standard authorize fields. **Required** fields must be present for the payment to succeed. Payrails sends **Optional** fields to Worldpay when you include them. For more about meta fields, refer to [Meta fields](/docs/orchestration/meta-fields).

| Field | Status | Description |
| :- | :- | :- |
| `amount` | Required | Sent to Worldpay as the instruction value. |
| `meta.order.softDescriptor` | Required | Sent as the statement narrative. |
| `meta.order.billingAddress.postalCode`, `meta.order.billingAddress.country.code` | Required | When you send a billing address. Sent as the billing postal code and country. |
| `meta.customer.name`, `meta.customer.lastName` | Required | When you save the card. Sent as the card holder name. |
| `meta.order.billingAddress.street`, `meta.order.billingAddress.city` | Optional | Sent as the billing address. |
| `meta.order.fundsTransfer` | Optional | Account funding transactions only. Refer to [Configure Worldpay settings](#configure-worldpay-settings). |
| `merchantReference` | Optional | Sent as the transaction reference. |

***

## Configure Worldpay settings

Some Worldpay integration settings change how Payrails processes your payments. The portal shows the same description when you hover over each setting.

### Support Account Funding Transactions (AFTs)

Turn on **Support Account Funding Transactions (AFTs)** to send account funding data with your authorizations. Payrails adds the recipient and sender details from `meta.order`, the customer and the billing address to the Worldpay request.

### Support Mastercard Transaction Link Identifier (TLID)

Turn on **Support Mastercard Transaction Link Identifier (TLID)** only after Worldpay switches TLID on for your entity; ask your Worldpay relationship manager. Payrails then quotes the stored transaction link ID with the network transaction reference on merchant-initiated Mastercard payments. With the setting off, merchant-initiated payments quote the network transaction reference alone.

### Acquirer details for 3D Secure

If you run 3D Secure through Payrails rather than through Worldpay, fill in the acquirer BIN and acquirer merchant ID for each card scheme you process: **Acquirer Bin Visa**, **Acquirer Merchant ID Visa** and the matching Mastercard and Amex fields. Your acquirer assigns these values. Payrails sends them with each 3D Secure authentication for that card scheme.

***

## Enable the integration

**In Payrails**

* Select **Save account** to enable the integration.
* Confirm the integration shows as **Enabled**.

Your **Worldpay** integration is now ready to process payments.

***

## Next steps

1. Run a test payment using a Worldpay [test card](https://developer.worldpay.com/products/access/reference/testing).
2. Verify that:
   * The payment appears in Worldpay.
   * The payment status updates correctly in Payrails.
3. Once verified in test mode, repeat the setup in live mode.

→ Continue to: [Test a payment](/docs/orchestration/payment-acceptance/test-payments)


## Related topics

- [Multibanco via Worldpay](/docs/orchestration/payment-methods/multibanco/worldpay.md)
- [Konbini via Worldpay](/docs/orchestration/payment-methods/konbini/worldpay.md)
- [Bancontact via Worldpay](/docs/orchestration/payment-methods/bancontact/worldpay.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.