mcp-transbank

Name: mcp-transbank
Author: codespar

本地服务

github.com/codespar金融数据2754 周前更新

代码仓库

关于 mcp-transbank

mcp-transbank 是智利主要银行卡收单机构 Transbank 的 MCP 服务，覆盖 Webpay Plus 一次性跳转支付、Webpay Mall 多商户拆分支付以及 OneClick Mall 卡片签约与扣款。它面向在智利开展业务、需要通过 Agent 处理卡支付的场景。服务通过环境变量配置集成或生产环境。

主要功能

01Webpay Plus 交易的创建、提交、查询和退款
02Webpay Mall 按子商户代码拆分交易并分别处理
03OneClick Mall 卡片签约、解约及按商户代码扣款
04支持延迟扣款（capture）与交易状态查询
05通过环境变量切换集成环境与生产环境

适用场景

01为智利商户的网站或 Agent 创建 Webpay Plus 支付并处理回跳确认
02在多卖家平台中将一笔订单拆分给多个子商户结算
03为定期或免密支付场景管理已签约的 OneClick Mall 卡片

MCP 相关

该项目是 MCP 服务，向 MCP 客户端暴露 19 个工具，用于调用 Transbank Webpay Plus、Webpay Mall 与 OneClick Mall 接口。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "codespar-mcp-transbank": {
      "command": "npx",
      "args": [
        "-y",
        "@codespar/mcp-transbank"
      ],
      "env": {
        "TRANSBANK_COMMERCE_CODE": "<TRANSBANK_COMMERCE_CODE>",
        "TRANSBANK_API_KEY_SECRET": "<TRANSBANK_API_KEY_SECRET>",
        "TRANSBANK_ENV": "<TRANSBANK_ENV>"
      }
    }
  }
}

启动命令npx -y @codespar/mcp-transbank

需要配置的环境变量

TRANSBANK_COMMERCE_CODETransbank merchant commerce code (sent as Tbk-Api-Key-Id header)

TRANSBANK_API_KEY_SECRET密钥Transbank API secret key (sent as Tbk-Api-Key-Secret header)

TRANSBANK_ENVEnvironment: 'integration' (default, https://webpay3gint.transbank.cl) or 'production' (https://webpay3g.transbank.cl)

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@codespar/mcp-transbank0.2.0-alpha.3stdio

工具

收录的工具列表 · 更新于 2 周前

参数	类型	必填	说明
amount	number	是	以 CLP 计价的金额（整数，不含小数）
buy_order	string	是	商户侧订单 ID（最多 26 个字符）
return_url	string	是	Transbank 在付款后将用户重定向回的 URL
session_id	string	是	商户侧会话 ID（最多 61 个字符）

详细介绍

@codespar/mcp-transbank

适用于 Transbank 的 MCP 服务——智利最大的银行卡收单机构。

Transbank 实际上是智利商业领域的默认选择（源自国有机构，现由智利银行组成的财团持有）。如果要宣称“CodeSpar 覆盖拉美”，且包括智利，就必须提供此服务。

涵盖两种产品：

Webpay Plus — 一次性重定向支付（buy_order + amount，用户会被重定向到 Webpay 完成支付）。
Webpay OneClick Mall — 令牌化的周期性支付／卡片留存支付，可在多个商户代码之间拆分（“商城”模式）。

工具（19 个）

工具	用途
`webpay_create_transaction`	创建 Webpay Plus 交易。
`webpay_commit_transaction`	用户从 Webpay 流程返回后，提交 Webpay Plus 交易。
`webpay_get_transaction_status`	根据令牌获取 Webpay Plus 交易的当前状态。
`webpay_refund_transaction`	退款已提交的 Webpay Plus 交易。
`webpay_increase_amount`	扣取先前已授权的 Webpay Plus 交易（部分扣款／延迟扣款流程）。
`webpay_capture_transaction`	延迟扣取先前已授权的 Webpay Plus 交易。
`webpay_mall_create_transaction`	创建 Webpay Mall 交易——一个父级 `buy_order` 拆分到多个卖家商务代码。
`webpay_mall_commit_transaction`	用户返回后，提交 Webpay Mall 交易。
`webpay_mall_get_transaction_status`	根据令牌获取 Webpay Mall 交易的状态（包括各子交易的详细信息）。
`webpay_mall_refund_transaction`	为 Webpay Mall 交易中的一个子卖家退款。
`webpay_mall_capture_transaction`	延迟扣取 Webpay Mall 交易中的一个子卖家款项。
`oneclick_create_inscription`	启动 OneClick Mall 卡片绑定流程。
`oneclick_finish_inscription`	用户返回后，完成 OneClick Mall 绑定。
`oneclick_delete_inscription`	删除（撤销）用户已存储的 OneClick Mall 卡片。
`oneclick_authorize`	使用已存储的 OneClick Mall 卡片，通过一个或多个商城商户代码扣款。
`oneclick_capture`	扣取先前已授权的 OneClick Mall 款项（延迟扣款流程）。
`oneclick_refund`	为 OneClick Mall 款项退款。
`oneclick_status`	根据父级 `buy_order` 获取 OneClick Mall 交易的状态。
`oneclick_get_transaction_by_buy_order`	根据父级 `buy_order` 查询 OneClick Mall 交易。

安装

npm install @codespar/mcp-transbank@alpha

环境

TRANSBANK_COMMERCE_CODE="..."   # merchant commerce code (Tbk-Api-Key-Id)
TRANSBANK_API_KEY_SECRET="..."  # secret key (Tbk-Api-Key-Secret)
TRANSBANK_ENV="integration"     # 'integration' (default) or 'production'

集成基础 URL：https://webpay3gint.transbank.cl 生产环境基础 URL：https://webpay3g.transbank.cl

身份验证

每个请求都会发送两个标头：

Tbk-Api-Key-Id: <commerce_code>
Tbk-Api-Key-Secret: <api_key_secret>
Content-Type: application/json

服务会自动处理标头——你只需配置环境变量。

运行

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

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

Webpay Plus 流程

使用 buy_order、session_id、amount、return_url 调用 webpay_create_transaction。
将用户重定向到 url?token_ws=<token>。
用户在 Webpay 完成支付后，会被重定向回 return_url。
使用返回的令牌调用 webpay_commit_transaction，以实际扣款。

OneClick Mall 流程

使用 username、email、response_url 调用 oneclick_create_inscription。将用户重定向到 url_webpay。
用户返回后，调用 oneclick_finish_inscription。将返回的 tbk_user 与你的用户关联存储。
若要稍后扣款，使用 username、tbk_user、父级商城 buy_order 和 details 数组（每个子商户对应一项）调用 oneclick_authorize。