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

# Worldpay

> Accept card payments via Worldpay with PayNext.

Worldpay is a global payment processor providing card acquiring and alternative payment methods across Europe, the Americas, and Asia-Pacific.

## Processor Details

|                          |                                                                         |
| :----------------------- | :---------------------------------------------------------------------- |
| **Payment Methods**      | <Badge>Cards</Badge> <Badge>Apple Pay</Badge> <Badge>Google Pay</Badge> |
| **Supported Currencies** | Multiple (configured per merchant account)                              |
| **Metadata Mapping**     | ✓                                                                       |
| **Network Tokens**       | ✓ (upon request to Worldpay)                                            |
| **Fraud Support**        | ✓ (FraudSight)                                                          |
| **3DS Support**          | ✓                                                                       |
| **3RI Support**          | ✓                                                                       |
| **ARN**                  | ✗                                                                       |
| **Fraud Signals**        | ✗                                                                       |

## Integration Guide

<Steps>
  <Step title="Open Worldpay Merchant Admin Interface">
    Log in to the [**Worldpay Merchant Interface (MAI)**](https://secure.worldpay.com/sso/public/auth/login.html?serviceIdentifier=applicationlisttest\&maiversion=version2\&countryCode=US\&languageCode=en) and ensure your merchant code and API credentials are active.
  </Step>

  <Step title="Collect credentials">
    Obtain the following credentials from Worldpay:

    * **Merchant Code**
    * **API Username**
    * **API Password**

    <Note>
      API credentials are separate from Merchant Interface login credentials.
    </Note>
  </Step>

  <Step title="Add integration in PayNext">
    In **Dashboard → Integrations**, click **Add new integration → Worldpay → Connect**
  </Step>

  <Step title="Enter credentials">
    * **Name**: Label for this connection (e.g., "Worldpay EU")
    * **Merchant Code**
    * **API Username**
    * **API Password**
    * **Network Tokens**: Enable if activated by Worldpay
  </Step>

  <Step title="Save">
    Click **Connect** to complete the integration
  </Step>

  <Step title="Add Worldpay Webhook sending">
    In [Worldpay MAI](https://secure.worldpay.com/sso/public/auth/login.html?serviceIdentifier=applicationlisttest\&maiversion=version2\&countryCode=US\&languageCode=en) navigate to "Integration" tab on the left, then click *Merchant Channel*

    <Steps>
      <Step>
        There configure *Merchant Channels* http protocol:

        * **Active**: yes
        * **Content**: xml
        * **Address**: Check this in PayNext CRM on integrations page
        * **Method**: POST
      </Step>

      <Step>
        Then lower in Merchant Channel Events mark following columns in *http* row:

        * **CAPTURED**
        * **SETTLED**
        * **SETTLED\_BY\_MERCHANT**
        * **VOIDED**
        * **REFUNDED**
        * **REFUNDED\_BY\_MERCHANT**
        * **REFUND\_FAILED**
        * **REFUND\_REVERSED**
      </Step>
    </Steps>
  </Step>
</Steps>

## Metadata Mapping

Worldpay supports passing merchant-defined metadata in authorization requests. This allows you to control statement descriptors and attach additional context for reconciliation.

<Info>
  Descriptor customization must be enabled on your Worldpay account. Contact Worldpay support if fields are not reflected on statements.
</Info>

**Supported Fields:**

| Metadata Key          | Target Field                                     | Character Limit | Description                                                                               |
| --------------------- | ------------------------------------------------ | --------------- | ----------------------------------------------------------------------------------------- |
| `description`         | `paymentService.submit.order.description`        | 255             | Order description available in Worldpay MAI                                               |
| `statement_narrative` | `paymentService.submit.order.statementNarrative` | 50              | Statement descriptor                                                                      |
| Your own key          | `deviceSession.sessionId`                        | 128             | FraudSight device data session ID — see [FraudSight Device Data](#fraudsight-device-data) |

**Example Usage:**

```json Update Customer Metadata theme={"system"}
PATCH /customers/:id
{
  "metadata": {
    "description": "Example"
  }
}
```

## FraudSight Device Data

Worldpay's [FraudSight](https://docs.worldpay.com/access/products/fraudsight) scores a transaction using a device profile collected in the shopper's browser. Collection runs on your checkout page and returns a session ID; PayNext forwards that ID on the authorization so Worldpay ties the profile to the transaction.

<Info>
  FraudSight must be enabled on your Worldpay merchant account. Contact Worldpay support to enable it and to confirm which device data collection script your account uses.
</Info>

To pass a device session ID:

1. Ask Worldpay to enable **FraudSight** on your merchant account
2. Collect the device session ID in your checkout using Worldpay's [device data collection for web](https://docs.worldpay.com/access/products/fraudsight/device-data/web)
3. Store the ID in **payment** metadata under a key of your choice (e.g. `wp_device_session`)
4. Map that key to `deviceSession.sessionId` — see [Metadata Mapping](/guides/advanced/metadata-mapping)

```json Create Payment theme={"system"}
POST /payments
{
  "metadata": {
    "wp_device_session": "4c1a9f2b7e3d8a6f"
  }
}
```

<Note>
  The session ID is read from **payment** metadata only, not from customer or subscription metadata. A device profile belongs to one checkout, so an ID stored on a customer would be replayed on later merchant-initiated charges and describe the wrong session.
</Note>

<Warning>
  Worldpay validates the session ID value and rejects the **whole authorization** with `<error code="5">` when it is not acceptable — no authorization is attempted. Pass the ID exactly as the collection script returns it; do not add punctuation, markup, or your own prefixes. PayNext trims surrounding whitespace and omits the element when the mapped value is empty or longer than 128 characters, so a broken mapping drops the fraud signal instead of blocking the payment.
</Warning>

**Verify the device session is sent:**

Check the authorized payment payload in the PayNext dashboard. The order should include:

```xml theme={"system"}
<deviceSession>
  <sessionId>4c1a9f2b7e3d8a6f</sessionId>
</deviceSession>
```

If the element is absent, the mapping target does not match `deviceSession.sessionId` exactly (it is case-sensitive), the metadata key holds no value on that payment, or the value was dropped by the checks above.