VTEX 无头整合指南

集成 Yuno SDK Web for VTEX Headless，高效处理在线支付。本指南涵盖安装、配置和实施步骤。

VTEXIO集成

要在 VTEXIO 签出中使用 Yuno，请安装以下应用程序：

yunopartnerbr.yuno:VTEXIO PPF 连接器可促进 VTEX 与 Yuno 支付基础设施之间的集成。
yunopartnerbr.yuno-app:使用卡或点击付款作为付款方式时，需要 VTEXIO 前端付款应用程序。Pix、Boleto 和其他基于重定向的支付方式则不需要。 yunopartnerbr.yuno-app 其主要特点如下
- 运行 Yuno Web SDK 以收集浏览器数据。
- 执行第三方欺诈检测 SDK。
- 直接在 Yuno 中处理付款。
- 支持使用两张信用卡付款。

安装

要将Yuno 与 VTEX 集成，您需要安装两个应用程序：

yunopartnerbr.yuno:用于后台通信的 VTEX PPF 连接器。
yunopartnerbr.yuno-app:前端支付应用程序，用于基于银行卡的支付。

🚧
所需管理员权限
要安装这两个应用程序，您需要 VTEX 中的管理员权限。

安装 `yunopartnerbr.yuno`

按照以下步骤安装 yunopartnerbr.yuno 于 VTEX 管理员:

登录您的VTEX 商店账户。
在 VTEX Admin 面板中，导航至 "商店设置">"提供商"，然后单击 "新建提供商"。
在可用提供商列表中搜索Yuno。
单击 "安装"，然后按照设置说明进行操作。

有关详细信息，请参阅 "将 Yuno 配置为提供程序"页面。

安装 `yunopartnerbr.yuno-app`

yunopartnerbr.yuno-app 使用银行卡或点击支付付款时需要安装。请按照以下步骤安装：

在VTEX 管理中，转到应用程序 > 应用程序管理。
搜索Yuno。
找到并选择Yuno Payment App（列表中的第二个选项）。
单击 "安装"完成设置。

安装适用于VTEX的Yuno SDK Web（可选）

如果您的项目需要 Yuno SDK Web VTEX，使用 npm:

npm install @yuno-payments/sdk-web-vtex

该软件包简化了SDK Web VTEX的集成，并包含 TypeScript 支持。

要使用 SDK，请导入并initialize 它：

从'@yuno-payments/sdk-web-vtex'导入 { loadScript }

...

const yunoVTEX = await loadScript()

yunoVTEX.mount({...})

欲了解更多信息，请访问@yuno-payments/sdk-web-vtex 。

支付流程

以下各节说明了 VTEXIO 和 VTEX Headless 如何使用不同的支付方法处理支付：

VTEXIO 中的信用卡支付流程
VTEXIO 中的 Pix (APMs) 支付流程
VTEX 无头支付流程

VTEXIO支付流程

VTEXIO 支持各种方式的无缝支付处理，包括信用卡和 Pix 等其他支付方式 (APM)。以下是这些支付流程如何运作的分步说明。

VTEXIO中的信用卡支付流程

该流程详细说明了 VTEXIO 如何处理信用卡支付，从用户交互到交易完成。

用户点击 VTEXIO 前端的支付按钮。
VTEX 后端将付款信息发送到 yunopartnerbr.yuno 连接器。
Yuno 连接器将信用卡信息发送到 Yuno API。
Yuno API 会返回一个一次性支付token 。
Yuno 连接器通知 VTEX 应打开支付应用程序并提供一次性token。
VTEXIO 使用来自 Yuno 连接器的数据打开 Yuno 支付应用程序。
用户在 Yuno 支付应用程序中输入信用卡详细信息。
支付详情、浏览器信息和欺诈检测数据会被发回 Yuno 连接器。
付款在 Yuno 中创建并处理。
用户从 VTEX 收到付款状态确认。

VTEXIO中的Pix（APMs）支付流程

此流程说明了如何在 VTEXIO 中处理 Pix 和其他 APM，包括付款创建和重定向。

