mcp-worldpay

@codespar/mcp-worldpay

MCP server for Access Worldpay — global enterprise payment processor.

Worldpay is one of the largest card acquirers in the world and a default rail for EU/UK/US enterprise merchants. This server targets the modern Access Worldpay REST surface, not the legacy FIS/WPG XML gateway.

Status: 0.1.0-alpha.1 — Access Worldpay uses HATEOAS action links (linkData) for lifecycle operations. Exact endpoint paths and media-type versions have been validated against the public docs (v7 payments, v4 verifications, v3 tokens, v1 fraudsight/disputes) but are moving targets. See Stability below.

Tools (22)

Tool	Purpose
verify_account	Run an AVS/CVC account verification on a card without charging it.
authorize_payment	Authorize a card payment.
capture_payment	Capture (settle) an authorized payment.
cancel_payment	Void an authorization that has not yet been captured.
refund_payment	Refund a captured payment.
reverse_payment	Reverse a payment atomically — voids if not yet captured, refunds if already captured.
get_payment	Retrieve the detail of a payment event by its Worldpay eventId.
create_token	Tokenize a card for reuse (card-on-file).
get_token	Retrieve a stored card token's metadata (bin, scheme, last4, cardHolderName, expiryDate, etc.).
update_token	Update metadata on a stored card token (e.g.
delete_token	Delete a stored card token.
query_payment	Look up a payment by the merchant-side transactionReference you assigned on authorize_payment.
list_payment_events	List recent payment events for the configured merchant entity.
lookup_3ds	Step 1 of 3DS2 — submit device-data-collection (DDC) output to Worldpay to determine whether a challenge is...
authenticate_3ds	Step 2 of 3DS2 — authenticate the cardholder.
challenge_3ds	Step 3 of 3DS2 — post the CReq back after the issuer challenge window closes, to retrieve the final authent...
get_dispute	Retrieve a dispute's current state, evidence requirements, deadlines, and HATEOAS action links.
defend_dispute	Open a defence on a dispute — signals intent to defend before submit_dispute_evidence.
get_reconciliation_batch	Retrieve a reconciliation batch (daily settlement file equivalent) — lists all settled transactions, fees,...
accept_dispute	Accept a dispute (forfeit the chargeback).
submit_dispute_evidence	Submit evidence to defend a dispute.
fraud_screen	Run a standalone FraudSight assessment on a payment method (no authorization).

Install

npm install @codespar/mcp-worldpay@alpha

Environment

WORLDPAY_USERNAME="..."    # API username (Basic Auth)
WORLDPAY_PASSWORD="..."    # API password (Basic Auth)
WORLDPAY_ENTITY="..."      # Merchant entity id; injected as merchant.entity
WORLDPAY_ENV="sandbox"     # sandbox | production; default sandbox
WORLDPAY_API_VERSION="v7"  # Payments API version; default v7

Authentication

HTTP Basic auth with your Worldpay-issued credentials:

Authorization: Basic base64(username:password)

Each API family uses its own versioned media type. The server sets the correct Content-Type / Accept headers per call:

Family	Media type
payments	application/vnd.worldpay.payments-v7+json
verifications	application/vnd.worldpay.verifications.accounts-v4+json
tokens	application/vnd.worldpay.tokens-v3.hal+json
fraudsight	application/vnd.worldpay.fraudsight-v1.hal+json
disputes	application/vnd.worldpay.disputes-v1.hal+json

HATEOAS and linkData

Access Worldpay is HATEOAS-driven. After authorize_payment, the response contains _links such as payments:settle, payments:partialSettle, payments:cancel, payments:refund, payments:partialRefund, and payments:reverse. Each href ends in an opaque segment we call linkData, e.g.:

/payments/settlements/eyJrIjoiazNhYjYzMiJ9
                       ^^^^^^^^^^^^^^^^^^^ linkData

Extract that segment and pass it as linkData to capture_payment / cancel_payment / refund_payment / reverse_payment. When omitted, the server POSTs to the bare resource path; this only works for onboardings configured for transactionReference-addressable settlements.

Run

# stdio (default — for Claude Desktop, Cursor, etc.)
npx @codespar/mcp-worldpay

# HTTP (for server-to-server testing)
MCP_HTTP=true MCP_PORT=3000 npx @codespar/mcp-worldpay

Stability

• Published as 0.1.0-alpha.1 until we validate end-to-end against a real sandbox account.
• Global Payments acquired Worldpay in January 2026. Base URLs (try.access.worldpay.com / access.worldpay.com) remain valid as of this writing, but Global Payments has publicly signalled platform consolidation. Expect URL and media-type rebranding over the next 12–18 months. Pin the WORLDPAY_API_VERSION env var and watch the release notes.
• This server does not cover: Worldpay Total (US CNP-API legacy), the WPG/FIS XML gateway, Disputes Direct (separate from Access Disputes), or Worldpay for Platforms. Those are separate surfaces and would be separate packages.

Enterprise

Need governance, budget limits, and audit trails for agent payments? CodeSpar Enterprise adds policy engine, payment routing, and compliance templates on top of these MCP servers.

License

MIT