.png)
Worldpay Integration Guide
Connect Worldpay payment and transaction APIs with enterprise applications using OAuth 2.0, selected webhook notifications, and Martini workflows.
Worldpay integration options at a glance
Worldpay’s current developer platform is primarily REST-based, with OAuth 2.0 and bearer tokens used by its Access APIs for payment and transaction operations. Selected products support webhook-style notifications for payment events, although coverage and verification requirements vary by product. Payment processing may include asynchronous status changes, while broad bulk APIs, general file interfaces, GraphQL, SOAP, and direct database access were not confirmed. Martini can consume Worldpay REST APIs, expose an endpoint for notifications, securely manage credentials, map payment data, persist identifiers and idempotency keys, and run scheduled reconciliation workflows where event coverage is incomplete.
| Integration point | Supported by Worldpay? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | Create and authorize payments, retrieve payment status, issue refunds, and access enabled account or transaction information. | Martini can consume Worldpay REST APIs from workflows, map request and response payloads, expose internal APIs, and apply payment and reconciliation rules. |
| Webhooks / outbound callbacks | Limited | Receive selected payment and transaction notifications; event coverage, registration, signatures, and retry behavior depend on the Worldpay product. | Martini can expose a REST endpoint, validate notifications, persist event identifiers, acknowledge promptly, and invoke asynchronous workflows. |
| Authentication | Yes | Current Worldpay Access APIs use OAuth 2.0 access tokens, bearer authentication, client credentials, merchant identifiers, and product-specific permissions. | Martini can manage OAuth token acquisition, secure client credentials in secrets, separate environments, and attach bearer tokens to API requests. |
| Bulk / asynchronous processing | Limited | Payment flows may produce asynchronous status changes, but a general-purpose bulk or batch REST API was not confirmed. | Martini can model asynchronous states, process follow-up notifications, and schedule status reconciliation without assuming bulk semantics. |
| Scheduled synchronization | Yes | Scheduled reconciliation can compare Worldpay transaction or settlement information with internal order, invoice, and ledger records where the relevant interface is available. | Martini scheduler-triggered workflows can retrieve pages, apply durable watermarks, map results, and identify unmatched or partially settled transactions. |
| File and settlement reporting | Limited | Product-specific settlement or reporting files may be available through merchant arrangements, but general file import/export APIs were not confirmed. | Martini can process an officially supported file or reporting interface if supplied for the target account, without assuming it is part of the standard REST API. |
| GraphQL APIs | Not confirmed | No official Worldpay GraphQL API documentation was confirmed. | Martini supports GraphQL consumption generally, but this Worldpay mechanism should not be assumed without product documentation. |
| SOAP APIs | Not confirmed | Older XML interfaces may exist, but SOAP support for the current Worldpay platform was not confirmed. | Martini supports SOAP consumption generally, but the integration should use the documented Worldpay REST contract unless a SOAP service contract is verified. |
How Worldpay exposes data and business events
Worldpay REST APIs
Worldpay’s current Access platform is primarily REST-based. The APIs support payment and related transaction operations, including payment status retrieval and refunds where enabled for the merchant, product, and region.
Martini implementation pattern
Martini implementation pattern: a workflow obtains or reuses an OAuth 2.0 bearer token, calls the appropriate Worldpay resource, validates the response, maps provider fields to an internal model, and applies business and error-handling rules.
Implementation sequence
Worldpay webhooks
Worldpay supports webhook-style notifications for selected payment and transaction events. Coverage, payloads, registration, retry behavior, and notification verification depend on the selected product.
Martini implementation pattern
Martini implementation pattern: a Martini API receives the notification, validates the required signature or authorization data, stores the event identifier, acknowledges promptly, and starts a workflow that retrieves authoritative Worldpay state when the notification is incomplete or out of order.
Implementation sequence
Worldpay asynchronous status processing
Worldpay payment flows may produce asynchronous status changes, although broad general-purpose bulk or batch API support was not confirmed. Integrations should not treat every initial response as final.
Martini implementation pattern
Martini implementation pattern: workflows persist the initial state, consume supported notifications when available, retrieve current payment status, and schedule bounded reconciliation for transactions that remain unresolved.
Implementation sequence
Worldpay reconciliation APIs
Worldpay transaction or settlement information may be available through APIs or product-specific reporting arrangements. The available interface must be confirmed for the merchant account and product.
Martini implementation pattern
Martini implementation pattern: a scheduled workflow retrieves the documented data set, follows its pagination model, maps transaction and settlement references, compares internal totals, and records unmatched or partially settled items.
Implementation sequence
Common Worldpay integration patterns
Pattern 1: Authorize commerce payments through Worldpay
When to use this pattern
Use this pattern when an order or commerce application needs Martini to mediate payment authorization and return a controlled result. It centralizes amount and currency validation, token handling, idempotency, and downstream status updates.
Integration direction
Example Mapping
| Worldpay Field | Canonical Field | Target Field |
|---|---|---|
| orderReference | orderId | merchantOrderReference |
| amount | amountMinorUnits | paymentAmount |
| currency | currencyCode | currency |
| paymentMethodToken | tokenizedInstrument | paymentInstrument |
Martini implementation pattern
A Martini API receives the payment request, validates the order and financial values, obtains an OAuth token, calls Worldpay, and maps the response to the commerce application. The workflow stores the provider reference and uses an idempotency key before retrying any uncertain request.
Martini capabilities used
- APIs
- workflows
- OAuth 2.0 authentication
- data mapping
- business rules
- error handling
Pattern 2: Synchronize Worldpay payment events
When to use this pattern
Use this pattern when selected Worldpay notifications should update orders, invoices, customer records, or operational cases. It is appropriate where event delivery is useful but cannot be treated as the sole source of financial truth.
Integration direction
Example Mapping
| Worldpay Field | Canonical Field | Target Field |
|---|---|---|
| eventId | providerEventId | externalEventId |
| paymentId | paymentReference | paymentReference |
| status | paymentStatus | Payment_Status__c |
| eventTimestamp | statusChangedAt | Status_Changed_At__c |
Martini implementation pattern
Martini receives and verifies the notification, checks the event store for duplicates, updates an internal payment record, and retrieves the current Worldpay resource when necessary. Conditional routing sends the normalized result to the target system and isolates out-of-order or conflicting transitions.
Martini capabilities used
- REST APIs
- workflow triggers
- API consumption
- data mapping
- conditional routing
- idempotency
- error handling
Pattern 3: Orchestrate refunds from customer operations
When to use this pattern
Use this pattern when an approved refund request originates in a CRM, order platform, or ERP and must be executed against the original Worldpay payment.
Integration direction
Example Mapping
| Worldpay Field | Canonical Field | Target Field |
|---|---|---|
| originalPaymentId | paymentReference | paymentReference |
| refundAmount | refundAmountMinorUnits | amount |
| refundReason | reasonCode | reason |
| caseId | refundRequestId | merchantReference |
Martini implementation pattern
The Martini workflow verifies refund eligibility, amount limits, currency, and the original payment reference before calling Worldpay. It records the refund result, prevents duplicate submissions using an internal key, and routes failures or ambiguous responses for controlled retry or review.
Martini capabilities used
- workflows
- API consumption
- validation
- business rules
- data mapping
- retry handling
Pattern 4: Reconcile Worldpay settlements with finance
When to use this pattern
Use this pattern for scheduled comparison of Worldpay transaction or settlement information with ERP, accounting, or ledger records. It helps identify missing, failed, unmatched, and partially settled transactions.
Integration direction
Example Mapping
| Worldpay Field | Canonical Field | Target Field |
|---|---|---|
| transactionReference | providerTransactionId | externalId |
| settlementAmount | settledAmountMinorUnits | amount |
| currency | currencyCode | currency |
| settlementDate | settledAt | settlementDate |
Martini implementation pattern
A scheduled Martini workflow retrieves the approved Worldpay reporting data, follows pagination, maps records, and compares provider references and financial values with NetSuite. Durable watermarks, duplicate checks, bounded retries, and exception queues support repeatable reconciliation.
Martini capabilities used
- scheduled workflows
- API consumption
- pagination handling
- data mapping
- SQL persistence
- business rules
- monitoring
Applications commonly integrated with Worldpay
Worldpay can be connected to commerce, finance, customer operations, and subscription platforms through their APIs and Worldpay’s documented payment interfaces. The exact implementation depends on the Worldpay product, region, merchant account, and target application configuration.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| Shopify | Synchronize payment authorization, refund, and order-payment status for online commerce. | Shopify → Martini → Worldpay | Martini exposes or consumes the required application API, validates the order and amount, submits the Worldpay payment request, and routes status or refund results back to Shopify with idempotency protection. |
| Salesforce Commerce Cloud | Process digital commerce payments and synchronize payment outcomes with order processing. | Salesforce Commerce Cloud → Martini → Worldpay | A Martini workflow receives the commerce payment request, obtains an OAuth 2.0 token, maps order and currency values to Worldpay, and returns or asynchronously updates the payment result. |
| SAP S/4HANA | Post payment, refund, settlement, and reconciliation information to finance processes. | Worldpay → Martini → SAP S/4HANA | Scheduled or event-driven workflows map Worldpay payment and settlement references to SAP finance structures, apply reconciliation rules, and retain unmatched items for review. |
| Oracle NetSuite | Reconcile Worldpay settlements and transactions with invoices, cash receipts, and refunds. | Worldpay → Martini → Oracle NetSuite | Martini retrieves available Worldpay transaction or settlement data, maps it to NetSuite records, compares amounts and references, and retries transient API failures without duplicating financial postings. |
| Salesforce | Associate payment status, refunds, and disputes with customer or case records. | Worldpay → Martini → Salesforce | Worldpay notifications trigger a Martini workflow that validates and deduplicates the event, retrieves authoritative payment state when needed, and updates Salesforce; approved refund requests can flow in the reverse direction. |
| ServiceNow | Create operational cases for failed payments, reconciliation exceptions, or dispute events. | Worldpay → Martini → ServiceNow | Martini classifies Worldpay events and API errors, applies business thresholds, and creates or updates ServiceNow records while storing event identifiers to prevent duplicate cases. |
| Microsoft Dynamics 365 | Synchronize orders, invoices, payment status, refunds, and financial reconciliation data. | Microsoft Dynamics 365 → Martini → Worldpay | Martini orchestrates payment and refund requests from Dynamics 365 and scheduled Worldpay reconciliation into Dynamics finance objects, with explicit amount, currency, and reference validation. |
| Zuora | Coordinate subscription billing payment results, failed-payment handling, and refunds. | Zuora → Martini → Worldpay | A Martini workflow translates Zuora billing actions into Worldpay payment or refund requests, then routes asynchronous outcomes back to the subscription lifecycle with bounded retries and idempotency. |
How to build a Worldpay integration in Martini
Objective
Establish the Worldpay product, region, environments, permissions, and authentication configuration before building payment workflows.
Instructions in Martini
- Confirm the Worldpay Access or other current API product and merchant arrangement
- Store client credentials and environment-specific configuration in Martini secrets
- Configure OAuth 2.0 token acquisition and bearer authentication
- Keep test and production credentials separate
Objective
Select the correct entry point for synchronous payment actions, selected Worldpay notifications, and scheduled reconciliation.
Instructions in Martini
- Expose a Martini REST API for application payment or refund requests
- Expose a protected Martini endpoint for supported Worldpay notifications
- Use a scheduler for status checks and reconciliation where event coverage is incomplete
- Define idempotency and correlation identifiers for every trigger
Objective
Call Worldpay APIs and obtain authoritative payment or settlement state rather than relying on incomplete notifications.
Instructions in Martini
- Call the documented Worldpay REST resource for the selected operation
- Retrieve current payment state after relevant notifications or uncertain responses
- Follow the documented pagination model for list or reporting resources
- Persist provider references, event identifiers, and synchronization timestamps
Objective
Coordinate validation, API calls, status transitions, downstream updates, and exception paths in maintainable Martini workflows.
Instructions in Martini
- Route payment, refund, notification, and reconciliation flows separately where appropriate
- Apply conditional logic for pending, successful, failed, disputed, and conflicting states
- Use asynchronous processing after promptly acknowledging webhook notifications
- Persist retry state and operational correlation information
Objective
Translate Worldpay payloads into canonical payment, order, finance, and case models while preserving financial precision.
Instructions in Martini
- Map provider fields to internal payment and transaction structures
- Represent amounts in the required minor units and preserve ISO currency codes
- Validate required identifiers, amounts, currencies, and status values
- Avoid logging raw card data, secrets, tokens, or sensitive notification credentials
Objective
Control authorization, refund eligibility, reconciliation matching, and duplicate processing before writing results.
Instructions in Martini
- Enforce refund limits and association with the original payment
- Check idempotency keys before retrying payment or refund operations
- Classify unmatched and partially settled transactions for review
- Handle out-of-order events and avoid invalid payment state transitions
Common Worldpay data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Payments | Authorize, process, retrieve, and track payment transactions. | Commerce platforms, order management, ERP, CRM, and reconciliation databases | Martini maps payment requests and responses, stores provider references and status, validates amount and currency, and applies idempotent retry logic. |
| Payment instruments | Represent card or other payment details, including tokenized instruments where supported. | Commerce platforms, payment flows, and customer applications | Martini should prefer tokenized or hosted collection patterns and avoid logging or passing raw sensitive payment data unless explicitly required and controlled. |
| Payment sessions | Represent checkout or payment-flow sessions used to collect and process payment details. | Commerce platforms, checkout applications, and customer-facing APIs | Martini can orchestrate session-related requests and map session identifiers to internal orders, subject to the selected Worldpay product. |
| Refunds | Perform full or partial reversals of previously processed payments. | Order management, CRM, ERP, accounting, and customer service systems | Martini verifies the original payment reference and refund limits, submits the request, records the refund reference, and protects retries with idempotency. |
| Settlements | Represent financial settlement information associated with processed transactions. | SAP S/4HANA, Oracle NetSuite, Microsoft Dynamics 365, ledgers, and reconciliation databases | Martini retrieves available settlement information, maps amounts and references, applies reconciliation rules, and routes exceptions for review. |
| Disputes | Represent chargebacks or dispute cases associated with payments. | CRM, customer service, ERP, case management, and reporting systems | Martini can process supported notifications or API data, associate disputes with payment references, and update downstream case or finance records. |
Authentication and security considerations
OAuth 2.0 and credentials
Current Worldpay Access APIs use OAuth 2.0 access tokens and bearer authentication. Store client identifiers, client secrets, merchant identifiers, and environment-specific settings in Martini secrets rather than workflow payloads or source code.
Payment data protection
Prefer Worldpay-hosted or tokenized payment collection where applicable. Avoid passing or logging raw card data, security codes, full payment tokens, OAuth secrets, or sensitive webhook credentials.
Webhook verification
Validate the signature, authorization header, or other notification verification mechanism required by the selected Worldpay product before changing payment state. Treat every notification as untrusted input.
Operational considerations for Worldpay integrations
Idempotency and state
Persist internal idempotency keys, Worldpay payment and refund references, event identifiers, amounts, currencies, and current status. Do not blindly retry uncertain payment creation requests.
Retries and rate limits
Use bounded retries and exponential backoff for transient failures and rate-limit responses. Refresh expired tokens without exposing token values in logs.
Pagination and reconciliation
Follow the pagination model documented by the applicable Worldpay product. Use durable watermarks where supported and schedule reconciliation because webhook coverage may be incomplete.
Schema and testing
Keep mappings explicit, validate required fields, tolerate documented optional fields, and test payment, refund, asynchronous, duplicate, out-of-order, and failure scenarios in the appropriate Worldpay environment.
Why use Martini instead of scripts or point-to-point integrations?
Centralized orchestration
Martini provides a maintainable workflow layer between Worldpay and commerce, finance, customer, and operational systems instead of duplicating payment logic across point-to-point scripts.
Consistent controls
OAuth configuration, secret handling, validation, idempotency, retries, status transitions, and reconciliation rules can be implemented consistently across payment and refund workflows.
Reusable integration assets
Martini can consume Worldpay REST APIs, expose controlled APIs for internal applications, normalize payment data, and reuse workflow components as downstream systems change.
Operational visibility
Workflow error handling, persistence, monitoring, and controlled retry paths make asynchronous payment events and reconciliation exceptions easier to operate than isolated scripts.
Frequently asked questions
Worldpay’s current integration model is primarily REST-based, using OAuth 2.0 and bearer tokens for payment and related transaction operations. Selected products also provide webhook-style notifications for payment events. Enterprise systems can use these APIs and notifications for payment authorization, refunds, status synchronization, and reconciliation, subject to the merchant’s product, region, and account configuration.
Yes. Martini can integrate with Worldpay by consuming its documented REST APIs, obtaining OAuth 2.0 tokens, receiving supported webhook notifications through a Martini API, mapping payment data, and orchestrating workflows for authorization, refunds, status updates, and reconciliation.
No. A dedicated Worldpay connector is not required. Martini can use Worldpay’s confirmed native integration mechanisms, including REST APIs, OAuth 2.0 authentication, and selected webhook-style notifications.
Lonti does not charge an additional per-connector or per-vendor fee to integrate Worldpay. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Worldpay, cloud infrastructure providers, or other third-party systems based on subscriptions, transaction volume, and deployment model.
Use the current Worldpay REST API product documented for the merchant’s region and payment use case, together with OAuth 2.0 authentication. Selected products may use webhook-style notifications. GraphQL and SOAP were not confirmed for the current platform, and legacy XML interfaces should not be selected without verifying their service contract and support status.
Yes, selected Worldpay products support webhook-style notifications for selected payment and transaction events. Coverage is not universal. Martini should validate the product-specific security mechanism, deduplicate notifications, acknowledge promptly, and retrieve authoritative payment state when the notification is incomplete or events arrive out of order.
Martini maps Worldpay payment, refund, settlement, and dispute references to internal order, invoice, customer, or finance models. Workflows can process supported events in near real time and use scheduled status or reconciliation workflows when notifications are unavailable or incomplete. Explicit mappings, watermarks, and idempotency keys support repeatable synchronization.
Martini can classify authentication, validation, rate-limit, transient, and conflicting-state errors, then apply bounded retries with backoff. Payment and refund requests require idempotency protection and an uncertainty check before retrying, while webhook event identifiers should be persisted to prevent duplicate processing.
Related Martini documentation
API Integration
Workflows
Connect Worldpay with your enterprise systems
Use Martini to build secure, observable Worldpay payment, notification, refund, and reconciliation workflows around the APIs and integration methods supported by your merchant account.