@codespar/mcp-transbank

MCP server for Transbank — Chile's dominant card acquirer.

Transbank is effectively default for Chilean commerce (state-origin roots, owned by a consortium of Chilean banks). Shipping this server is a prerequisite for any "CodeSpar covers LatAm" claim that includes Chile.

Two products are covered:

• Webpay Plus — one-shot redirect payments (buy_order + amount, user is redirected to Webpay to pay).
• Webpay OneClick Mall — tokenized recurring / card-on-file payments that can split across multiple merchant codes (the "mall" model).

Tools (19)

| Tool | Purpose | |---|---| | webpay_create_transaction | Create a Webpay Plus transaction. | | webpay_commit_transaction | Commit a Webpay Plus transaction after the user has returned from the Webpay flow. | | webpay_get_transaction_status | Get the current status of a Webpay Plus transaction by token. | | webpay_refund_transaction | Refund a committed Webpay Plus transaction. | | webpay_increase_amount | Capture a previously authorized Webpay Plus transaction (partial-capture / deferred-capture flow). | | webpay_capture_transaction | Deferred-capture for a previously authorized Webpay Plus transaction. | | webpay_mall_create_transaction | Create a Webpay Mall transaction — one parent buy_order split across several seller commerce codes. | | webpay_mall_commit_transaction | Commit a Webpay Mall transaction after the user has returned. | | webpay_mall_get_transaction_status | Get the status of a Webpay Mall transaction by token (includes per-child details). | | webpay_mall_refund_transaction | Refund one child seller of a Webpay Mall transaction. | | webpay_mall_capture_transaction | Deferred-capture for one child seller inside a Webpay Mall transaction. | | oneclick_create_inscription | Start a OneClick Mall card-enrollment flow. | | oneclick_finish_inscription | Finalize a OneClick Mall enrollment after the user has returned. | | oneclick_delete_inscription | Delete (revoke) a stored OneClick Mall card for a user. | | oneclick_authorize | Charge a stored OneClick Mall card across one or more mall merchant codes. | | oneclick_capture | Capture a previously authorized OneClick Mall charge (deferred-capture flow). | | oneclick_refund | Refund a OneClick Mall charge. | | oneclick_status | Get the status of a OneClick Mall transaction by parent buy_order. | | oneclick_get_transaction_by_buy_order | Look up a OneClick Mall transaction by parent buy_order. |

Install

npm install @codespar/mcp-transbank@alpha

Environment

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'

Integration base URL: https://webpay3gint.transbank.cl Production base URL: https://webpay3g.transbank.cl

Authentication

Every request sends two headers:

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

The server handles headers automatically — you only configure the env vars.

Run

# 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 flow

1. Call webpay_create_transaction with buy_order, session_id, amount, return_url.
2. Redirect user to url?token_ws=<token>.
3. User pays at Webpay, is redirected back to return_url.
4. Call webpay_commit_transaction with the returned token to actually charge.

OneClick Mall flow

1. Call oneclick_create_inscription with username, email, response_url. Redirect user to url_webpay.
2. After user returns, call oneclick_finish_inscription. Store the returned tbk_user against your user.
3. To charge later, call oneclick_authorize with username, tbk_user, a parent mall buy_order, and a details array (one entry per child merchant).

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