Pay By Bank 集成

概述

Pay By Bank 是面向英国市场的本地银行支付方式。本文档参考现有本地支付单方式页面结构，说明通过 Onerway 支付网关接入 Pay By Bank 的完整技术流程，从基础前提、关键参数，到重定向处理与 webhook 最终确认。

技术特性：

支付流程：重定向式
订单货币：GBP（英镑）
适用国家：GB（英国）
交易类型：一次性支付
集成方式：REST API

支持功能：

单次支付
银行选择页跳转
银行 App / 网银授权支付
webhook 异步结果通知

不支持：

分期交易
订阅支付

支付结果确认要求

Pay By Bank 的浏览器回跳仅表示客户从银行授权链路返回，不能作为最终支付成功依据：

同步响应：通常返回 status=R、paymentStatus=R 与 actionType=RedirectURL
前端职责：收到 redirectUrl 后立即跳转到银行选择页
回跳页面：建议展示 Processing / Pending 状态，等待最终确认
最终结果：必须以 webhook 为准；如 webhook 延迟，可调用交易订单查询兜底

技术前提条件

开始集成前，请确保您的系统满足以下技术要求：

基础设施要求

启用 HTTPS 的接口端点（TLS 1.2 或更高版本）
公网可访问的 webhook 接收端点
能够生成和验证 SHA256 签名
支持 UTF-8 字符编码

集成要求

已开通 Pay By Bank 的 Onerway 商户账号
API 凭证（商户号和密钥）
沙箱环境访问权限
支持 HTTP 重定向（302/303 状态码）

可选增强

回跳页的处理中状态展示
移动设备浏览器与银行 App 跳转测试
交易订单查询兜底逻辑

技术配置

步骤 1：API 凭证配置

从 Onerway 获取以下凭证信息：

merchantNo：商户唯一标识符
secretKey：用于请求/响应签名生成
API 端点 URL（沙箱和生产环境）

步骤 2：Webhook 配置

配置 webhook 端点以接收支付通知：

端点 URL：必须通过 HTTPS 公网访问
支持方法：POST
Content-Type：application/json
响应要求：返回 HTTP 200 状态码及包含 transactionId 的 JSON 响应体

Webhook 配置示例：

text

Webhook URL: https://your-domain.com/api/webhooks/onerway
Method: POST
Timeout: 30 秒
重试: 3 次（间隔 30 分钟）

步骤 3：返回 URL 配置

设置支付完成后的客户重定向 URL：

returnUrl：客户完成、取消或中断银行授权后回跳的地址
建议商户在 returnUrl 中自行拼接 merchantTxnId，便于回跳后主动发起交易订单查询
Pay By Bank 的 returnUrl 需要提前提交给 Onerway 加白，未加白的地址可能无法正常回跳
查询参数可能包含：transactionId、status、merchantTxnId

支付状态轮询

收到 returnUrl 回跳后，商户可以主动调用交易订单查询或相关查询接口验证最终状态，而不是仅依赖浏览器回跳参数。

集成流程

Pay By Bank 集成采用基于重定向的银行授权流程：

支付流程图

流程步骤说明

阶段 1：支付发起

客户选择 Pay By Bank 作为支付方式
商户向 Onerway API 发送支付请求
Onerway 创建支付会话
Onerway 返回重定向 URL

阶段 2：银行授权

商户将客户重定向到银行选择页
客户选择发卡银行或开户银行
页面拉起银行 App 或跳转至网银授权页
客户在银行侧完成支付确认
银行授权链路将客户返回到商户网站或聚合结果页

阶段 3：支付确认

银行授权链路向 Onerway 回传支付结果
Onerway 向商户发送 webhook
商户确认接收 webhook
商户向客户显示结果

重要提示

始终依赖 webhook 通知来获取最终支付状态
returnUrl 回跳可能早于最终状态确认
建议在回跳页展示处理中状态，并在后台等待 webhook 或主动查询

Pay By Bank 特殊要求

Pay By Bank 支付需要以下配置和参数：

lpmsInfo 配置

设置 lpmsInfo 参数标识使用 Pay By Bank：

json

"lpmsInfo": "{\"lpmsType\":\"PAY_BY_BANK\"}"

必填参数

以下参数在 Pay By Bank 支付中为关键参数：

billingInformation

最小必填：

country

推荐最小值：

json

"billingInformation": "{\"country\":\"GB\"}"

shippingInformation

最小必填：

country

推荐最小值：

json

