Worldpay Corporate Gateway

What you can do

• Store a Worldpay Corporate Gateway merchant code and its XML credentials as a FloPay gateway, with separate gateways for Worldpay Secure Test and production.
• Test the stored credentials against Worldpay without changing the gateway.
• Review the capability approval that Flo Payments Operations records for your merchant code: its currencies, countries, card schemes, operations, and certifications.
• Keep your checkout code as it is. Full-mode FloPay SDK checkouts from version 1.9.15 already declare the capability that makes an approved Worldpay gateway eligible for their cards.

Who this is for

This connector is for merchants that hold a Worldpay Corporate Gateway (WPG XML Direct) merchant code and want FloPay to process card payments through it. FloPay client owners and admins configure the gateway. Developers keep using the provider-neutral FloPay SDK and REST API, so there is no Worldpay-specific checkout code to write.

The connector covers the Worldpay Corporate Gateway XML Direct integration only. It does not cover Access Worldpay, Worldpay Hosted Payment Pages, or Worldpay for Platforms.

Prerequisites

• A Worldpay Corporate Gateway merchant code for each environment you connect, with an XML username and password issued for that merchant code and environment. A personal Worldpay Merchant Interface login is not an XML credential.
• A FloPay client where you are an owner or admin.
• An active, user-owned FloPay API token if you configure the gateway through the REST API.
• A capability approval from Flo Payments Operations for each merchant code and environment. Merchants cannot create or change it. Contact FloPay to ask about approval.
• A checkout built with @flopay/react or @flopay/js 1.9.15 or later, created in Full mode with the buyer's country.

Setup

FloPay stores your Worldpay connection as a gateway record whose providerType is worldpay_corporate_gateway. One gateway represents one merchant code in one environment, and a client cannot hold two Worldpay gateways for the same merchant code in the same environment.

Client owners and admins manage gateways in Settings > Gateways or through the settings/gateways REST API. Members cannot manage gateway settings. The setup sequence uses POST /v1/settings/gateways, PATCH /v1/settings/gateways/:id, POST /v1/settings/gateways/:id/test, and POST /v1/settings/gateways/:id/activate.

Sandbox and production

Each environment needs its own gateway, merchant code, and XML credentials. Never reuse Secure Test credentials on a production gateway. The provider, environment, and merchant code lock once FloPay validates the connection, so moving to production means creating a new gateway. A Secure Test result does not prove production behavior.

Gateway lifecycle

Every new gateway starts as a draft. In this release a Worldpay gateway cannot leave draft, because FloPay refuses Worldpay activation. See Activation.

Credentials and secret handling

3DS Flex credentials are accepted and stored, but no payment flow uses them in this release. Worldpay gateways do not use publishableKey, secretKey, or webhookSigningSecret. The worldpayCapabilities record belongs to Flo Payments Operations; see Operations approval.

Read responses never return a write-only value. They report worldpayXmlUsernameConfigured, worldpayXmlPasswordConfigured, worldpayThreeDsApiIdConfigured, worldpayThreeDsOrganizationUnitIdConfigured, and worldpayThreeDsHmacKeyConfigured instead. There is no way to retrieve a submitted credential through the API or Dashboard.

To rotate a credential, submit its replacement in a normal update. Omitted credential fields keep their stored values. When a create or update includes a credential and the gateway then holds a merchant code, XML username, and XML password, FloPay validates that set with Worldpay before it saves anything. A rejected set returns 422 and leaves the stored credentials unchanged.

1. Create a draft

In the Dashboard, open Settings > Gateways > Add gateway, choose Worldpay Corporate Gateway and the environment, then create the draft. Through the API:

curl -X POST https://api.flopay.com/v1/settings/gateways \
  -u "$FLOPAY_CLIENT_ID:$FLOPAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Worldpay (Secure Test)",
    "providerType": "worldpay_corporate_gateway",
    "environment": "stage",
    "currency": "YOUR_CURRENCY",
    "countries": ["YOUR_COUNTRY"],
    "priority": 0,
    "worldpayMerchantCode": "YOUR_MERCHANT_CODE"
  }'

currency is the ISO 4217 code the gateway serves, and countries lists the ISO 3166-1 alpha-2 buyer countries it serves. Both must match your capability approval: activation requires the currency and every listed country to be approved, and a Worldpay gateway without countries cannot be activated. Creating a second gateway for a merchant code that already has one in the same environment returns 409 with Another Worldpay gateway already uses this merchant code in the selected environment.

2. Save and test credentials

Save the XML credentials on the draft. FloPay validates the complete set with Worldpay, captures the merchant code as providerAccountId, and stamps connectionValidatedAt the first time validation succeeds.

curl -X PATCH https://api.flopay.com/v1/settings/gateways/GATEWAY_ID \
  -u "$FLOPAY_CLIENT_ID:$FLOPAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "worldpayXmlUsername": "YOUR_XML_USERNAME",
    "worldpayXmlPassword": "YOUR_XML_PASSWORD"
  }'

