集成一个 White Label 加密支付网关 不仅仅是连接到一个 API。这意味着在保持客户体验控制权的同时，为您的网站或应用添加一个完整的 加密支付流程 。
借助 OxaPay White Label，企业可以在自己的界面中显示支付地址、二维码、金额、网络和支付状态。同时，OxaPay 负责底层支付基础设施，包括支付创建、 区块链监控以及交易更新。
这种方式让企业无需自行构建和维护区块链支付基础设施，也能以自己的品牌提供加密支付。
本指南将介绍如何集成 OxaPay White Label 网关、企业在开始前需要做好哪些准备，以及上线前应考虑哪些支付场景。
White Label 适合您的企业吗？
开始集成之前，需要先判断 White Label 方案是否是 适合您支付流程的选择.
一个 托管式加密支付页面 通常足以满足希望 快速开始接受加密货币的企业。在这种模式下，客户会被重定向到由支付网关提供的支付页面来完成交易。
当支付体验是产品或客户旅程的重要组成部分时，White Label 更合适。您无需把客户重定向到外部支付页面，而是可以在自己的网站、应用、平台或结账流程中直接展示支付信息。
这种方案特别适合希望实现以下目标的企业：
- 在整个结账过程中保持一致的品牌体验
- 让客户始终留在自己的平台内
- 控制支付说明和支付状态的展示方式
- 将加密支付连接到现有订单流程
- 避免从零开始构建区块链支付基础设施
核心区别在于控制程度。您的企业负责面向客户的体验，而 OxaPay 负责背后的支付基础设施。
开始前需要准备什么
White Label 集成需要一定准备，但企业无需运行区块链节点，也无需自行构建交易监控系统。
您的网站或应用应具有能够安全连接到 OxaPay API的后端，用于存储支付信息并将每笔支付关联到正确的订单。
您还需要一个 callback endpoint ，用于接收 OxaPay 的支付更新。这些更新可以让系统知道客户何时开始付款，以及付款何时完成。
最后，支付界面应能够展示以下关键信息：
- 支付金额
- 所选加密货币
- 区块链网络
- 支付地址
- 二维码
- 剩余支付时间
- 最新支付状态
界面应清晰展示这些信息，尤其是所选网络和到期时间，因为这些环节中的错误可能导致支付问题。
使用 OxaPay 集成 White Label 加密支付网关
1. 创建 OxaPay Merchant 账户
第一步是创建 OxaPay 账户并进入 Merchant 控制面板。
在控制面板中，您可以管理 Merchant API Key、支付设置、支持的货币、交易记录以及其他商户工具。
在此阶段，您是在准备企业账户与 OxaPay 通信。无需为每个订单创建单独的区块链钱包，也无需自行构建交易监控系统。
2. 生成 Merchant API Key
接下来，从 OxaPay 账户生成一个 Merchant API Key 。
该密钥用于验证系统发送到 OxaPay API 的支付请求。它应始终 安全存储 在您的后端服务器上。
Merchant API Key 不应放在前端代码、公开代码仓库、浏览器脚本或任何客户可访问的位置。
后端在创建 White Label 支付请求时应使用该密钥。前端只应接收向客户展示所需的支付信息。
3. 创建 White Label 支付请求
要生成一笔 White Label 支付，系统需要向以下 endpoint 发送请求：
POST https://api.oxapay.com/v1/payment/white-label两个必填支付字段是：
金额：支付金额pay_currency：用于支付的加密货币
还可以根据您的支付流程添加其他字段。
例如：
currency定义订单定价所使用的货币，例如 USD。网络在加密货币支持多个网络时选择区块链网络。order_id将支付关联到您系统中的订单。callback_url告诉 OxaPay 将支付更新发送到哪里。lifetime定义支付保持有效的时间。under_paid_coverage定义请求金额与实际收到金额之间允许的差额。
根据 currency, 网络, order_id，以及 callback_url 字段在 API 中是可选的。不过，对于需要可靠订单追踪的企业，强烈建议使用订单 ID 和 callback URL。
请求成功后，OxaPay 会创建一个支付会话，并返回系统展示支付所需的信息。
4. 接收并展示支付信息
创建支付请求后，OxaPay 会返回结构化的支付信息。
其中可能包括：
- 一个唯一的
track_id - 准确支付金额
- 支付所使用的加密货币
- 区块链网络
- 支付地址
- 一个二维码
- 到期时间
您的系统应存储 track_id ，并将其关联到正确的内部订单。该标识符可以帮助企业追踪支付，并在需要时进行后续排查。
随后，前端可以使用返回的信息创建带有自身品牌的支付页面。
客户应能够：
- 扫描二维码
- 复制支付地址
- 复制准确金额
- 查看所需的加密货币和网络
- 查看剩余时间
- 跟踪当前支付状态
这是 White Label 模式的主要优势。客户可以在由您的企业设计并带有自身品牌的体验中完成付款。
支付页面还应提醒客户，支付到期后不要再发送资金。根据 OxaPay 文档，生成的 White Label 地址只在指定的支付 lifetime 内有效。
5. 跟踪支付状态
客户发送加密货币后，OxaPay 会监控该支付并报告其进度。
OxaPay 支付状态 可能包括以下状态：
- 等待支付
- 支付进行中
- paid
- underpaid
- expired
- 手动接受
- refunded
企业无需向客户展示每一个内部状态。界面可以将这些状态转化为简单信息，例如“等待支付”“已检测到支付”“支付完成”或“支付已过期”。
重要的是，系统不应过早完成订单。
当检测到支付活动时，OxaPay 会发送 paying 更新。通常，系统应等待最终 paid 状态，再交付产品、激活服务或将订单标记为已完成。
6. 接收并验证支付更新
OxaPay 会将支付更新发送到支付请求中包含的 callback_url 。
这些通知使系统能够：
- 识别对应支付
- 更新内部订单状态
- 向客户告知进度
- 在支付成功后完成订单
由于 callback endpoint 可公开访问，系统应在采取操作前 验证传入通知 。
OxaPay 会随 callback 提供一个 安全签名 。技术团队应验证该签名，并确认支付信息与已存储的订单信息一致。
这些步骤无需向客户展示，但它们是保护支付流程的重要部分。
系统还应能够处理同一更新被多次接收的情况。重复 callback 不得导致产品重复交付、余额重复入账或订单被多次确认。
如果系统未能成功确认 callback 已收到，OxaPay 可能会重新发送。
少付处理
有时客户发送的金额可能少于要求的支付金额。
OxaPay 提供少付容差选项，允许商户设置预期金额与实际收到金额之间可接受的差额。
如果差额在允许范围内，支付可以按照配置的策略继续。如果金额低于允许阈值，则可能需要采取其他处理措施。
根据您的业务模式，可以：
- 要求客户补齐剩余金额
- 手动审核支付
- 根据内部政策接受该支付
- 在适当情况下取消订单或退款
少付不应自动按照失败支付来处理。应建立清晰流程，让客户和支持团队都知道下一步如何处理。
7. 测试完整支付流程
上线集成之前，请测试 完整客户旅程 ，从创建支付一直到订单完成。
测试应包括：
- 成功创建支付
- 正确显示地址和二维码
- 准确的支付金额和网络信息
- 支付状态更新
- 成功完成订单
- 已过期支付
- 少付场景
- 重复支付通知
- 延迟的支付更新
您还应检查支付页面在移动设备上的表现。许多客户会用另一台设备扫描二维码，或直接把地址复制到移动钱包中。
仅测试最初的 API 请求并不够。包括支付更新和履约在内的完整订单流程，应在向客户开放集成之前可靠运行。
重要集成注意事项
可靠的 White Label 支付体验取决于一些实际细节。
到期处理
支付到期后，系统应停止将其显示为有效状态。应允许客户创建新的支付请求，而不是继续使用已经过期的支付信息。
正确选择网络
如果某种加密货币支持多个网络，请清晰显示所选网络。
如果客户通过错误网络发送资金，可能需要联系支持团队，而且资金不一定能够恢复。清晰的说明可以避免很多此类错误。
清晰的支付说明
客户应立即明确：
- 应发送哪种加密货币
- 应使用哪个网络
- 应发送多少
- 应发送到哪里
- 支付可以保持有效多长时间
- 支付后会发生什么
清晰的支付页面可以减少困惑，并提供更可靠的结账体验。
White Label 集成流程
完整流程可以概括为七个步骤：
- 您的系统创建一个内部订单。
- 后端向 OxaPay 发送 White Label 支付请求。
- OxaPay 返回支付详情。
- 您的网站或应用在自身界面中展示支付。
- 客户发送要求的加密货币。
- OxaPay 监控交易并发送支付更新。
- 系统确认支付并完成订单。
结论
集成 OxaPay White Label 加密支付网关，可以让企业在无需自行构建 底层区块链基础设施 的情况下掌控支付体验。
OxaPay 负责支付创建、交易监控和支付更新。您的企业负责品牌展示、客户界面、订单管理以及最终履约。
逻辑很简单：客户体验由您的企业掌控，而背后的支付基础设施由 OxaPay 提供。
通过清晰的支付页面、可靠的状态跟踪和充分测试，White Label 集成可以为客户提供一致的加密支付体验，并与您的网站或应用保持完整连接。
