# Webpay Plus - REST API 集成技巧该技能提供了使用 REST API (HTTP) 集成 Transbank Webpay Plus 支付网关所需的一切。它涵盖了完整的购买周期：创建交易、确认付款、检查状态、退款/撤消和延期捕获。 > 此技能仅涵盖**Webpay Plus**（单店）。它不涵盖 Webpay Plus Mall（多商店）或 Oneclick。 ## 目录 1. 环境和凭证 2. 支付流程概述 3.API端点 * 创建交易 * 确认交易（提交） * 获取交易状态 * 退款/反向交易 * 捕获交易（延期） 4. 参考表 5. 错误代码 6. 投入生产 ** ** ## 环境和凭证 Webpay REST API 通过 TLSv1.2 进行保护，并在每个请求上使用两个 HTTP 标头进行身份验证：标题 |描述 ---|--- `Tbk-Api-Key-Id` |商业代码 (codigo de comercio) `Tbk-Api-Key-Secret` |秘密密钥（llave Secreta）所有请求还必须包含“Content-Type: application/json”。 ### 环境环境 |基本网址 ---|--- **集成（测试）** | `https://webpay3gint.transbank.cl` **生产** | `https://webpay3g.transbank.cl` ### 集成测试凭证在集成环境中自由使用这些凭据进行测试： Tbk-Api-Key-Id：597055555532 Tbk-Api-密钥秘密：579B532A7440BB0C9079DED94D31EA1615BACEB56610332264630D42D0A36B1C ### 集成测试卡要在集成环境中进行测试，请使用中记录的测试卡交易成功的常用测试数据： * **卡号** : `4051 8856 0044 6623` * **到期日期**：任何未来日期 * **CVV**：`123` * **RUT**：`11.111.111-1` * **密码**：`123` 要模拟**被拒绝的**交易，请使用 RUT“11.111.111-1”和密码“123”，但拒绝 Webpay 表单中的付款。 ### 集成商业代码产品 |商业代码 ---|--- 网络支付加 | `597055555532` Webpay Plus（延迟捕获）| `597055555540` ** ** ## 支付流程概览 Webpay Plus 支付周期遵循以下顺序： 1. 商户服务器 2. WEBPAY（跨银行） | | |-- POST /交易 -------------->| （创建交易） |<-- { 令牌, url } ------------------| | | |-- 将用户重定向到 url + token ---->| （用户通过 Webpay 表单付款） | | |<-- 重定向到 return_url ----------| （Webpay通过POST发送token_ws） | | |-- PUT /交易/{token} ------->| （确认/提交交易） |<-- { 交易结果 } ----------| | | |-- 向用户显示结果 | ### 一步一步： 1. **创建交易** ：您的服务器使用订单详细信息调用“POST /rswebpaytransaction/api/webpay/v1.2/transactions”。您会收到一个“token”和一个“url”。 2. **重定向到 Webpay** ：将用户的浏览器重定向到返回的“url”，通过名为“token_ws”的表单 POST 字段传递“token”： <输入类型=“提交”值=“帕加尔”> 3. **用户付款**：用户在 Transbank 的安全表单上输入其银行卡详细信息并授权付款。 4. **Webpay 重定向回来** ：授权（或拒绝/中止）后，Webpay 通过 POST 将用户重定向回您的“return_url”，发送： * `token_ws`：交易令牌（如果用户完成了流程） * `TBK_TOKEN` \+ `TBK_ORDEN_COMPRA` \+ `TBK_ID_SESION`：仅当用户 **中止** 付款时 5. **确认交易** ：您的服务器调用 `PUT /rswebpaytransaction/api/webpay/v1.2/transactions/{token}` 来确认并获取结果。 6. **显示结果** ：向用户显示支付结果。 ### 处理中止的付款如果用户在 Webpay 表单上单击“Anular”（取消），则重定向到“return_url”将包括“TBK_TOKEN”、“TBK_ORDEN_COMPRA”和“TBK_ID_SESION”，而不是“token_ws”。在这种情况下，交易未完成。不调用commit；通知用户付款已取消。 ### 超时行为如果用户没有在允许的时间内完成支付，则会有两个请求到达“return_url”： 1. 首先使用`TBK_TOKEN`、`TBK_ORDEN_COMPRA`、`TBK_ID_SESION`（和空的`token_ws`） 2. 仅包含“TBK_TOKEN”的第二个请求（来自用户浏览器的 POST）两者都表明交易已被放弃。不确认交易。 ** ** ## API 端点所有端点路径都相对于所选环境的基本 URL。 **基本路径** : `/rswebpaytransaction/api/webpay/v1.2` ### 1\.创建交易初始化 Webpay Plus 付款。返回付款表单的令牌和 URL。 **端点**：`POST /rswebpaytransaction/api/webpay/v1.2/transactions` **请求标头**： Tbk-Api-Key-Id：597055555532 Tbk-Api-密钥秘密：579B532A7440BB0C9079DED94D31EA1615BACEB56610332264630D42D0A36B1C 内容类型：application/json **请求正文**： { "buy_order": "ordenCompra12345678", "session_id": "session1234557545", “金额”：10000， “return_url”：“http://www.comercio.cl/webpay/retorno” } **请求参数**：参数|类型 |描述 ---|---|--- `购买订单` |字符串|此交易的唯一订单 ID。最大长度：26。允许的字符：字母、数字和 `|_=&%.,~:/?[+!@()>-` `session_id` |字符串|会话标识符，供商户内部使用。交易结束后返回。最大长度：61 `金额` |十进制|交易金额。 CLP 为整数，USD 最多 2 位小数。最大长度：17 `return_url` |字符串| Webpay 授权后重定向的 URL。最大长度：256 **响应**（200 OK）： { “令牌”：“e9d555262db0f989e49d724b4db0b0af367cc415cde41f500a776550fc5fddd3”， “url”：“https://webpay3gint.transbank.cl/webpayserver/initTransaction” } **响应字段**：领域|类型 |描述 ---|---|--- `令牌` |字符串|交易代币。长度：64 `网址` |字符串| Webpay 付款表单 URL。最大长度：255 ** ** ### 2\.确认交易（提交）用户在 Webpay 上完成支付并被重定向到“return_url”后，确认交易。这是完成付款所必需的。 **端点**：`PUT /rswebpaytransaction/api/webpay/v1.2/transactions/{token}` **请求标头**： Tbk-Api-Key-Id：597055555532 Tbk-Api-密钥秘密：579B532A7440BB0C9079DED94D31EA1615BACEB56610332264630D42D0A36B1C 内容类型：application/json **网址参数**：参数|类型 |描述 ---|---|--- `令牌` |字符串|交易令牌（在 URL 路径中，而不是正文中）。长度：64 **不需要请求正文**。 **响应**（200 OK）： { “vci”：“TSY”， “金额”：10000， “状态”：“已授权”， "buy_order": "ordenCompra12345678", "session_id": "session1234557545", “卡片详细信息”：{ “卡号”：“6623” }, “会计日期”：“0522”， "transaction_date": "2019-05-22T16:41:21.063Z", “授权代码”：“1213”， " payment_type_code": "VN", “响应代码”：0， “分期付款数量”：0 } **响应字段**：领域|类型 |描述 ---|---|--- `vci` |字符串|持卡人身份验证结果。查看 VCI 代码 `金额` |十进制|交易金额。最大长度：17 `状态` |字符串|交易状态。查看交易状态 `购买订单` |字符串|创建时发送的订单 ID。最大长度：26 `session_id` |字符串|在 create 中发送的会话 ID。最大长度：61 `卡片详细信息` |对象|卡详细信息对象 `card_detail.card_number` |字符串|卡的最后 4 位数字。最大长度：19 `会计日期` |字符串|授权日期。长度：4，格式：MMDD `交易日期` |字符串|授权日期/时间。 ISO 8601 格式 `授权代码` |字符串|授权码。最大长度：6 `付款类型代码` |字符串|付款类型。查看付款类型代码 `响应代码` |数量 |授权响应代码。 0 = 已批准 `分期付款金额` |数量 |分期付款金额。最大长度：17 `分期付款数量` |数量 |分期付款次数。最大长度：2 `平衡` |数量 |无效明细的剩余余额。最大长度：17 ### 验证成功的交易调用 commit 后，通过检查验证事务是否成功： 1. `response_code` 等于 `0` 2. `status` 等于 `"AUTHORIZED"` 如果“response_code”不为“0”，则交易被拒绝。 ** ** ### 3\.获取交易状态随时查询交易状态。对于错误恢复或验证事务的当前状态很有用。 **端点**：`GET /rswebpaytransaction/api/webpay/v1.2/transactions/{token}` **请求标头**： Tbk-Api-Key-Id：597055555532 Tbk-Api-密钥秘密：579B532A7440BB0C9079DED94D31EA1615BACEB56610332264630D42D0A36B1C 内容类型：application/json **网址参数**：参数|类型 |描述 ---|---|--- `令牌` |字符串|交易令牌（在 URL 中，而不是正文中）。长度：64 **响应**：与提交响应的结构相同（见上文）。 ** ** ### 4\.退款/反向交易退还全部或部分已完成的交易。如果在原始交易的同一天内调用，可能会导致**逆转**（REVERSED）。如果在不同的日子调用，它就会变成**无效**（NULLIFIED）。 **端点**：`POST /rswebpaytransaction/api/webpay/v1.2/transactions/{token}/refunds` **请求标头**： Tbk-Api-Key-Id：597055555532 Tbk-Api-密钥秘密：579B532A7440BB0C9079DED94D31EA1615BACEB56610332264630D42D0A36B1C 内容类型：application/json **网址参数**：参数|类型 |描述 ---|---|--- `令牌` |字符串|交易令牌（在 URL 中，而不是正文中）。长度：64 **请求正文**： { “金额”：1000 } **请求参数**：参数|类型 |描述 ---|---|--- `金额` |十进制|退款/冲销金额。 CLP 为整数，USD 最多 2 位小数。最大长度：17 **响应**（200 OK）- 无效： { “类型”：“NULLIFIED”， "授权码": "123456", "authorization_date": "2019-03-20T20:18:20Z", “无效金额”：1000.00， “余额”：0.00， “响应代码”：0 } **响应**（200 OK）-反转： { “类型”：“反转” } **响应字段**：领域|类型 |描述 ---|---|--- `类型` |字符串|退款类型：“REVERSED”或“NULLIFIED”。最大长度：10 `授权代码` |字符串| （仅限 NULLIFIED）授权代码。最大长度：6 `授权日期` |字符串| （仅限 NULLIFIED）授权日期/时间 `平衡` |十进制| （仅限 NULLIFIED）更新余额。最大长度：17 `无效金额` |十进制| （仅限 NULLIFIED）无效金额。最大长度：17 `响应代码` |数量 | （仅限 NULLIFIED）结果代码。 0 = 成功。最大：2 **退款错误代码**：代码|描述 ---|--- 304 | 304空输入字段验证 245 | 245商业代码不存在 22 | 22商业不活跃 316 | 316商务与证书不符 308 | 308不允许操作 274 | 274未找到交易 16 | 16交易不允许作废 292 | 292交易未获授权 284 | 284超过废止期限 310 | 310交易已作废 311 | 311金额超过可用余额即可作废 312 | 312一般无效错误 315 | 315授权者错误 53 | 53交易不允许分期付款部分作废 ** ** ### 5\.捕获交易（延期）对于配置了延迟捕获的商户，此端点捕获先前授权的交易。需要特定的商业代码才能延迟捕获。 **延迟捕获的集成商务代码**：`597055555540` **端点**：`PUT /rswebpaytransaction/api/webpay/v1.2/transactions/{token}/capture` **请求标头**： Tbk-Api-Key-Id：597055555540 Tbk-Api-密钥秘密：579B532A7440BB0C9079DED94D31EA1615BACEB56610332264630D42D0A36B1C 内容类型：application/json **网址参数**：参数|类型 |描述 ---|---|--- `令牌` |字符串|交易令牌（在 URL 中，而不是正文中）。长度：64 **请求正文**： { "购买订单": "415034240", “授权码”：“12345”， “捕获量”：1000 } **请求参数**：参数|类型 |描述 ---|---|--- `购买订单` |字符串|要捕获的交易的订单 ID。最大长度：26 `授权代码` |字符串|来自原始交易的授权码。最大长度：6 `捕获量` |十进制|要捕获的数量。最大长度：17 **响应**（200 OK）： { “令牌”：“e074d38c628122c63e5c0986368ece22974d6fee1440617d85873b7b4efa48a3”， "授权码": "123456", "authorization_date": "2019-03-20T20:18:20Z", “捕获量”：1000， “响应代码”：0 } **响应字段**：领域|类型 |描述 ---|---|--- `令牌` |字符串|交易代币。最大长度：64 `授权代码` |字符串|延迟捕获授权代码。最大长度：6 `授权日期` |字符串|授权日期/时间 `捕获量` |十进制|捕获量。最大长度：6 `响应代码` |数量 |结果代码。 0 = 成功。最大：2 **捕获错误代码**：代码|描述 ---|--- 304 | 304空输入字段验证 245 | 245商业代码不存在 22 | 22商业不活跃 316 | 316商务与证书不符 308 | 308不允许操作 274 | 274未找到交易 16 | 16事务不延迟捕获 292 | 292交易未获授权 284 | 284超过捕获期限 310 | 310先前撤销的交易 309 | 309先前捕获的交易 311 | 311捕获金额超过授权金额 315 | 315授权者错误 ** ** ## 参考表 ### 交易状态状态 |描述 ---|--- `初始化` |交易已创建，等待用户完成支付 `授权` |交易授权成功 `反转` |交易被撤销（当天退款） `失败` |交易被拒绝或失败 `无效` |交易被取消（会计日期后退款） `部分无效` |交易部分无效 `捕获` |事务已捕获（延迟捕获） ### 付款类型代码代码|描述 ---|--- `VD` |借记销售（Venta Debito） `越南` |正常销售 - 信用 (Venta Normal) 'VC' |分期付款销售 (Venta en Cuotas) `SI` | 3 期免息分期付款 (3 Cuotas sin Interests) 'S2' | 2 次免息分期付款（2 Cuotas sin Interests） 'NC' | N 免息分期付款 (N Cuotas sin Interests) `副总裁` |预付特卖 (Venta Prepago) ### VCI 代码 “vci”字段表示持卡人认证结果。这是“response_code”的补充信息。由于不断添加新代码，商家不应验证此字段。 **国内交易** : 代码|描述 ---|--- 'TSY' |认证成功 `TSN` |身份验证被拒绝 'NP' |不参与、不认证 'U3' |连接失败，身份验证被拒绝 `INV` |无效数据 `A` |尝试过 'CNP1' |商务部不参与 `EOP` |操作错误 'BNA' | BIN 未注册 `埃纳` |发行人未登记 **国外销售代码**：代码|描述 ---|--- `TSYS` |成功的无摩擦身份验证 'TSAS' |尝试，卡未注册/发卡机构不可用 'TSNS' |失败、未验证、被拒绝 `TSRS` |身份验证被拒绝，无摩擦 `TSUS` |由于技术问题，身份验证失败 `TSCF` |挑战身份验证（不被商业接受） 'TSYF' |挑战认证成功 `TSNF` |未经过身份验证，因质询而被拒绝 `TSUF` |由于技术问题，挑战身份验证失败 'NPC' |商务部不参与 'NPB' | BIN不参与 'NPCB' |商务部和 BIN 不参与 'SPCB' | Commerce和BIN参与，授权不完整 ** ** ## 错误代码 ### HTTP 状态代码 HTTP 代码 |描述 ---|--- 200 | 200操作执行成功 204 | 204 DELETE操作执行成功 400 |无效的 JSON 消息（格式错误或意外的字段） 401 | 401未经授权。无效的 API 密钥和/或 API 密钥 404 | 404未找到交易 405 | 405方法不允许 406 | 406无法处理请求格式的响应 415 | 415消息类型不允许 422 | 422无法处理请求（数据验证或业务逻辑） 500 | 500意外错误所有错误都会返回 JSON 正文： { "error_message": "需要令牌" } ** ** ## 进入生产阶段从集成转向生产： 1. 完成Transbank的认证流程 2. 获取您的生产商业代码和API密钥 3. 将基本 URL 从 `https://webpay3gint.transbank.cl` 更改为 `https://webpay3g.transbank.cl` 4. 将集成凭据替换为您的生产凭据更多详情请访问 ** ** ## 实现示例 ### Node.js / Express 后端示例 const express = require('express'); const axios = require('axios'); 常量应用程序 = Express(); app.use(express.json()); app.use(express.urlencoded({ 扩展: true })); // 配置 const WEBPAY_BASE_URL = 'https://webpay3gint.transbank.cl'; // 使用 prod 的生产 URL const API_KEY_ID = '597055555532'; const API_KEY_SECRET = '579B532A7440BB0C9079DED94D31EA1615BACEB56610332264630D42D0A36B1C'; 常量标头 = { 'Tbk-Api-Key-Id'：API_KEY_ID， 'Tbk-Api-Key-Secret'：API_KEY_SECRET， '内容类型'：'应用程序/json' }; // 步骤1：创建交易 app.post('/api/webpay/create', async (req, res) => { 尝试{ const { buy_order, session_id, amount, return_url } = req.body; const 响应 = 等待 axios.post( `${WEBPAY_BASE_URL}/rswebpaytransaction/api/webpay/v1.2/transactions`, { buy_order, session_id, 金额, return_url }, { 标题 } ）； // 返回 token 和 url 到前端 res.json(response.data); } 捕获（错误）{ res.status(error.response?.status || 500).json({ 错误：错误.响应？.数据|| “创建交易时出错” }); } }); // 步骤 2：确认交易（return_url 处理程序） app.post('/api/webpay/confirm', async (req, res) => { 尝试{ const token_ws = req.body.token_ws; // 检查支付是否被中止 if (!token_ws || req.body.TBK_TOKEN) { return res.redirect('/支付取消'); } const 响应 = 等待 axios.put( `${WEBPAY_BASE_URL}/rswebpaytransaction/api/webpay/v1.2/transactions/${token_ws}`, 空， { 标题 } ）； const 结果 = 响应.data; // 验证交易成功 if (result.response_code === 0 && result.status === '授权') { // 支付成功-更新您的数据库 res.redirect(`/付款成功？order=${result.buy_order}`); } 否则{ // 付款被拒绝 res.redirect(`/付款被拒绝？order=${result.buy_order}`); } } 捕获（错误）{ res.redirect('/付款错误'); } }); // 检查交易状态 app.get('/api/webpay/status/:token', async (req, res) => { 尝试{ const 响应 = 等待 axios.get( `${WEBPAY_BASE_URL}/rswebpaytransaction/api/webpay/v1.2/transactions/${req.params.token}`, { 标题 } ）； res.json(response.data); } 捕获（错误）{ res.status(error.response?.status || 500).json({ 错误：错误.响应？.数据|| “检查状态时出错” }); } }); // 退款交易 app.post('/api/webpay/refund', async (req, res) => { 尝试{ const { 代币，金额 } = req.body; const 响应 = 等待 axios.post( `${WEBPAY_BASE_URL}/rswebpaytransaction/api/webpay/v1.2/transactions/${token}/refunds`, { 金额 }, { 标题 } ）； res.json(response.data); } 捕获（错误）{ res.status(error.response?.status || 500).json({ 错误：错误.响应？.数据|| “退款交易出错” }); } }); ### 前端重定向示例