Test the stored credentials at any time with Test connection in the Dashboard or through the API:

curl -X POST https://api.flopay.com/v1/settings/gateways/GATEWAY_ID/test \
  -u "$FLOPAY_CLIENT_ID:$FLOPAY_API_TOKEN"

The test sends Worldpay a read-only order inquiry with the stored merchant code and XML credentials. It moves no money and does not change the gateway. The response is a GatewayTestResultResponseDto:

{
  "success": true,
  "providerAccountId": "YOUR_MERCHANT_CODE",
  "error": null
}

A failed test returns success: false, providerAccountId: null, and a sanitized error that never contains credentials:

{
  "success": false,
  "providerAccountId": null,
  "error": "Worldpay rejected the XML credentials for the secure-test environment. Check the merchant code, username, password, and environment."
}

Troubleshooting lists every sanitized message and what to do about it.

3. Operations approval

Flo Payments Operations records what each merchant code may do, separately for each environment, in the gateway's worldpayCapabilities record. Merchants can read the record but not write it: a create or update that includes worldpayCapabilities returns 403 with Worldpay capability records require Operations approval. Until a record exists, the Dashboard shows Awaiting Operations approval.

Every list is an explicit allowlist, and an empty or missing value never means all. An approved operation is not necessarily available: Supported features shows what this release can run.

4. Order Notifications

Worldpay reports order changes through Order Notifications. FloPay accepts them only over mutual TLS, from a Worldpay client certificate that Flo Payments Operations has certified for the environment. There is no webhook signing secret to copy into FloPay, so leave webhookSigningSecret unset. Operations sets up and certifies notifications for your merchant code, and orderNotificationsCertified in the approval record shows the result, as does the gateway's Webhook setup section in the Dashboard.

In this release FloPay acknowledges authenticated Order Notifications but does not apply them to payments.

5. Activation

curl -X POST https://api.flopay.com/v1/settings/gateways/GATEWAY_ID/activate \
  -u "$FLOPAY_CLIENT_ID:$FLOPAY_API_TOKEN"

Activation checks completeness first. A gateway missing worldpayMerchantCode, worldpayXmlUsername, worldpayXmlPassword, or worldpayCapabilities returns 409 with Activation requires a complete provider connection. Missing: followed by the missing fields. Activation then checks the approval: a current approval window, the gateway currency and every gateway country in the allowlists, at least one card scheme, order_inquiry, certified order_notifications, and PCIVault outbound proxy certification. An approval that includes three_ds or stored_credentials also blocks activation.

Checkout

Worldpay is a server-side card gateway. When a checkout can use a Worldpay gateway, the same hosted card form that buyers already see captures the card, and FloPay charges it through Worldpay server-side. There is no Worldpay browser SDK, key, or checkout code to add.

Opt a checkout in

POST /v1/checkouts/sessions makes an approved Worldpay gateway eligible only when the request sends the token worldpay-corporate-gateway-v1 in the X-Flo-SDK-Capabilities header. The billing API stores that decision on the session and applies it to the session's claim, reads, and card capture. FloPay SDKs from version 1.9.15 send the token for you:

• FloPayCheckout with createSession, PaymentAPI.createAndFetchSession, or PaymentAPI.createDetachedSession, in Full mode without tokenizedData, send it.
• Auto, Confirm, and pre-tokenized sessions do not, because they charge a stored payment method that the Worldpay route does not accept.
• Redirect sessions from createCheckoutSession, server-side creates with @flopay/node, and older SDKs send nothing, so those sessions are never routed to Worldpay.

A checkout needs no Worldpay-specific props:

import { FloPayCheckout } from '@flopay/react';
import type { DeclineEvent, FloPayError, InlineSessionDraft, PaymentResult } from '@flopay/shared';

const createSession: InlineSessionDraft = {
  clientId: 'YOUR_FLOPAY_CLIENT_ID',
  currency: 'YOUR_CURRENCY',
  products: [{ code: 'YOUR_PRODUCT_CODE', quantity: 1 }],
  account: { userId: 'YOUR_BUYER_ID', email: 'BUYER_EMAIL', country: 'BUYER_COUNTRY' },
  successUrl: 'https://YOUR_DOMAIN/success',
  cancelUrl: 'https://YOUR_DOMAIN/checkout',
};

export function Checkout() {
  return (
    <FloPayCheckout
      createSession={createSession}
      onComplete={(result: PaymentResult) => {
        if (result.status === 'succeeded') window.location.assign('/success');
      }}
      onDecline={(decline: DeclineEvent) => console.info(decline.code)}
      onError={(error: FloPayError) => console.error(error.code)}
    />
  );
}