用户点击 VTEXIO 前端的支付按钮。
VTEX 后端将付款信息发送到 yunopartnerbr.yuno 连接器。
Yuno 连接器在 Yuno 系统中创建付款。
Yuno 生成 QR 码和其他付款详细信息，并将其返回给 VTEX。
VTEXIO 打开 Pix 应用程序或重定向用户以完成支付。

VTEX 无头架构

要在 VTEX Headless 签出中使用 Yuno，请安装：

yunopartnerbr.yuno:在 VTEXIO 服务器端运行的 VTEXIO PPF 连接器。

此外，还应实施SDK Web VTEX。该 SDK 支持使用两张信用卡付款。

VTEX无头支付流程

VTEX Headless 需要不同的付款处理方法。以下是在 VTEX Headless 中处理信用卡交易的步骤。

用户点击商家自定义前台的支付按钮。
VTEX 后端将付款信息发送到 yunopartnerbr.yuno 连接器。
Yuno 连接器将信用卡信息发送到 Yuno API。
Yuno API 会返回一个一次性支付token 。
Yuno 连接器通知 VTEX 应打开支付应用程序并提供一次性token。
商家前台使用提供的数据打开 Yuno SDK Web VTEX。
支付详情、浏览器信息和欺诈检测数据会被发送到 Yuno 连接器。
Yuno 连接器通过调用{{merchant’s domain}}/_v/yunopartnerbr.yuno/v4/payments/yuno.
用户从 VTEX 收到付款状态确认。

安装和使用VTEX Web SDK

Yuno SDK Web VTEX 允许与 VTEX 的支付基础设施无缝集成，使商家能够直接在其前端处理支付。

要集成 Yuno SDK Web for VTEX，请在 HTML 文件中包含脚本并配置必要的参数：

<!DOCTYPE html>
<html>
<head>
  <script src="https://sdk-web-vtex.y.uno/v1/main.js"></script>
</head>
<body>
  <div id="root-container"></div>
  <script>
    window.YunoVTEX.mount({  
      elementRoot: "root-container",  
      payload: '{}',  
      language: 'pt',
      domainVTEX: 'https://myvtex.yunopartnerbr.com',
      onPaymentDone: (paymentData) => { console.log(paymentData); },
      onError: (message, error) => { console.log(message, error); },
      onLoading: (loading) => { console.log(loading); }
    });
  </script>
</body>
</html>

下表描述了您可以使用的参数。

财产	类型	说明	需要	示例
`elementRoot`	字符串	HTML 元素 ID	正确	`"root-container"`
`payload`	字符串	来自我们的连接器响应	正确	`{"isVTEXCard":true, "checkoutSessions":["id"], "paymentIds":["id"], "orderId":"id"}`
`language`	字符串	ISO 639-1 语言代码	正确	`"pt"`
`domainVTEX`	字符串	商家的 VTEX 域名（如果与 VTEX 域名不同）	假的	`"https://myvtex.yunopartnerbr.com"`
`onLoading`	功能	SDK 处理付款时调用	假的	`function(loading) { console.log(loading); }`
`onPaymentDone`	功能	付款完成时调用	假的	`function(paymentResponse) { console.log(paymentResponse); }`
`onError`	功能	发生错误时调用	假的	`function(message, error) { console.log(error); }`

要获取 TypeScript 类型，请安装 npm 包装

npm install @yuno-payments/sdk-web-vtex

支付响应有效负载

通过以下方式处理付款时 Yuno 和 VTEX，"...... yunopartnerbr.yuno 连接器会生成一个结构化的有效负载，其中包含所有必要的交易细节。下面，我们提供了信用卡支付和 Pix 支付（APM）的有效载荷示例。

📘
有效载荷的生成和结构

自动生成：商家无需手动修改或格式化有效载荷。

动态结构：根据所选支付方式（信用卡、Pix 等）调整有效载荷格式。

无缝集成：在 VTEX 中处理交易时，Yuno 的连接器会自动检索数据。

有关详细信息，请访问API 参考。

信用卡支付有效负载

下面的 JSON 响应表示通过 Yuno 处理的信用卡支付授权。

