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)

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
`isWebhookSecured`	Adds `Authorization` header to outbound webhook calls
`hppLanguage`	Language for the HPP page (default: `"en"`)
`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"`)
`countryCode` *	string	ISO country code
`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"`)
`brandId`	string	Brand identifier
`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",
  "countryCode": "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.

The method field will be WORLDPAY_EU_PAYIN.

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 company
`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#