Worldpay

Adapter 0.2.0, documentation reviewed 2026-10-25. Overall status: limited.

Capabilities

Supported input

Notification delivery

• Repeated deliveries are recognized by eventId.
• Delivery order: not documented by the provider.
• Worldpay retries an event until it receives HTTP 200, for up to one week, but does not document whether a retried delivery keeps its eventId or in which order events arrive. Record processed eventIds, and also check the payment's current state (Payment Queries) before acting on an event.

Known limitations

• Account payouts webhooks (PaymentOutNotification) and Event Notifications (limited beta, format not documented) are not analyzed.
• WPG documents begin with <!DOCTYPE paymentService ...>. PandaPayLens rejects any DOCTYPE declaration, so a WPG reply or order notification must be pasted without that line (also inside a raw HTTP message). One XML document is one record; several notifications are analyzed together when they are imported as separate inputs.
• WPG: replies with <error> (the 14 DTD codes are decoded; the error text is provider text and is shown scrubbed), orderStatus and orderStatusEvent payments (all 26 documented lastEvent values, including CAPTURE_FAILED, which appears only in an example) and <ok> acknowledgements of capture, cancel, refund and void requests are analyzed. Batch status, token, address check and other replies, reports and requests are recognized but not analyzed. CGI/Text notifications are not supported.
• WPG ISO8583ReturnCode: only the seven standard codes (0, 2, 5, 6, 34, 973, 975) are decoded. Extended response codes and codes from other acquirers keep the code and Worldpay's description, with an unknown category, because the WPG pages do not say that they follow the Access Worldpay refusal codes. IssuerResponseCode, schemeResponse, FraudSight, riskScore and 3DS results are not read; CVC and AVS result descriptions are shown as attributes.
• WPG amounts are read from <amount value currencyCode exponent> and converted to minor units of the currency (left out when that would need rounding). Capture, refund, settlement and dispute events use the journal (accountTx) amount, which is the amount moved by that step; when the journal has no amount or amounts that differ, no amount is set and the order amount is shown as an attribute. WPG dates (bookingDate) carry no time zone, so WPG events have no event time and follow the input order.
• WPG events are linked by orderCode, which Worldpay requires to be unique per order, and are never linked to Access Worldpay records. merchantCode, card numbers, card holder names, addresses, email addresses and authorisation ids are never read. WPG order notifications carry no notification id, so repeated deliveries are recognized only when their content is identical; authenticity (client certificate, reverse DNS) cannot be verified from pasted data.
• cnpAPI: only cnpOnlineResponse in the namespace http://www.vantivcnp.com/schema is read (the older Litle schema is not). The 379 payment transaction response codes of the public response code page are decoded with their message and Worldpay's response type (Approved, Soft Decline, Hard Decline, Referral and others); retry guidance follows that type, and only codes whose message names the reason (for example insufficient funds) get a category. Responses with the response attribute 1 to 5 are decoded as rejected requests. Batch files, requests, AVS, card validation, fraud and 3DS result codes and other transaction responses are not analyzed.
• cnpAPI responseTime is used as event time only when it carries a time zone; otherwise it is shown as sent. cnpAPI amounts are not read (approvedAmount is shown as sent, without a currency). Responses are linked by cnpTxnId and by the merchant's orderId; a capture, credit or void response carries a new cnpTxnId and no orderId, so it joins its authorization only through another record.
• No merchant sectors are listed: Worldpay publishes no list of accepted sectors. Its sector pages (financial services MCC 6012/6051, crypto ramp providers, airline, lodging and purchasing Level 2/3 data) and the gambling limit footnote are integration requirements, not eligibility statements.
• refusalCode carries the Worldpay refusal code by default, but the raw scheme or acquirer code when the merchant is configured for raw codes. Card Payments v7 then adds gatewayRefusalCode with the Worldpay code, and Card Payments v6 used separate code and rawCode fields. The Payments API has no such field, so a lone refusalCode is read as a Worldpay code, with possible confidence when the raw tables give it a different meaning (for example 55, 63 or Amex 106). Zero-padded and alphanumeric codes (05, 1A, N7) are read as raw codes.
• The scheme of a raw code is not taken from the payload, so a raw code with different meanings per scheme (for example 51 is a generic decline for Discover) is decoded with possible confidence and all scheme readings are shown. Worldpay notes that raw codes from third-party acquirers may not be listed at all.
• The refused webhook carries no refusal code or description. The reason is only in the synchronous response, in Payment Queries (events[].code) or, for refunds, in refundFailed refund.refusal.
• Webhook eventTimestamp values carry no time zone, so they are shown as sent and are not used as event time; webhook events follow the input order. Synchronous responses carry no timestamp. Payment Queries timestamps (ISO 8601 with Z) and tokenCreated createdAt are used as event time.
• eventId is used as the delivery key. Worldpay retries unacknowledged events for up to one week, but whether a retry keeps the same eventId and the delivery order are not documented.
• Webhook amounts are documented as whole numbers with an exponent of 2. They are used as minor units only for currencies whose ISO 4217 exponent is 2; for other currencies the value is shown as supplied. Response amounts (amounts.requested, amounts.totalAuthorized) are shown as attributes and Payment Queries amounts are not read.
• Payments are linked by paymentId, by transactionReference (documented as identifying a payment throughout its lifecycle) and by commandId. sentForAuthorization, error, settled, cancelled, expired, refunded and the payout and chargeback events carry no paymentId, and Card Payments v7 responses carry no transactionReference, so a v7 response joins those events only through another record that carries both keys. A transactionReference reused by the merchant for several payments would join them. orderReference may be reused and is never used for linking.
• An outcome of sentForSettlement on an authorization request (automatic settlement) is shown as a capture request; the implied authorization is not shown as a separate event. Settle, cancel, refund and reversal requests answer HTTP 202, which confirms receipt only.
• Card chargebacks are limited to informationRequested in Access webhooks (chargedBack is Klarna only). Card Payments v7 reversals are processed as a cancel or a refund and have no webhook of their own.
• settled, settlementFailed, refunded and informationRequested are sent only in certain use cases, and event availability differs by business type, so a missing event does not mean the step did not happen.
• Payment Queries is read for one payment (GET /paymentQueries/payments/{paymentId}); list responses are not analyzed. The Card Payments events query is deprecated and can lag up to 15 minutes.
• APM responses are read only through the shared outcome field; APM lastEvent values (dispute and other states) are not analyzed.
• The Event-Signature header and the mutual TLS check cannot be verified from pasted data, so a pasted webhook is never treated as authentic. Only the presence of the header is reported.
• Refusal codes 17, 29 and 38 appear only on Worldpay's testing pages and are decoded with possible confidence. Codes 63, 85, 605 and other codes with contradicting documented texts are decoded as unknown with manual review.
• Error responses without a JSON errorName body (for example a bare HTTP status or a plain-text body) are not recognized.
• Category and retry guidance per code are PandaPayLens suggestions. Worldpay's own retry signals are the refusal advice codes (Mastercard and Maestro only), the Visa categories of raw codes, and the guidance that 4xx requests can be retried once fixed while 5xx errors are server-side, most commonly timeouts.

Examples

• Worldpay: card payment webhooks: Access Worldpay events from authorization to settlement in one timeline.
• Worldpay: refusal with a raw scheme code: A Card Payments v7 refusal where the raw scheme code and the Worldpay code are shown side by side.

Provider documentation

• Refusal codes and refusal advice codes
• Raw scheme response codes
• Worldpay error responses
• API principles
• Payments API
• Payments API reference (2024-06-01)
• Card Payments API reference (v7)
• Card Payments v7 migration guide
• Manage card payments (settle, cancel, refund, reverse)
• Online refunds
• Payment Queries API reference (v1)
• Events (webhooks)
• Events API reference (v1)
• Event signature
• Hosted payment pages webhooks
• Payments API testing values
• WPG (Worldwide Payment Gateway) XML API
• WPG error codes
• WPG order notifications and payment statuses
• WPG payment process
• WPG authorisation response codes (ISO8583ReturnCode)
• WPG payment requests and replies
• cnpAPI introduction
• cnpAPI payment transaction response codes
• cnpAPI XML validation messages
• cnpAPI additional response header error messages

PandaPayLens is not affiliated with Worldpay. Pasted notifications are never treated as verified: PandaPayLens does not check webhook signatures.