"shippingInformation": "{\"country\":\"GB\"}"

lpmsInfo

最小必填：

lpmsType

不要求：

bankName
iban/iBan

对于 Pay By Bank，商户无需在下单时预先指定银行，银行选择会在后续重定向页中完成。

txnOrderMsg

必须包含以下字段：

returnUrl - 客户完成或中断授权后回跳的页面地址
notifyUrl - 接收最终支付结果的 webhook 地址
products - 商品信息，用于订单展示和对账

returnUrl 建议形如：

text

https://merchant.example.com/payments/return?merchantTxnId=1774494196000

这样商户在客户回跳后，可以直接用页面中已有的 merchantTxnId 发起交易订单查询。同时，该 returnUrl 需要提前报备给 Onerway 加白。

完整字段定义见 TxnOrderMsg

API 请求参数

POST

关键参数

对于 Pay By Bank 集成，您必须设置：

productType: LPMS
subProductType: DIRECT
lpmsInfo: JSON 字符串，包含 lpmsType 设置为 PAY_BY_BANK
orderCurrency: GBP

标准请求参数

完整的标准 LPMS 参数，请参考本地支付方式文档。

Parameter	Type	Length	Required	Signed	Description
billingInformation	String	/	Yes	Yes	Transaction billing information in JSON string format. See TransactionAddress for complete structure.
lpmsInfo	String	/	Conditional	Yes	Local payment method information in JSON string format. See LpmsInfo for complete structure.
merchantNo	String	20	Yes	Yes	Merchant number assigned by `Onerway` upon registration, obtained from the `Onerway` merchant dashboard.
merchantTxnId	String	64	Yes	Yes	Unique transaction identifier for each customer payment, generated by the merchant system.
merchantTxnOriginalId	String	128	No	Yes	Master transaction ID generated by merchant for grouping related transactions.
merchantTxnTime	String	/	No	Yes	Transaction timestamp when the merchant initiated the transaction.
merchantTxnTimeZone	String	64	No	Yes	Transaction timezone offset for the merchant transaction time.
metaData	String	2048	No	Yes	Merchant-defined custom data.
mpiInfo	String	/	Conditional	Yes	3DS verification result information in JSON string format. See MpiInfo for complete structure.
orderAmount	String	19	Yes	Yes	Transaction amount in the specified currency, formatted as a decimal string.
orderCurrency	String	8	Yes	Yes	Three-letter currency code according to ISO 4217 standard for the transaction amount.
osType	String	16	Conditional	Yes	Operating system type for mobile and app-based transactions. See OsTypeEnum for available options.
paymentMode	String	16	No	Yes	Payment mode indicating the platform or environment for the transaction. See PaymentModeEnum for all available options.
productType	String	16	Yes	Yes	Payment method category that determines which payment options are available to customers. See ProductTypeEnum for all available options.
risk3dsStrategy	String	16	Conditional	Yes	3DS risk control strategy for fraud prevention. See Risk3dsStrategyEnum for available options.
shippingInformation	String	/	Yes	Yes	Transaction shipping information in JSON string format. See TransactionAddress for complete structure.
sign	String	/	Yes	No	Digital signature string for request verification and security. Please refer to Signature for signature generation method.
subProductType	String	16	Yes	Yes	Specific implementation method within the selected product type, defining how the payment is processed. See SubProductTypeEnum for all available options.
subscription	String	/	Conditional	Yes	Subscription configuration in JSON format including frequency, billing cycle, and subscription type (managed / self-managed).
txnOrderMsg	String	/	Yes	Yes	Transaction business information in JSON string format. See TxnOrderMsg for complete structure.
txnType	String	16	Yes	Yes	Transaction type that defines the payment operation to be performed. See TxnTypeEnum for all available options and detailed usage scenarios.

lpmsInfo 参数说明

lpmsInfo 为 JSON 字符串，Pay By Bank 支付配置：

参数	类型	必填	说明
lpmsType	String	是	固定值 `PAY_BY_BANK`
bankName	String	否	当前方式不要求，建议省略
iban / iBan	String	否	当前方式不要求，建议省略

响应

API 返回标准的 Onerway 响应格式。对于 Pay By Bank 交易，需特别关注 status 、 paymentStatus 、 actionType 和 redirectUrl 字段以确定下一步操作。

Name	Type	Description
respCode	String	Response code from `Onerway`
respMsg	String	Response message from `Onerway`
data	Object	Response data. Refer to object data

data

响应中的 data 对象包含交易的详细信息：