{
  "status": "undefined",
  "authorizationId": null,
  "paymentAppData": {
    "appName": "yunopartnerbr.yuno-app",
    "payload": "{\"isVTEXCard\":true,\"checkoutSessions\":[\"acd5c64e-f4c6-4cde-a24d-840e2d7ed78c\"],\"paymentIds\":[\"6BB2F575BB1B493A9D3A3EBD8D8AA8D8\"],\"orderId\":\"1510060504991\",\"publicApiKeys\":[\"sandbox_gAAAAABmq_lv7XP4nR-1Wey4rNuph3vWrCxxDwXYB9_V28t2ZGiAJPBAiWRKUxCu1siekHoTkSTNWaUoi2kjfyVJHdPbqZ3mrKwwXHtwkEeOBYqiAGmGQ2-RXJT3-ay-XUrnRbAWwz_tnwU-CHrb1_Mh6GkBzWCvMaZqeGwjF3xVRCeGfrlZopW9mmB7G93d-Q7UBTIcQNIQi-llGl8VHR396GKiwZT8XGC0wYh5ZYzotUWs9KZ1PZkH1d-ow-Zw2tmsv8cuc3HJ\"],\"country_code\":\"BR\",\"paymentMethod\":\"Visa\",\"authorizations\":[{\"reference\":\"504991\",\"orderId\":\"1510060504991\",\"shopperInteraction\":\"ecommerce\",\"paymentMethod\":\"Visa\",\"value\":0,\"referenceValue\":148,\"currency\":\"BRL\",\"installments\":1,\"installmentsInterestRate\":0,\"installmentsValue\":148,\"ipAddress\":\"185.239.149.42\",\"miniCart\":{\"buyer\":{\"email\":\"[email protected]\",\"firstName\":\"Camilo\",\"lastName\":\"Segura\",\"document\":\"02678175928\",\"phone\":\"+5511912345678\"},\"shippingAddress\":{\"receiverName\":\"Camilo Segura\",\"postalCode\":\"89220555\",\"city\":\"Joinville\",\"state\":\"SC\",\"country\":\"BRA\",\"street\":\"Rua São Matias\",\"number\":\"1\"},\"billingAddress\":{\"postalCode\":\"89220555\",\"street\":\"Rua São Matias\",\"neighborhood\":\"Costa e Silva\",\"city\":\"Joinville\",\"state\":\"SC\",\"country\":\"BRA\",\"number\":\"1\"},\"items\":[{\"id\":\"17\",\"name\":\"BLACK + DECKER 20V Max Cordless Motosserra, 10 polegadas, ferramenta somente (LCS1020B)\",\"price\":138,\"quantity\":1}],\"shippingValue\":10,\"taxValue\":0},\"paymentId\":\"6BB2F575BB1B493A9D3A3EBD8D8AA8D8\",\"transactionId\":\"A09E2F38DD524C64B92CD5019D9A41E7\",\"callbackUrl\":\"https://yunopartnerbr.vtexpayments.com.br/payment-provider/transactions/A09E2F38DD524C64B92CD5019D9A41E7/payments/6BB2F575BB1B493A9D3A3EBD8D8AA8D8/retry\"}],\"sessions\":[\"ZjgyMzRmZTZmMDVkMzBkNTg2YjY5NzZjNDA2YTY0NTJmNTE2NWJiYTIyZjI3NjU2ZjRiNjg0YzNhZGZkZGQ5NTVjMzFhYWNkNDU1NzFlNTU1ZmQ1MmQ0MWQyYzdlZDM4MDNmNTQ4OTZhN2FiMmYyNTJhYzI4YzZkYzkxNTlmNDAzMmYwNmIyY2E1ZmM1OWE2OWZhOTUyNDY3NjI3YTM0OTQ5NmEyYTQwNzgzMTVhYmU2YTkzNDBhMTc2ZmFjNzY0NWU0ZjU3ZjBmNDIzNDVjNDJjM2MyNjBlZGIwMmQ2ZjkyMzc4OGEzODEzMjE0N2NhN2M0MTM4Y2RkMDAwNjRkYjkwNmQxMjAzZTdiNGNjODJlMjEzZjczZDliZDg3NTMxYjQzZjQ0ZmFiNDJlMmQ4M2UwYTg2YjJhZWNmMmNmYTYzNDY4ZDExZGE2YjAyZTMyYTA2MmI3ZWJlMzIyNjRkYWFlM2JjMTczNThiYmEyNzZkMGUzMzIzMDFlYjk4NTA4NzJjNTIwZjIxOWI5OWY3YTE3ZWJhNWFiMGI0YzYzNWEwNTMwMmQ4YzlmMmVhZGJiOTBlNmY1YTZjMzk3ZTU4M2E4NGU3YzMzMDI2YTczNzdmM2Y5ZWQwOWE3MGFiZjlmMDk4NzkwY2U5YTQ3MTQ1ZTY1MzhjYjU0N2ZhNjY4MDY2NDIxMjA5MWM3MDdhYzc4MDYwMzg0YzA4ODg2NzM0YzRjNzMwNzAyMGNiNWQxOTVlZTAxOWZiZWJhOTg4MWJhMTY2ODY1NDFjOWExMTdlM2M2OGJmMmE5OGI4OTBjYTBkYWIxZjI2ZDc5NDdmYzc2NDE0YjBmODNlNWFkM2RlYTFkNzM1ZmQzMGMxNTlmNTY5YTZmZTYwNGMxMjViMzY0ZTNkN2JmYTk0NWFmN2I2Y2ZiNTRjN2Y3Y2EwMzJjZGY1NDM4MTlhNTIwMTQ4MzY2YzI1YmUyYTk1M2VlYjFhZGE2YmQ5MWYxYjUxZGIwYjE1MWJhYmZmZmFjODgzMDNjNmY4OTBiMWMxZWViMzUwMmQ3NGIwZTljNDZlY2ZlMTkyNTgwZjYwNDcxZjQ5ZWEzMTEyODQyMjE2NDYxYzI0MzM5NjQ3MjU3NGQ5NTE2MGJiMDBhMjQxYThlNmM1ZDEwZDQ3NzFlNDM4YjNhNzZhMzkzNTIyZDNkNmE1YWQyNGY3MTc5ZGJjOWM4OGEzNmVhNjgzYmZiMGQ2YThjNDY4M2ZiNDRkNGJmODVmNzIyYThhMmNhZjY0NzRlMmYxYzYzMTFjNWQ1N2RhOWM3NmFhNmU5ZjJmZmEwODUxMDZmNDA4ZjJlMjkyN2VkZjRiMjRiYzk0ZGMxZTJiMzlhMzk5YjE4ZTUzNjYwZjhmMDJmNTVlZWVhYzdhOWE0MjIyMjBjOWM0NzQ1YTliOWQ0MjYxZmE0YjliMDcxNjhhM2NmZjA2NDRjNWEyZTQ1NWU5YjViMjAyY2NmNDI5MmU4OWEwNjgyZjdkODZkYTc3ZWE4YzEzYjVhODI3YzhjMmI0MWNiNTc1MjMwZTQzZjUzZjhlMTdmOTVjOTkxNmE0MWIwNmMzZDZkNjc2YTgxOTk2ZjZlMGEwNGZiZTMyYTIxMzk3YTdjYjhmNTRjYjJhZTNlYmNkYmI3Njc4ZTdiOWVjZDU3ZTkxZWI4NGY2MWUzNjQ0N2I1YzY4ODhmODVlYmQzY2Q4YjExY2E2M2RkNmUzOTAyZjgyNTRkMjcxZGU0MzI1YzUxMmViMTBkYTM4YTk3ZTMwMzM1N2ZkZmVkNDlkYTQ0MzQ1NjczZTJlNTljZDdkMmFlZGNjMWVlYjM4NWE3NjMyYjZkZjIxZDQ3M2I0ZTdmMzNhNTI3MDg1Y2M0OWEyYzVhZTRiZmVhYjg2MDVhZTQzZWIwY2ExM2RkMzc1MWE1MzQyMDMwMzc4ODI0YTZiMDQ4MjA0NjYwMmZmNmQ2ZDIwYTk4NGI1NWQ5MGU3ODBmODM2MGI5NGU4ZjNhNjYwNDlkZDZkNjBmN2NkMzAyOTZjNDczYjQwNTcyMjkyNWZh\"],
    \"account\":\"yunopartnerbr\"}"
  }
}