If you build the create request yourself for a checkout that the FloPay SDK renders, send the same header with the released @flopay/shared helpers. resolveSessionCreateCapabilities returns worldpay-corporate-gateway-v1 for a Full-mode draft without tokenizedData and undefined for any other draft, and FLO_SDK_CAPABILITIES_HEADER is the header name:

import {
  FLO_SDK_CAPABILITIES_HEADER,
  type InlineSessionDraft,
  resolveSessionCreateCapabilities,
} from '@flopay/shared';

export function sessionCreateHeaders(draft: InlineSessionDraft): Record<string, string> {
  const capabilities = resolveSessionCreateCapabilities(draft);
  return {
    'Content-Type': 'application/json',
    ...(capabilities ? { [FLO_SDK_CAPABILITIES_HEADER]: capabilities } : {}),
  };
}

Which sessions route to Worldpay

FloPay routes a session's cards to a Worldpay gateway only when all of these hold:

1. The session was created with the worldpay-corporate-gateway-v1 capability.
2. The Worldpay gateway is active and its approval window is current.
3. The approval includes purchase for automatic capture or authorization for manual capture, together with order_inquiry, certified order_notifications, and PCIVault outbound proxy certification.
4. The session currency matches the gateway currency and is in the approved currencies.
5. The buyer country (account.country) is set, is one of the gateway countries, and is in the approved countries.
6. The cart holds one-time items only, all in one currency. A cart with a subscription routes to another gateway, and attaching one to a session that was bound to Worldpay returns 409 with Attached checkout cart has no compatible non-Worldpay payment gateway. when no other gateway can take it.

A routed session carries data.gateways.worldpayCorporateGateway in CheckoutSessionResponseDto:

{
  "publishableKey": null,
  "environment": "stage",
  "enabledPaymentMethods": [],
  "enabledPaymentMethodCountries": {}
}

The entry carries no browser credential or payment method, and the SDK never lists it in the normalized providers. Your checkout code does not need to check for it.

Outcomes

onComplete omits paymentIntentId for Worldpay-routed sessions, because a Worldpay order reference is not a Stripe PaymentIntent. Reconcile those payments with the checkout session and paymentId instead. If you mount the hosted card widget directly from @flopay/js, treat the completion event's intentId as an opaque processor reference.

Session endpoints that do not apply

• POST /v1/checkouts/sessions/:id/process is not part of the Worldpay card path. The hosted card form submits the card and FloPay charges it server-side, and the Worldpay route does not accept the saved or tokenized payment methods that /process charges.
• POST /v1/checkouts/sessions/:id/3ds/complete resolves Stripe 3DS state and has no Worldpay equivalent. Worldpay 3DS Flex is not available in this release, and a Worldpay-routed session has no 3DS step for the buyer.

Verify your setup

1. Read the gateway with GET /v1/settings/gateways/:id, or open it in Settings > Gateways. Check that providerType is worldpay_corporate_gateway, environment is the environment you intended, worldpayMerchantCode is your merchant code, and both worldpayXmlUsernameConfigured and worldpayXmlPasswordConfigured are true. connectionValidatedAt shows when FloPay first validated the credentials.
2. Run the connection test. Confirm that success is true and providerAccountId matches your merchant code.
3. Check the worldpayCapabilities record: expiresAt is in the future, currencies includes the gateway currency, countries includes every gateway country, and orderNotificationsCertified and pcivaultProxyCertified are both true.
4. Payment verification is not possible in this release, because activation is refused. When FloPay routes a session to an active Worldpay gateway, the session response includes data.gateways.worldpayCorporateGateway, and you reconcile that payment with the checkout session and paymentId rather than a Stripe identifier.

Supported features

Limitations

• In Preview, FloPay refuses Worldpay activation, so no checkout is routed to Worldpay and no payment is processed through it.
• Capture, void, and refund are not available for Worldpay payments.
• 3DS Flex, stored credentials, saved cards, card setup, subscriptions, and wallets are not available through Worldpay.
• Authenticated Order Notifications are acknowledged but not applied to payments.
• Only sessions created with the worldpay-corporate-gateway-v1 capability can use Worldpay: Full-mode checkouts from SDK 1.9.15 or later, with a buyer country, a single currency, and one-time items only.
• Currencies, countries, and card schemes are limited to the Operations approval for each merchant code and environment.
• The provider, environment, and merchant code cannot change after validation, and a merchant code can have only one gateway per environment.
• Secure Test does not move funds or contact card issuers, so its results do not prove production behavior.
• The connector covers the Worldpay Corporate Gateway XML Direct integration only.

Troubleshooting

Match the sanitized message FloPay returns to its fix below. If you need help, contact FloPay and share only the gateway ID, environment, time, and message.

Related links

• Accept a payment
• FloPayCheckout API
• resolveSessionCreateCapabilities
• CheckoutGatewaysDto
• Checkout continuation authentication
• Stripe connector