Name	Type	Description
transactionId	String	Transaction ID created by `Onerway`
paymentId	String	Payment intent ID
responseTime	String	Response timestamp Format: `yyyy-MM-dd HH:mm:ss`
txnTime	String	Transaction initiation time Format: `yyyy-MM-dd HH:mm:ss`
txnTimeZone	String	Transaction timezone Format: `+/-HH:mm`
orderAmount	String	Order amount
orderCurrency	String	Order currency Refer to ISO 4217 currency codes
txnAmount	String	Settlement amount
txnCurrency	String	Settlement currency Refer to ISO 4217 currency codes
status	String	Transaction status Refer to TxnStatusEnum
paymentStatus	String	Payment intent status Refer to PaymentStatusEnum
redirectUrl	String	Payment redirect URL
contractId	String	Subscription contract ID
tokenId	String	Payment token
eci	String	Electronic Commerce Indicator
periodValue	String	Installment periods
codeForm	String	Code form See CodeFormEnum
presentContext	String	Presentation context
actionType	String	Required action See ActionTypeEnum
subscriptionManageUrl	String	Subscription management URL
sign	String	Response signature Refer to the Signature documentation

响应处理

Pay By Bank 交易通常返回 status=R 、 paymentStatus=R 和 actionType=RedirectURL 。您必须立即将客户重定向到 redirectUrl ，并在回跳页等待 webhook 最终确认。

API 使用示例

标准支付请求

请求响应 - 重定向异步通知

json

{
  "billingInformation": "{\"country\":\"GB\"}", // 最小账单信息
  "lpmsInfo": "{\"lpmsType\":\"PAY_BY_BANK\"}", // Pay By Bank 标识
  "merchantNo": "<MERCHANT_NO>", // Onerway 商户号
  "merchantTxnId": "1774494196000", // 唯一交易 ID
  "orderAmount": "10",
  "orderCurrency": "GBP", // 英镑
  "productType": "LPMS", // 本地支付方式
  "shippingInformation": "{\"country\":\"GB\"}", // 最小收货信息
  "sign": "<SIGNATURE>", // 请求签名
  "subProductType": "DIRECT", 
  "txnOrderMsg": "{\"returnUrl\":\"https://merchant.example.com/payments/return?merchantTxnId=1774494196000\", \"products\":\"[{\\\"price\\\":\\\"10.00\\\", \\\"num\\\":\\\"1\\\", \\\"name\\\":\\\"iphone11\\\", \\\"currency\\\":\\\"GBP\\\"}]\", \"transactionIp\":\"127.0.0.1\", \"appId\":\"<APP_ID>\", \"javaEnabled\":false, \"colorDepth\":\"24\", \"screenHeight\":\"1080\", \"screenWidth\":\"1920\", \"timeZoneOffset\":\"-480\", \"accept\":\"text/html, application/xhtml+xml, application/xml; q=0.9, image/avif, image/webp, image/apng, */*; q=0.8\", \"userAgent\":\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36\", \"contentLength\":\"340\", \"language\":\"en-US\", \"notifyUrl\":\"https://merchant.example.com/webhook/payment\"}", // 建议在 returnUrl 中拼接 merchantTxnId，且该地址需提前加白
  "txnType": "SALE"
}

json

{
  "respCode": "20000", // 成功代码
  "respMsg": "Success",
  "data": {
    "transactionId": "2037002425390727168", // Onerway 交易 ID
    "paymentId": "2037002425365561344", // 支付意图 ID
    "responseTime": "2026-03-26 11:03:21",
    "orderAmount": "10.00",
    "orderCurrency": "GBP",
    "status": "R", // 需要重定向
    "paymentStatus": "R", // 支付意图处理中
    "redirectUrl": "https://payment-gateway.example.com/payments?payment_id=59af7f48-fa7a-4f1e-880f-a09d2f2e76d7&resource_token=<RESOURCE_TOKEN>&return_uri=https://sandbox-gw-dmz.onerway.com/front/return/0000000011", // 银行选择页 URL
    "periodValue": null,
    "codeForm": null,
    "presentContext": null,
    "actionType": "RedirectURL", // 操作类型：重定向
    "subscriptionManageUrl": null,
    "sign": "<RESPONSE_SIGNATURE>"
  }
}

json