Pix支付有效负载

此示例显示了 Pix 支付响应，其中 Yuno 生成了文本格式和 base64 图像格式的二维码。

{
  "status": "undefined",
  "authorizationId": null,
  "paymentAppData": {
    "appName": "yunopartnerbr.yuno-app",
    "payload": {
      "code": "00020126830014br.gov.bcb.pix2561qr-code-h.picpay.com/pix/624ea025-9bb0-47ae-a620-6f2b9ba048815204000053039865802BR5912p2bpix teste6009Sao Paulo62070503***6304535D",
      "qrCodeBase64Image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAABWQAAAVkCAYAAABTjRaxAAAABGdBTUEAALGPC/xhBQAAAAFzUkdCAK7OHOkAAAAgY0hSTQAAeiYAAICEAAD6AAAAgOgAAHUwAADqYAAAOpgAABdwnLpRPAAAIABJREFUeJzs2ltu5TqWQMFmw/OfMuvz3vyoBFyil7YPIwZwsCU+bCxo7b33/wEAAAAA8OP+/+0BAAAAAABuIcgCAAAAAEQEWQAAAACAiCALAAAAABARZAEAAAAAIoIsAAAAAEBEkAUAAAAAiAiyAAAAAAARQRYAAAAAICLIAgAAAABEBFkAAAAAgIggCwAAAAAQEWQBAAAAACKCLAAAAABARJAFAAAAAIgIsgAAAAAAEUEWAAAAACAiyAIAAAAARARZAAAAAICIIAsAAAAAEBFkAQAAAAAigiwAAAAAQESQBQAAAACICLIAAAAAABFBFgAAAAAgIsgCAAAAAEQEWQAAAACAiCALAAAAABARZAEAAAAAIoIsAAAAAEBEkAUAAAAAiAiyAAAAAAARQRYAAAAAICLIAgAAAABEBFkAAAAAgIggCwAAAAAQEWQBAAAAACKCLAAAAABARJAFAAAAAIgIsgAAAAAAEUEWAAAAACAiyAIAAAAARARZAAAAAICIIAsAAAAAEBFkAQAAAAAigiwAAAAAQESQBQAAAACICLIAAAAAABFBFgAAAAAgIsgCAAAAAEQEWQAAAACAiCALAAAAABARZAEAAAAAIoIsAAAAAEBEkAUAAAAAiAiyAAAA**TRUNCATED**"
    }
  },
  "paymentId": "C9B4F5750BD24EF084E0C7EC0DB7AD16",
  "code": "UNDEFINED",
  "message": "Payment session started by Yuno"
}

