mcp-worldpay

@codespar/mcp-worldpay

用于 Access Worldpay 的 MCP 服务——全球企业级支付处理商。

Worldpay 是全球最大的收单机构之一，也是欧盟、英国和美国企业商户默认使用的支付渠道。此服务针对现代 Access Worldpay REST 接口，而非旧版 FIS/WPG XML 网关。

状态：0.1.0-alpha.1 — Access Worldpay 使用 HATEOAS 操作链接（linkData）执行生命周期操作。具体端点路径和媒体类型版本已根据公开文档（v7 支付、v4 验证、v3 令牌、v1 FraudSight/争议）验证，但仍可能变动。请参阅下方的稳定性。

工具（22 个）

工具	用途
verify_account	对银行卡执行 AVS/CVC 账户验证，不会扣款。
authorize_payment	授权银行卡支付。
capture_payment	捕获（结算）已授权的支付。
cancel_payment	撤销尚未捕获的支付授权。
refund_payment	退还已捕获的支付。
reverse_payment	原子性地冲正支付——尚未捕获时撤销授权，已捕获时退款。
get_payment	根据 Worldpay 事件 ID 获取支付事件详情。
create_token	将银行卡令牌化以供重复使用（存档卡）。
get_token	获取已存储银行卡令牌的元数据（bin、scheme、last4、cardHolderName、expiryDate 等）。
update_token	更新已存储银行卡令牌的元数据（例如
delete_token	删除已存储的银行卡令牌。
query_payment	根据你在 authorize_payment 中指定的商户端 transactionReference 查询支付。
list_payment_events	列出已配置商户实体的近期支付事件。
lookup_3ds	3DS2 第 1 步——将设备数据收集（DDC）结果提交给 Worldpay，以确定是否需要质...
authenticate_3ds	3DS2 第 2 步——验证持卡人身份。
challenge_3ds	3DS2 第 3 步——在发卡机构的质询窗口关闭后回传 CReq，以获取最终验证...
get_dispute	获取争议的当前状态、证据要求、截止日期和 HATEOAS 操作链接。
defend_dispute	对争议发起抗辩——在调用 submit_dispute_evidence 前表明抗辩意向。
get_reconciliation_batch	获取对账批次（相当于每日结算文件）——列出所有已结算交易、费用等...
accept_dispute	接受争议（放弃拒付抗辩）。
submit_dispute_evidence	提交证据以抗辩争议。
fraud_screen	对支付方式执行独立的 FraudSight 评估（不授权支付）。

安装

npm install @codespar/mcp-worldpay@alpha

环境

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

身份验证

使用 Worldpay 签发的凭据进行 HTTP Basic 身份验证：

Authorization: Basic base64(username:password)

每个 API 系列都使用各自带版本号的媒体类型。服务会为每次调用设置正确的 Content-Type / Accept 标头：

系列	媒体类型
支付	application/vnd.worldpay.payments-v7+json
验证	application/vnd.worldpay.verifications.accounts-v4+json
令牌	application/vnd.worldpay.tokens-v3.hal+json
FraudSight	application/vnd.worldpay.fraudsight-v1.hal+json
争议	application/vnd.worldpay.disputes-v1.hal+json

HATEOAS 和 linkData

Access Worldpay 由 HATEOAS 驱动。调用 authorize_payment 后，响应中会包含 _links，例如 payments:settle、payments:partialSettle、payments:cancel、payments:refund、payments:partialRefund 和 payments:reverse。每个 href 都以一个不透明片段结尾，我们称之为 linkData，例如：

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

提取该片段，并将其作为 linkData 传给 capture_payment / cancel_payment / refund_payment / reverse_payment。如果省略，服务会向基础资源路径发送 POST 请求；这仅适用于配置为可通过 transactionReference 定位结算的商户。

运行

# 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

稳定性

• 在使用真实沙盒账户完成端到端验证之前，版本将保持为 0.1.0-alpha.1。
• Global Payments 于 2026 年 1 月收购了 Worldpay。 截至本文撰写时，基础 URL（try.access.worldpay.com / access.worldpay.com）仍然有效，但 Global Payments 已公开表示将整合平台。预计未来 12–18 个月内，URL 和媒体类型将重新命名。请固定 WORLDPAY_API_VERSION 环境变量，并关注发行说明。
• 此服务不涵盖：Worldpay Total（美国 CNP-API 旧版）、WPG/FIS XML 网关、Disputes Direct（与 Access Disputes 相互独立）或 Worldpay for Platforms。这些属于独立的产品领域，需要单独打包。

企业版

需要为 Agent 支付设置治理、预算限额和审计跟踪？CodeSpar Enterprise 在这些 MCP 服务的基础上增加了策略引擎、支付路由和合规模板。

许可证

MIT