<输入类型=“隐藏”名称=“token_ws”id=“token_ws”> <脚本> 异步函数initialPayment(orderData) { const 响应 = 等待 fetch('/api/webpay/create', { 方法：'POST'， headers: { 'Content-Type': 'application/json' }, 正文：JSON.stringify({ buy_order: orderData.orderId, session_id: orderData.sessionId, 金额：orderData.金额， return_url: window.location.origin + '/api/webpay/confirm' }) }); const { token, url } =等待response.json(); // 重定向到 Webpay 付款表单 const form = document.getElementById('webpay-form'); 表单.action = url; document.getElementById('token_ws').value = token; 表单.提交(); } ### cURL 示例 **创建交易**：卷曲-X POST“https://webpay3gint.transbank.cl/rswebpaytransaction/api/webpay/v1.2/transactions”\ -H“Tbk-Api-Key-Id：597055555532”\ -H“Tbk-Api-密钥秘密：579B532A7440BB0C9079DED94D31EA1615BACEB56610332264630D42D0A36B1C”\ -H“内容类型：application/json”\ -d'{ "buy_order": "订单123", “session_id”：“session456”， “金额”：10000， "return_url": "http://localhost:3000/webpay/confirm" }' **确认交易** : curl -X PUT "https://webpay3gint.transbank.cl/rswebpaytransaction/api/webpay/v1.2/transactions/{token}" \ -H“Tbk-Api-Key-Id：597055555532”\ -H“Tbk-Api-密钥秘密：579B532A7440BB0C9079DED94D31EA1615BACEB56610332264630D42D0A36B1C”\ -H“内容类型：application/json” **获取交易状态** : curl -X GET "https://webpay3gint.transbank.cl/rswebpaytransaction/api/webpay/v1.2/transactions/{token}" \ -H“Tbk-Api-Key-Id：597055555532”\ -H“Tbk-Api-密钥秘密：579B532A7440BB0C9079DED94D31EA1615BACEB56610332264630D42D0A36B1C”\ -H“内容类型：application/json” **退款**：卷曲-X POST“https://webpay3gint.transbank.cl/rswebpaytransaction/api/webpay/v1.2/transactions/{token}/refunds”\ -H“Tbk-Api-Key-Id：597055555532”\ -H“Tbk-Api-密钥秘密：579B532A7440BB0C9079DED94D31EA1615BACEB56610332264630D42D0A36B1C”\ -H“内容类型：application/json”\ -d '{"金额": 5000}' **捕获（延迟）**：卷曲-X PUT“https://webpay3gint.transbank.cl/rswebpaytransaction/api/webpay/v1.2/transactions/{token}/capture”\ -H“Tbk-Api-Key-Id：597055555540”\ -H“Tbk-Api-密钥秘密：579B532A7440BB0C9079DED94D31EA1615BACEB56610332264630D42D0A36B1C”\ -H“内容类型：application/json”\ -d'{ "buy_order": "订单123", "授权码": "123456", “捕获量”：10000 }' ** ** ## 重要实施说明 1. **每笔交易的`buy_order`必须是唯一的**。它不能重复使用。 2. **始终在收到重定向后确认（提交）交易**。如果不调用commit，交易将保持“INITIALIZED”状态，并且不会处理付款。 3. **Commit 有时间限制** ：必须在用户重定向回来后的几秒内确认事务。如果时间过长，交易可能会过期。 4. **在“return_url”处处理所有重定向场景**： * `token_ws` 存在：正常流程，继续提交 * 存在“TBK_TOKEN”（无“token_ws”）：用户中止 * 两者都显示空“token_ws”：超时 5. **退款与冲销** ：API自动判断是冲销（当天，会计截止前）还是作废（会计截止后）。您始终调用同一个端点。 6. **支持部分退款**：您可以在原交易金额以内任意退款。允许多次部分退款，直至余额为零。 7. **延期捕获**需要特殊的商业代码和 Transbank 的配置。并非所有商家都启用此功能。 8. **`vci` 字段**不应用于业务逻辑验证。请改用“response_code”。 “vci”字段仅供参考，添加新值时不会更新文档。 9. **`response_code`** 是交易是否被批准（0）或被拒绝（非零）的明确指标。

网络支付API

包含技能