支付元数据

通过VTEX连接器处理支付时，Yuno会在结账会话和支付创建过程中均包含元数据。这些元数据为交易提供了额外的背景信息。

卖家ID（联盟代码）

VTEX连接器捕获了 sellerId (联盟代码) 来自 VTEX 订单，并将其包含在结账会话和支付元数据中。这启用了市场追踪和联盟模式功能，使商家能够追踪其自有商店与合作伙伴市场之间的归因关系。

"(《世界人权宣言》) sellerId 在处理付款时，该字段会自动包含在元数据中：

"metadata": [
  {
    "key": "sellerId",
    "value": "[affiliate_code_from_vtex_order]"
  }
]

此功能对使用VTEX联盟模式参与市场平台的商家尤为实用。有关在VTEX中配置联盟的更多信息，请参阅VTEX关于配置联盟的文档。

VTEXIO集成

安装

所需管理员权限

安装 yunopartnerbr.yuno

安装 yunopartnerbr.yuno-app

安装适用于VTEX的Yuno SDK Web（可选）

支付流程

VTEXIO支付流程

VTEXIO中的信用卡支付流程

VTEXIO中的Pix（APMs）支付流程

VTEX 无头架构

VTEX无头支付流程

安装和使用VTEX Web SDK

支付响应有效负载

有效载荷的生成和结构

信用卡支付有效负载

Pix支付有效负载

支付元数据

卖家ID（联盟代码）

安装 `yunopartnerbr.yuno`

安装 `yunopartnerbr.yuno-app`