webpay-api

Webpay Plus REST API 集成技能

本技能用于通过 REST API（HTTP）集成 Transbank 的 Webpay Plus 支付网关，覆盖完整的购买周期：创建交易、确认支付（Commit）、查询状态、退款/冲正以及延迟捕获。本技能仅覆盖 Webpay Plus（单店铺），不覆盖 Webpay Plus Mall（多店铺）或 Oneclick。

一、用途面向需要在其系统中实现 Webpay Plus 支付的开发者，提供从环境配置、凭证管理、支付流程到各 API 接口的完整说明，包括请求/响应结构、字段含义、错误码以及上线生产的步骤。

二、环境与认证 Webpay REST API 通过 TLSv1.2 保护，每次请求使用两个 HTTP 头认证：Tbk-Api-Key-Id（商业代码）和 Tbk-Api-Key-Secret（密钥）。所有请求还需包含 Content-Type: application/json。

环境：

集成（测试）：https://webpay3gint.transbank.cl
生产：https://webpay3g.transbank.cl

集成测试凭证：

Tbk-Api-Key-Id: 597055555532
Tbk-Api-Key-Secret: 579B532A7440BB0C9079DED94D31EA1615BACEB56610332264630D42D0A36B1C

集成测试卡（成功交易常用数据）：卡号 4051 8856 0044 6623，有效期任意未来日期，CVV 123，RUT 11.111.111-1，密码 123。模拟被拒交易可使用 RUT 11.111.111-1 与密码 123，但在 Webpay 表单中拒绝支付。

集成用商业代码：Webpay Plus 为 597055555532；Webpay Plus（延迟捕获）为 597055555540。

三、支付流程概述

商家服务器调用 POST /transactions 创建交易，获得 token 和 url。
将用户浏览器重定向到返回的 url，通过名为 token_ws 的表单 POST 字段传递 token。
用户在 Transbank 安全表单输入卡信息并授权支付。
Webpay 将用户重定向回 return_url（POST），成功时发送 token_ws；若用户中止支付，则发送 TBK_TOKEN、TBK_ORDEN_COMPRA、TBK_ID_SESION。
商家服务器调用 PUT /transactions/{token} 确认（Commit）并获取结果。
向用户展示支付结果。

处理中止支付：若用户在 Webpay 表单点击“Anular”（取消），重定向回 return_url 时会包含 TBK_TOKEN、TBK_ORDEN_COMPRA、TBK_ID_SESION 而非 token_ws，此时交易未完成，不应调用 commit，应告知用户支付已取消。

超时行为：若用户未在允许时间内完成支付，return_url 会收到两次请求：第一次带 TBK_TOKEN、TBK_ORDEN_COMPRA、TBK_ID_SESION（token_ws 为空），第二次仅带 TBK_TOKEN（来自用户浏览器的 POST）。两者均表示交易被放弃，不应确认交易。

四、API 接口所有接口路径相对于所选环境的基础 URL。基础路径：/rswebpaytransaction/api/webpay/v1.2

创建交易 POST /rswebpaytransaction/api/webpay/v1.2/transactions 请求头：Tbk-Api-Key-Id、Tbk-Api-Key-Secret、Content-Type: application/json。请求体示例：{ "buy_order": "ordenCompra12345678", "session_id": "sesion1234557545", "amount": 10000, "return_url": "http://www.comercio.cl/webpay/retorno" } 参数：buy_order（唯一订单 ID，最长 26，允许字母、数字及 |_=&%.,~:/?[+!@()>-）；session_id（会话标识，最长 61）；amount（金额，CLP 为整数，USD 最多 2 位小数，最长 17）；return_url（授权后重定向 URL，最长 256）。响应（200 OK）：{ "token": "e9d555262db0f989e49d724b4db0b0af367cc415cde41f500a776550fc5fddd3", "url": "https://webpay3gint.transbank.cl/webpayserver/initTransaction" } 字段：token（长度 64）；url（支付表单 URL，最长 255）。
确认交易（Commit） PUT /rswebpaytransaction/api/webpay/v1.2/transactions/{token} token 放在 URL 路径中，长度 64。无需请求体。响应（200 OK）字段包括：vci、amount、status、buy_order、session_id、card_detail.card_number（卡号后 4 位）、accounting_date（格式 MMDD）、transaction_date（ISO 8601）、authorization_code（最长 6）、payment_type_code、response_code（0 表示批准）、installments_amount、installments_number、balance。验证成功：response_code 等于 0 且 status 等于 "AUTHORIZED"；若 response_code 不为 0 则交易被拒。
查询交易状态 GET /rswebpaytransaction/api/webpay/v1.2/transactions/{token} token 放在 URL 中，长度 64。响应结构与 Commit 响应相同。
退款/冲正 POST /rswebpaytransaction/api/webpay/v1.2/transactions/{token}/refunds 请求体：{ "amount": 1000 } 若与原交易同日调用可能为冲正（REVERSED），不同日则为作废（NULLIFIED）。作废响应字段：type、authorization_code、authorization_date、nullified_amount、balance、response_code（0 表示成功）。冲正响应仅含 type。退款错误码包括：304、245、22、316、308、274、16、292、284、310、311、312、315、53 等（各自含义按原文表格）。
延迟捕获（Capture）适用于配置了延迟捕获的商户。集成延迟捕获商业代码：597055555540。 PUT /rswebpaytransaction/api/webpay/v1.2/transactions/{token}/capture token 放在 URL 中。请求体：{ "buy_order": "415034240", "authorization_code": "12345", "capture_amount": 1000 } 响应字段：token、authorization_code、authorization_date、captured_amount、response_code（0 表示成功）。捕获错误码包括：304、245、22、316、308、274、16、292、284、310、309、311、315。

五、参考表交易状态：INITIALIZED、AUTHORIZED、REVERSED、FAILED、NULLIFIED、PARTIALLY_NULLIFIED、CAPTURED。支付类型码：VD、VN、VC、SI、S2、NC、VP。 VCI 码：本地交易包括 TSY、TSN、NP、U3、INV、A、CNP1、EOP、BNA、ENA；境外销售包括 TSYS、TSAS、TSNS、TSRS、TSUS、TSCF、TSYF、TSNF、TSUF、NPC、NPB、NPCB、SPCB。注意 vci 仅作补充信息，商户不应以此验证，因为会不断新增代码。 HTTP 状态码：200、204、400、401、404、405、406、415、422、500。所有错误返回 JSON：{ "error_message": "token is required" }。

六、上线生产步骤：完成 Transbank 认证流程；获取生产商业代码和 API 密钥；将基础 URL 从 https://webpay3gint.transbank.cl 改为 https://webpay3g.transbank.cl；用生产凭证替换集成凭证。

七、适用场景与限制适用于需要集成 Transbank Webpay Plus 单店铺支付的商户与服务端应用（示例含 Node.js/Express 后端）。限制：不覆盖 Webpay Plus Mall（多店铺）或 Oneclick；集成测试凭证与测试卡仅供测试环境使用；生产上线需完成 Transbank 认证流程。

技能介绍