{
  "channelRequestId": "0000000008",
  "merchantNo": "<MERCHANT_NO>",
  "merchantTxnId": "1774494196000",
  "notifyType": "TXN",
  "orderAmount": "10.00",
  "orderCurrency": "GBP",
  "paymentId": "2037002425365561344", // 支付意图 ID
  "paymentMethod": "PAY_BY_BANK", // 支付方式
  "paymentMethodDetails": "{\"card\":{\"checks\":null, \"holderName\":null, \"year\":null, \"month\":null, \"cardType\":null, \"productCategory\":null, \"issuer\":null, \"cardBinCountry\":null, \"authorizationCode\":null, \"cardNumber\":null}}",
  "paymentStatus": "S", // 支付意图成功
  "reason": "{\"respCode\":\"20000\", \"respMsg\":\"Success\"}",
  "responseTime": "2026-03-26 11:12:27",
  "sign": "<WEBHOOK_SIGNATURE>", // 验证签名
  "status": "S", // 交易成功
  "transactionId": "2037002425390727168", // Onerway 交易 ID
  "txnTime": "2026-03-26 11:03:21",
  "txnTimeZone": "+08:00",
  "txnType": "SALE"
}

技术集成检查清单

生产环境部署前：

API 集成

支付请求 API 已实现并测试
请求签名生成正常工作
错误响应处理已实现
重定向流程已实现（处理 status=R 和 actionType=RedirectURL）

Pay By Bank 特殊要求

lpmsInfo 使用 {"lpmsType":"PAY_BY_BANK"}
billingInformation 至少包含 country=GB
shippingInformation 至少包含 country=GB
未在请求中错误依赖 bankName 或 iban/iBan
txnOrderMsg 已配置 returnUrl
returnUrl 已拼接 merchantTxnId 以便回跳后主动查询
returnUrl 已提前报备给 Onerway 加白
txnOrderMsg 已配置 notifyUrl
回跳页已实现 Processing / Pending 展示

Webhook 实现

Webhook 端点通过 HTTPS 公网可访问
Webhook 签名验证已实现
幂等性 webhook 处理已实现
Webhook 确认返回 HTTP 200 及 transactionId
webhook 最终状态落库已实现

安全性

已启用 TLS 1.2 或更高版本
API 凭证安全存储
签名验证已测试
敏感数据不以明文记录日志

测试验证

成功支付场景已测试
失败支付场景已测试
用户取消或中断授权场景已测试
webhook 接收已测试
回跳页处理中状态已测试
移动设备银行 App 跳转流程已测试

监控与运维

API 请求/响应日志已实现
错误监控和告警已配置
paymentId / transactionId 状态跟踪已实现
交易订单查询兜底逻辑已实现

技术支持

如需技术集成协助，请联系 Onerway 技术支持，并提供您的 merchantNo 和具体技术问题。

收银台

下单

WebSDK

Android

绑卡支付

订阅支付

本地支付

Apple Pay

Google Pay

Pay By Bank 集成 ​

概述 ​

技术前提条件 ​

基础设施要求 ​

集成要求 ​

可选增强 ​

技术配置 ​

步骤 1：API 凭证配置 ​

步骤 2：Webhook 配置 ​

步骤 3：返回 URL 配置 ​

集成流程 ​

支付流程图 ​

流程步骤说明 ​

阶段 1：支付发起 ​

阶段 2：银行授权 ​

阶段 3：支付确认 ​

Pay By Bank 特殊要求 ​

lpmsInfo 配置 ​

必填参数 ​

billingInformation ​

shippingInformation ​

lpmsInfo ​

txnOrderMsg ​

API 请求参数 ​

标准请求参数 ​

lpmsInfo 参数说明 ​

响应 ​

data ​

API 使用示例 ​

标准支付请求 ​

技术集成检查清单 ​

API 集成 ​

Pay By Bank 特殊要求 ​

Webhook 实现 ​

安全性 ​

测试验证 ​

监控与运维 ​

Pay By Bank 集成

概述

技术前提条件

基础设施要求

集成要求

可选增强

技术配置

步骤 1：API 凭证配置

步骤 2：Webhook 配置

步骤 3：返回 URL 配置

集成流程

支付流程图

流程步骤说明

阶段 1：支付发起

阶段 2：银行授权

阶段 3：支付确认

Pay By Bank 特殊要求

lpmsInfo 配置

必填参数

billingInformation

shippingInformation

lpmsInfo

txnOrderMsg

API 请求参数

标准请求参数

lpmsInfo 参数说明

响应

data

API 使用示例

标准支付请求

技术集成检查清单

API 集成

Pay By Bank 特殊要求

Webhook 实现

安全性

测试验证

监控与运维