Worldpay

Card payment processing for European markets. Supports hosted payment page (HPP) and direct card integration modes with optional tokenisation and FraudSight risk assessment.

Operations: Pay-In ✓ | Pay-Out - | Webhook ✓
Processing: Asynchronous - redirect to hosted page or direct card submission
Integration modes: HPP (default) | Direct

Fields marked with * are required.

Configuration (Mozarto back office)

These fields are in the locked API Credentials section of the account's Processing Scope tab. Unlock it with your 2FA code first - see Unlock API credentials.

Field	Description
`accountName` *	Display name for this account
`merchantCode` *	Worldpay merchant code
`installationId` *	Worldpay installation ID
`xmlUsername` *	Worldpay XML API username
`xmlPassword` *	Worldpay XML API password
`webhookUrl` *	Your HTTPS endpoint for transaction status updates
`captureDelay`	Days before capture: `DEFAULT`, `0`-`14`, or `OFF` (default: `DEFAULT`)
`macSecret`	MAC secret for payment response verification
`integrationMode`	`"hpp"` (default) or `"direct"`
`tokenizationEnabled`	Enable card tokenisation (default: `false`)
`siteUrl`	Your site URL - required for Mozarto to append result redirect URLs to the HPP link
`hppPaymentMethodMask`	Restrict which payment methods appear on the HPP

Pay-In

POST /v1/api/mozarto/cashier

Request body

Field	Type	Description
`pspType` *	string	Always `"WORLDPAY_EU"`
`type` *	string	Always `"PAYIN"`
`baseamount` *	number	Amount as a number (e.g. `150.00`)
`currency` *	string	Currency code (e.g. `"EUR"`, `"GBP"`)
`userId` *	string	Your internal user/player identifier
`email` *	string	User's email address
`firstName` *	string	User's first name
`lastName` *	string	User's last name
`phone` *	string	Phone number (min 6 digits)
`gender` *	string	User's gender
`dob` *	string	Date of birth in `YYYY-MM-DD` format (e.g. `"1990-01-15"`)
`country` *	string	Payer's country - full name, ISO 3166-1 alpha-2, or alpha-3 (e.g. `"Germany"`, `"DE"`, `"DEU"`). See Country codes. Matched against the account's Processing Scope, and converted to alpha-2 for Worldpay's billing/shipping address. Omit it and Mozarto geo-locates the caller's IP instead
`kycVerified` *	boolean	Whether user has passed KYC
`blocked` *	boolean	Whether user is blocked
`isVelocity` *	boolean	Velocity check flag
`transactionCount` *	string	Number of prior transactions
`userBalance` *	number	User's current balance
`partnerName` *	string	Partner/operator name
`emailVerification` *	string	Verified email address
`verificationDate` *	string	Date email was verified in `YYYY-MM-DD` format (e.g. `"2024-01-01"`)
`bonusCode`	string	Bonus code
`tags`	array	Tag list
`address` *	object	See address fields below
`card`	object	Card details (for direct mode only)
`integrationMode`	string	`"hpp"` or `"direct"`
`createToken`	boolean	Create a reusable card token
`enableTokenization`	boolean	Enable tokenisation for this transaction
`deviceSessionId`	string	Device session ID (required for FraudSight direct)
`fraudSightSessionId`	string	FraudSight session ID
`fraudSightData`	object	See FraudSight fields below

Address fields

Field	Type	Description
`address.line1` *	string	Street address line 1
`address.line2`	string	Street address line 2
`address.line3`	string	Street address line 3
`address.city` *	string	City
`address.state` *	string	State or region
`address.postalCode` *	string	Postal / ZIP code
`address.country` *	string	Country code

Card fields (direct mode only)

Field	Type	Description
`card.pan` *	string	Card number (max 16 digits)
`card.expiry` *	string	Expiry in `"MM/YYYY"` format
`card.cvv` *	string	CVV (max 3 digits)
`card.cardHolderName` *	string	Cardholder name

FraudSight fields (optional)

Field	Type	Description
`fraudSightData.shopperName`	string	Shopper's full name
`fraudSightData.shopperId`	string	Your internal shopper ID
`fraudSightData.birthDate`	object	`{ dayOfMonth, month, year }`
`fraudSightData.shopperAddress`	object	Shopper address for risk assessment

Example request (HPP mode)

{
  "pspType": "WORLDPAY_EU",
  "type": "PAYIN",
  "baseamount": 150.00,
  "currency": "GBP",
  "userId": "user_123",
  "email": "player@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "phone": "07700900123",
  "gender": "female",
  "dob": "1990-01-15",
  "country": "GB",
  "kycVerified": true,
  "blocked": false,
  "isVelocity": false,
  "transactionCount": "5",
  "userBalance": 500,
  "partnerName": "ExamplePartner",
  "emailVerification": "player@example.com",
  "verificationDate": "2024-01-01",
  "address": {
    "line1": "123 Main Street",
    "city": "London",
    "state": "England",
    "postalCode": "SW1A 1AA",
    "country": "GB"
  }
}

Response

{
  "status": "success",
  "message": "Successfully",
  "isSuccess": true,
  "data": {
    "orderCode": "MZRT_64a1f2b3c4d5e6f7a8b9c0d1_1714000000000",
    "paymentUrl": "https://hpp.worldpay.com/app/hpp/integration/wpg/corporate?OrderKey=...",
    "transactionId": "64a1f2b3c4d5e6f7a8b9c0d1",
    "merchantReference": "",
    "amount": 10,
    "transaction_status": "Pending"
  }
}

Note: Worldpay uses data.paymentUrl - not data.url as returned by other providers. Update any redirect logic accordingly.

Field	Description
`data.paymentUrl`	Hosted payment page URL - redirect the user here
`data.transactionId`	Mozarto transaction ID - use for status queries and idempotency
`data.orderCode`	Worldpay order code in `MZRT_{transactionId}_{timestamp}` format
`data.amount`	Transaction amount as a number
`data.transaction_status`	Initial status - always `"Pending"` on creation

Webhook

Mozarto calls your webhookUrl when the transaction is processed. See Webhook Setup for the shared field reference.

Error codes

Worldpay EU transport failures are mapped to normalized Mozarto errorCode values. Use errorCode for programmatic handling rather than parsing raw XML error strings.

Mozarto `errorCode`	PSP raw signal	When
`PSP_NOT_CONFIGURED`	Missing credentials in Mozarto back office	`xmlUsername`, `xmlPassword`, or `merchantCode` not set for this brand
`INVALID_PSP_CREDENTIALS`	HTTP 401 / 403, or body contains `"Unauthorized"`, `"Invalid credentials"`, or `"authentication"`	XML credentials are wrong or expired
`PSP_TIMEOUT`	HTTP 408, or response body contains `"timeout"`	Worldpay did not respond in time - safe to retry
`PSP_UNAVAILABLE`	HTTP 5xx	Worldpay service error - safe to retry with backoff
`PSP_RATE_LIMITED`	HTTP 429	Too many requests - retry after a delay
`UNKNOWN_PSP_ERROR`	Any other HTTP error or XML validation failure	Fallback - check `data` for the raw Worldpay response and contact support if it persists

XML validation errors: Worldpay returns XML error responses for malformed requests (e.g. missing paymentMethodMask, invalid order structure). These produce UNKNOWN_PSP_ERROR unless the HTTP status code maps to a more specific code.

For the full list of errorCode values and retryability guidance, see Errors.

Configuration (Mozarto back office)#

Pay-In#

Request body#

Address fields#

Card fields (direct mode only)#

FraudSight fields (optional)#

Example request (HPP mode)#

Response#

Webhook#

Error codes#