EVO Payment API Portal

简体中文

ENG

简体中文

ENG

MCP Server Preview ​

EVO Payment MCP server 定义了一套工具，AI agents 可以使用这些工具与EVO支付API进行交互。

使用此 SDK 将 EVO Payment 集成到您的智能体工作流中。由于智能体行为具有不确定性，请在测试环境中使用此 SDK 并运行评估以评估您应用程序的效果。

前置要求 ​

MCP 客户端 ​

  1. 确保您有可用的 mcp 客户端，详细的客户端列表可以参考网页 https://modelcontextprotocol.io/clients
  2. 确保您已经安装了 uv, 参考文档 https://docs.astral.sh/uv/getting-started/installation/

环境变量 ​

在使用 LinkPay MCP 之前，您需要配置以下环境变量：

环境变量说明必填
EVOCLOUD_BASE_URLEvoCloud API 基础 URL(默认使用 uat 服务)是
EVOCLOUD_SIDEvoCloud 商户 ID是
EVOCLOUD_SIGN_KEYEvoCloud 签名密钥是
EVOCLOUD_WEBHOOK_URL支付回调 URL否

MCP 服务器配置 ​

在您的 MCP 客户端配置文件中添加以下配置：

json
{
  "mcpServers": {
    "linkpay": {
      "command": "uvx",
      "args": ["--from", "evocloud_agent_toolkit", "linkpaymcp", "stdio"],
      "env": {
        "EVOCLOUD_BASE_URL": "https://counter-uat.everonet.com",
        "EVOCLOUD_SID": "您的商户ID",
        "EVOCLOUD_SIGN_KEY": "您的签名密钥",
        "EVOCLOUD_WEBHOOK_URL": "https://example.com/webhook"
      }
    }
  }
}

功能概览 ​

LinkPay MCP 提供以下核心功能：

1. 生成商户订单 ID ​

  • 功能名称: generate_merchant_order_id
  • 描述: 生成唯一的商户订单 ID
  • 参数:
    • prefix (可选): 订单号前缀，默认为 "LINKPAY"

2. 创建支付订单 ​

  • 功能名称: create_linkpay_order
  • 描述: 创建 LinkPay 支付订单
  • 参数:
    • merchant_order_id (必填): 商户订单 ID
    • currency (必填): 货币代码，如 "USD", "CNY"
    • amount (必填): 支付金额
    • merchant_order_time (可选): 订单时间
    • goods_name (可选): 商品名称
    • goods_description (可选): 商品描述
    • trade_type (可选): 交易类型
    • return_url (可选): 支付完成后的返回地址
    • webhook_url (可选): 支付状态回调地址
    • enabled_payment_methods (可选): 支持的支付方式列表
    • valid_time (可选): 订单有效时间（分钟）

3. 查询订单状态 ​

  • 功能名称: query_linkpay_order
  • 描述: 查询 LinkPay 订单状态
  • 参数:
    • merchant_order_id (必填): 商户订单 ID

4. 创建退款 ​

  • 功能名称: create_linkpay_refund
  • 描述: 创建 LinkPay 退款请求
  • 参数:
    • original_merchant_order_id (必填): 原始订单 ID
    • merchant_trans_id (必填): 退款交易 ID
    • currency (必填): 货币代码
    • refund_amount (必填): 退款金额
    • merchant_trans_time (可选): 退款时间
    • reason (可选): 退款原因
    • description (可选): 退款描述

5. 查询退款状态 ​

  • 功能名称: query_linkpay_refund
  • 描述: 查询 LinkPay 退款状态
  • 参数:
    • merchant_trans_id (必填): 退款交易 ID

使用示例 ​

1. Cursor 配置 LinkPay MCP 服务 ​

配置如下服务:

保存好，在 mcp 工具列表里查看 LinkPay 服务是否正常

2. 创建 LinkPay 交易订单 ​

安全注意事项 ​

  1. 密钥安全: 确保 EVOCLOUD_SIGN_KEY 等敏感信息安全存储，不要硬编码在代码中
  2. HTTPS: 生产环境必须使用 HTTPS 协议
  3. 签名验证: 回调 webhook 应验证请求签名的有效性
  4. 订单幂等: 确保相同的 merchant_order_id 不会重复创建订单
  5. 金额验证: 在处理支付前应验证金额的合理性