本地支付方式

本地支付方式（LPMs）提供信用卡之外的多种支付选择，使商户能够接受各国流行的本地化支付方式。这些支付方式可能包括电子钱包、银行转账、二维码支付以及其他本地支付选项。

本地支付优势

更广泛的市场覆盖：接受偏好或仅使用本地支付方式的客户的付款
更高的转化率：提供客户熟悉和信任的支付选项
更低的处理费用：许多本地支付方式的处理成本低于信用卡
降低欺诈风险：大多数本地支付方式内置安全验证机制

API请求参数

POST

本地支付的关键参数

集成本地支付方式时，您需要设置以下关键参数：

productType：所有本地支付交易必须设置为 LPMS。
lpmsInfo：JSON格式字符串，包含本地支付方式详情，包括 lpmsType 和特定字段。
subscription：适用于支持订阅功能的本地支付方式（如 DANA、WeChat）。
subProductType：对于支持订阅功能的本地支付方式，必须设置为 SUBSCRIBE。

注意

所有 JSON 字段必须在提交前进行字符串化处理
嵌套对象必须序列化为 JSON 字符串格式
JSON 字段不能包含未转义的特殊字符
JSON 中的数组应该正确格式化
JSON 字符串字段示例：

json

{
  "object": "{\"obj-key1\":\"v1\",\"obj-key2\":\"v2\"}",
  "complex": "{\"k1\":\"v1\",\"array\":\"[{\\\"obj-key3\\\":\\\"v3\\\",\\\"obj-key4\\\":\\\"v4\\\"}]\"}"
}

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.
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.

TransactionAddress

Name	Type	Length	Required	Signature	Description
firstName	String	64	No	No	Customer first name.
lastName	String	64	No	No	Customer last name.
jpFirstName	String	64	No	No	First name in Japanese Katakana.
jpLastName	String	64	No	No	Last name in Japanese Katakana.
phone	String	32	No	No	Customer phone number in international format.
email	String	256	Yes	No	Customer email address.
postalCode	String	32	No	No	Postal/ZIP code.
address	String	256	No	No	Full address in a single field.
country	String	64	Yes	No	Country in ISO 3166-1 alpha-2 format. See ISO 3166.
province	String	64	Conditional	No	Province/State code. Required when country is `US` or `CA`. See ISO 3166.
city	String	64	No	No	City name.
street	String	64	No	No	Street name.
number	String	64	No	No	House/Building number.
identityNumber	String	64	No	No	Government-issued ID number.
birthDate	String	64	No	No	Birth date in `yyyy-MM-dd` format.

LpmsInfo

Name	Type	Length	Required	Signature	Description
lpmsType	String	64	Yes	No	Local payment method type. Please refer to LpmsTypeEnum for all supported payment methods.
bankName	String	128	Conditional	No	Bank name. When `lpmsType` is `EFT`, please refer to EFTBankNameEnum for supported banks. When `lpmsType` is `Przelewy24`, please refer to Przelewy24BankNameEnum for valid Polish bank options.
walletAccountId	String	/	Conditional	No	Wallet/local account identifier. Required in these scenarios: When `productType` is `LPMS` and `lpmsType` is `ATM_CARD`, provide the local bank account number. When `productType` is `PAYMENT_CODE`, provide the wallet payment code.
walletAccountName	String	/	Conditional	No	Wallet/local account name. Required when `productType` is `LPMS` and `lpmsType` is `ATM_CARD`, provide the local bank account holder name.
iBan	String	64	Conditional	No	International Bank Account Number (IBAN). Required for transfers in regions that use IBAN for bank identification.
prepaidNumber	String	/	Conditional	No	Prepaid card or voucher number. Required for certain Japanese payment methods like `BitCash` (16 digits), `Net_Cash` (16 digits), and `WebMoney` (19 digits).

Subscription

本地支付方式的订阅支持

以下本地支付方式目前支持订阅支付：

DANA
WeChat
GCash
TOUCH_GO_EWALLET

这些支付方式遵循两步流程：

初始零金额订阅注册（合同建立）
使用已建立的合同和token进行后续扣款

Name	Type	Length	Required	Description
requestType	String	1	Yes	Subscription request type. See RequestTypeEnum
merchantCustId	String	40	Yes	Unique identifier for the user in the merchant's system, used to associate the user with subscription information. This ID will be used for subscription creation, query, and management. Please ensure its uniqueness in your system.
productName	String	256	Conditional	Subscription product name, used to distinguish different subscription services or plans. If not provided, each user can only create one subscription; if provided, the same user can subscribe to multiple different products.
frequencyType	String	1	Yes	Subscription cycle unit: Self-managed subscription mode only supports `D` (day).
frequencyPoint	String	2	Yes	Suggested subscription cycle value, indicating how many days between billings.
expireDate	String	10	Yes	Subscription termination date, format is `yyyy-MM-dd`. After this date, the system will not allow any further subscription charges.
mode	String	1	Yes	Subscription authorization mode. See SubscriptionModeEnum
selfExecute	String	1	Yes	Subscription billing mode. See SubscriptionExecuteModeEnum

仅签约模式立即计费模式续费计费请求本地支付订阅

json

// 自主管理订阅 - 仅签约模式，不立即计费
// 适用于本地支付方式如微信、DANA、GCash或TOUCH_GO_EWALLET

"subscription": "{\"requestType\":\"0\",\"merchantCustId\":\"custId_xxx\",\"productName\":\"自主管理-仅签约\",\"frequencyType\":\"D\",\"frequencyPoint\":\"1\",\"expireDate\":\"2025-01-01\",\"selfExecute\":\"2\",\"mode\":\"1\"}"

json

// 自主管理订阅 - 立即计费模式，立即计费
// 通常用于信用卡支付或某些本地支付方式

"subscription": "{\"requestType\":\"0\",\"merchantCustId\":\"custId_xxx\",\"productName\":\"自主管理-立即计费\",\"frequencyType\":\"D\",\"frequencyPoint\":\"1\",\"expireDate\":\"2025-01-01\",\"selfExecute\":\"2\",\"mode\":\"2\"}"

json

// 自主管理订阅 - 续费计费，使用现有订阅合约发起新的计费周期
// 使用初始订阅webhook收到的contractId和tokenId

"subscription": "{\"requestType\":\"1\",\"contractId\":\"contractId_xxx\",\"tokenId\":\"tokenId_xxx\",\"merchantCustId\":\"custId_xxx\"}"

json

// DANA、微信、GCash或TOUCH_GO_EWALLET订阅示例
// 零金额初始交易以建立合约

"lpmsInfo": "{\"lpmsType\":\"DANA\",\"iBan\":\"DE89370400440532013000\"}",
"productType": "LPMS",
"subProductType": "SUBSCRIBE",
"subscription": "{\"requestType\":\"0\",\"merchantCustId\":\"custId_xxx\",\"frequencyType\":\"D\",\"frequencyPoint\":\"1\",\"expireDate\":\"2025-01-01\",\"selfExecute\":\"2\",\"mode\":\"1\"}"

自主管理订阅特性

手动扣款：商户必须手动发起所有后续扣款，Onerway不会自动处理未来付款
无客户管理界面：不提供 subscriptionManageUrl，因此客户无法通过Onerway平台管理订阅
无邮件通知：系统不会自动向客户发送订阅确认邮件
订阅资源管理：商户必须安全存储 contractId 和 tokenId 以便进行未来扣款操作
后续扣款流程：商户需要参考订阅续费文档来发起后续扣款

TxnOrderMsg

Name	Type	Length	Required	Signature	Description
returnUrl	String	256	Yes	No	Synchronous return address. After payment completion, customer is redirected to this URL
products	String	1024	Yes	No	List of product information purchased by the customer See Products for complete structure.
transactionIp	String	64	Conditional	No	Cardholder transaction `IP`
appId	String	20	Yes	No	Store `ID`. Unique identifier generated when merchant registers with `Onerway`. Obtained from dashboard.
javaEnabled	Boolean	/	Conditional	No	Whether the cardholder's browser has `java` enabled, retrieved via: `window.navigator.javaEnabled()`
colorDepth	String	64	Conditional	No	Cardholder screen color depth, retrieved via: `window.screen.colorDepth`
screenHeight	String	64	Conditional	No	Cardholder's screen resolution, retrieved via: `window.screen.height`
screenWidth	String	64	Conditional	No	Cardholder's screen resolution, retrieved via: `window.screen.width`
timeZoneOffset	String	64	Conditional	No	Cardholder browser's time zone, retrieved via: `((new Date()).getTimezoneOffset()).toString()`
accept	String	2048	Conditional	No	Cardholder browser's `Accept` request header
userAgent	String	2048	Conditional	No	Cardholder's browser type, retrieved via: `window.navigator.userAgent`
contentLength	String	64	Conditional	No	Content length of the cardholder's browser content beyond the headers
customerPlatform	String	128	Conditional	No	Merchant platform identifier
language	String	64	Conditional	No	Cardholder's browser language, retrieved via: `window.navigator.language`
periodValue	String	/	Conditional	No	Installment payment period.
notifyUrl	String	256	Yes	No	Notification URL. See Notifications

Products

Name	Type	Length	Required	Description
name	String	256	Yes	Product name
price	String	1024	Yes	Product unit price
num	String	20	Yes	Product quantity
productAvatarUrl	String	255	Conditional	Product image URL
desc	String	1024	No	Product description
currency	String	256	Yes	Currency code following ISO 4217 standard
type	String	256	Conditional	Product category. See StoreProductTypeEnum

products 必须为 JSON 字符串格式

示例：

如果type为discount，折扣金额应作为负数传递

json

\"[{\\\"name\\\":\\\"Pro1\\\",\\\"price\\\":\\\"50.00\\\",\\\"num\\\":\\\"2\\\",\\\"currency\\\":\\\"USD\\\"},{\\\"name\\\":\\\"Pro2\\\",\\\"price\\\":\\\"100\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\"}]\"

json

\"[{\\\"name\\\":\\\"Pro1\\\",\\\"price\\\":\\\"50.00\\\",\\\"num\\\":\\\"2\\\",\\\"currency\\\":\\\"USD\\\"},{\\\"name\\\":\\\"Pro2\\\",\\\"price\\\":\\\"100\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\"},{\\\"name\\\":\\\"discount\\\",\\\"price\\\":\\\"-10\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\",\\\"type\\\":\\\"discount\\\"}]\"

json

\"[{\\\"name\\\":\\\"Pro1\\\",\\\"price\\\":\\\"50.00\\\",\\\"num\\\":\\\"2\\\",\\\"currency\\\":\\\"USD\\\"},{\\\"name\\\":\\\"Pro2\\\",\\\"price\\\":\\\"100\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\"},{\\\"name\\\":\\\"shipping fee\\\",\\\"price\\\":\\\"10\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\",\\\"type\\\":\\\"shipping_fee\\\"}]\"

json

\"[{\\\"name\\\":\\\"Pro1\\\",\\\"price\\\":\\\"50.00\\\",\\\"num\\\":\\\"2\\\",\\\"currency\\\":\\\"USD\\\"},{\\\"name\\\":\\\"Pro2\\\",\\\"price\\\":\\\"100\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\"},{\\\"name\\\":\\\"shipping fee\\\",\\\"price\\\":\\\"10\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\",\\\"type\\\":\\\"shipping_fee\\\"},{\\\"name\\\":\\\"discount\\\",\\\"price\\\":\\\"-10\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\",\\\"type\\\":\\\"discount\\\"}]\"

json

\"[{\\\"name\\\":\\\"Pro1\\\",\\\"price\\\":\\\"50.00\\\",\\\"num\\\":\\\"2\\\",\\\"currency\\\":\\\"USD\\\",\\\"type\\\":\\\"physical\\\"},{\\\"name\\\":\\\"Pro2\\\",\\\"price\\\":\\\"100\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\",\\\"type\\\":\\\"physical\\\"}]\"

json

\"[{\\\"name\\\":\\\"游戏点数\\\",\\\"price\\\":\\\"25.00\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\",\\\"type\\\":\\\"virtual\\\"},{\\\"name\\\":\\\"高级会员\\\",\\\"price\\\":\\\"49.99\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"USD\\\",\\\"type\\\":\\\"virtual\\\"}]\"

注意：price * num (商品金额) + price * num (折扣金额) + price * num (运费) = orderAmount (订单交易金额)

响应参数

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

data

Name	Type	Description
transactionId	String	Transaction order number created by `Onerway`
responseTime	String	Interface response time Format: `yyyy-MM-dd HH:mm:ss`
txnTime	String	Transaction completion time Format: `yyyy-MM-dd HH:mm:ss`
txnTimeZone	String	Transaction time zone Format: `+/-HH:mm`
orderAmount	String	Order amount
orderCurrency	String	Transaction order currency Refer to ISO 4217 currency codes
txnAmount	String	Order amount after conversion to settlement currency
txnCurrency	String	Settlement currency Refer to ISO 4217 currency codes
status	String	Transaction processing result Refer to TxnStatusEnum
redirectUrl	String	Redirection URL for 3D Secure verification
contractId	String	Subscription contract number
tokenId	String	Payment token
eci	String	Electronic Commerce Indicator
periodValue	String	Installment payment number of periods
codeForm	String	Code form for specific payment methods See CodeFormEnum
presentContext	String	Context information for presentation layer
actionType	String	Action type for the transaction See ActionTypeEnum
subscriptionManageUrl	String	Subscription management URL
sign	String	Signature string Refer to the Signature interface

本地支付集成流程

本地支付集成流程包含以下三个主要阶段：

1. 支付发起

在此阶段：

客户在商户网站/应用上选择本地支付方式
商户系统收集并将支付数据传输到Onerway
支付请求包含 lpmsInfo 参数，通过 lpmsType 指定所选支付方式
productType 设置为 LPMS，subProductType 通常设置为 DIRECT
商户负责根据客户的地区/货币展示可用的支付选项

2. 支付处理

在此阶段：

Onerway处理支付请求并生成支付订单
Onerway返回 status=R 和指向本地支付平台的 redirectUrl
商户必须重定向客户以完成支付
支付完成后，本地支付平台将客户重定向回商户的 returnUrl
returnUrl 将包含查询参数，如 transactionId 和 status 以指示支付状态
最终支付结果通过webhook发送到商户的 notifyUrl

支付时效

某些本地支付方式并非即时到账。webhook通知仅在支付达到最终状态时发送。商户应相应设计其用户体验。

3. 支付结果通知

在此阶段：

Onerway通过HTTP POST 将详细支付结果数据发送到 notifyUrl
webhook包含完整的交易信息，包括 transactionId、status、paymentMethod 和用于验证的 signature
商户系统必须响应 transactionId 以确认收到webhook
如果未收到成功响应，Onerway将以30分钟间隔重试发送webhook，最多重试 3 次

4. 本地支付的订阅流程

对于支持订阅的本地支付方式，流程包含额外步骤：

订阅集成涉及：

初始订阅设置：
- 商户发送带有 subProductType=SUBSCRIBE 和订阅配置的请求
- 客户授权与本地支付提供商的订阅协议
- 商户收到包含 txnType=BIND_CARD、orderAmount=0.00 和 scenarios=SUBSCRIPTION_INITIAL 的webhook
- 必须存储关键值（contractId 和 tokenId）以用于未来扣款
周期性扣款：
- 根据订阅频率，Onerway使用存储的token发起扣款
- 商户收到包含 txnType=SALE 和实际扣款金额的webhook
- 来自初始设置的相同 contractId 和 tokenId 包含在这些webhook中

订阅支持限制

并非所有本地支付方式都支持订阅。目前，只有 DANA、WeChat、GCash 和 TOUCH_GO_EWALLET 提供订阅功能。每种方式可能有特定的要求或限制。

API使用示例

标准本地支付请求（DANA）

请求响应Webhook回调

json

{
  "billingInformation": "{\"address\":\"370 Feest Pike\",\"city\":\"Port Webster\",\"country\":\"ID\",\"email\":\"Emmett.Ankunding95@yahoo.com\",\"firstName\":\"Eden\",\"identityNumber\":\"21589551116\",\"lastName\":\"Langosh\",\"phone\":\"14988671499\",\"postalCode\":\"12192-3718\",\"province\":\"CO\"}",
  "lpmsInfo": "{\"lpmsType\":\"DANA\",\"bankName\":null,\"iBan\":\"DE89370400440532013000\",\"walletAccountId\":null,\"walletAccountName\":null,\"prepaidNumber\":null}", 
  "merchantCustId": "CustId-04IK-L1S3",
  "merchantNo": "800209",
  "merchantTxnId": "2ee5097c-48e3-44e4-b008-0590119995b3",
  "merchantTxnTime": "2025-05-11 17:49:22",
  "orderAmount": "100",
  "orderCurrency": "IDR",
  "productType": "LPMS", 
  "shippingInformation": "{\"address\":\"71463 Myrna Ridge\",\"city\":\"West Marlene\",\"country\":\"ID\",\"email\":\"Lori_Simonis98@hotmail.com\",\"firstName\":\"Elyssa\",\"identityNumber\":\"55296378622\",\"lastName\":\"Becker\",\"phone\":\"19175504257\",\"postalCode\":\"59143-0170\",\"province\":\"CO\"}",
  "sign": "24fd8bfc66b6f031fd27bc52ab91388f44bac7d4edc752cc7f2932908b4e9d97",
  "subProductType": "DIRECT", 
  "txnOrderMsg": "{\"accept\":\"*/*\",\"appId\":\"1727880846378401792\",\"colorDepth\":\"32\",\"contentLength\":\"16384\",\"javaEnabled\":true,\"language\":\"en-US\",\"products\":\"[{\\\"currency\\\":\\\"IDR\\\",\\\"name\\\":\\\"cavalo\\\",\\\"num\\\":\\\"25\\\",\\\"price\\\":\\\"733.39\\\",\\\"type\\\":\\\"dolor\\\"},{\\\"currency\\\":\\\"IDR\\\",\\\"name\\\":\\\"dried apricot\\\",\\\"num\\\":\\\"18\\\",\\\"price\\\":\\\"320.45\\\",\\\"type\\\":\\\"Excepteur\\\"},{\\\"currency\\\":\\\"IDR\\\",\\\"name\\\":\\\"nashi pear\\\",\\\"num\\\":\\\"66\\\",\\\"price\\\":\\\"965.59\\\",\\\"type\\\":\\\"consectetur laboris dolore\\\"}]\",\"returnUrl\":\"https://docs.onerway.com/\",\"notifyUrl\":\"https://docs.onerway.com/apis\",\"screenHeight\":\"480\",\"screenWidth\":\"1366\",\"timeZoneOffset\":\"-120\",\"transactionIp\":\"220.14.137.207\",\"userAgent\":\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36\"}",
  "txnType": "SALE"
}

json

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "transactionId": "1921503197131046912",
    "responseTime": "2025-05-11 17:50:39",
    "txnTime": "2025-05-11 17:50:36",
    "txnTimeZone": "+08:00",
    "orderAmount": "100.00",
    "orderCurrency": "IDR",
    "txnAmount": null,
    "txnCurrency": null,
    "status": "R", 
    "redirectUrl": "https://sandbox-stc.onerway.com/local-payment?orderId=8002091921503201446731776&returnUrl=https://sandbox-gw-dmz.onerway.com/front/return/8002091921503201446731776", 
    "contractId": null,
    "tokenId": null,
    "eci": null,
    "periodValue": null,
    "codeForm": null,
    "presentContext": null,
    "actionType": "RedirectURL", 
    "subscriptionManageUrl": null,
    "sign": "f809e578ab27b6ac1599d365fa4b39f5107ab5ad65ac11dbede4725362ea441d"
  }
}

json

{
  "notifyType": "TXN",
  "transactionId": "1921503197131046912",
  "txnType": "SALE",
  "merchantNo": "800209",
  "merchantTxnId": "2ee5097c-48e3-44e4-b008-0590119995b3",
  "responseTime": "2025-05-11 17:51:15",
  "txnTime": "2025-05-11 17:50:36",
  "txnTimeZone": "+08:00",
  "orderAmount": "100.00",
  "orderCurrency": "IDR",
  "status": "S", 
  "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
  "sign": "55ab708f7a91a8faad33c6b804796a84170a84fc8d48f04876c903bf83b343cc",
  "paymentMethod": "DANA", 
  "channelRequestId": "8002091921503201446731776"
}

本地支付订阅示例

本地支付方式的订阅流程

对于支持订阅的本地支付方式（如 DANA、WeChat、GCash 和 TOUCH_GO_EWALLET），订阅流程通常遵循两步流程：

初始订阅设置：零金额交易以建立订阅合同
- 系统为未来扣款创建合同和token
- 交易类型将是 BIND_CARD，尽管这不是卡交易
- 在webhook中以 scenarios: "SUBSCRIPTION_INITIAL" 显示
后续扣款：使用已建立的合同进行实际支付交易
- 使用初始设置中的 contractId 和 tokenId
- 带有订阅金额的常规交易

请求响应初始订阅Webhook后续扣款Webhook

json

{
  "billingInformation": "{\"country\":\"ID\",\"email\":\"abel.wang@onerway.com\",\"firstName\":\"CL\",\"lastName\":\"BRW2\",\"phone\":\"17700492982\",\"address\":\"Apt. 870\",\"city\":\"Hayward\",\"postalCode\":\"66977\",\"identityNumber\":\"12345678\"}",
  "lpmsInfo": "{\"lpmsType\":\"DANA\",\"iBan\":\"DE89370400440532013000\"}", 
  "merchantNo": "800209",
  "merchantTxnId": "1746975870000",
  "merchantTxnTime": "2025-05-11 23:04:30",
  "merchantTxnTimeZone": "+08:00",
  "orderAmount": "20000",
  "orderCurrency": "IDR",
  "productType": "LPMS", 
  "shippingInformation": "{\"country\":\"ID\",\"email\":\"abel.wang@onerway.com\",\"firstName\":\"CL\",\"lastName\":\"BRW2\",\"phone\":\"17700492982\",\"address\":\"Apt. 870\",\"city\":\"Hayward\",\"postalCode\":\"66977\",\"identityNumber\":\"12345678\"}",
  "sign": "ccc3fe125e4f842cc6d0c36fabd5f69c0c89af295cef7a7b05614c055e203a37",
  "subProductType": "SUBSCRIBE", // 用于订阅支付
  "subscription": "{\"requestType\":\"0\",\"merchantCustId\":\"1746975870000\",\"expireDate\":\"2034-10-17\",\"frequencyType\":\"D\",\"frequencyPoint\":\"1\",\"tokenId\":\"\",\"contractId\":\"\"}", 
  "txnOrderMsg": "{\"returnUrl\":\"https:/docs.onerway.com/\",\"products\":\"[{\\\"price\\\":\\\"20000\\\",\\\"num\\\":\\\"1\\\",\\\"name\\\":\\\"iphone11\\\",\\\"currency\\\":\\\"IDR\\\"}]\",\"transactionIp\":\"127.0.0.1\",\"appId\":\"1727880846378401792\",\"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,application/signed-exchange;v=b3;q=0.9\",\"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-USen-US\",\"notifyUrl\":\"https://www.merchant-store-website.com/\"}",
  "txnType": "SALE"
}

json

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "transactionId": "1921582195139805184",
    "responseTime": "2025-05-11 23:04:34",
    "txnTime": "2025-05-11 23:04:31",
    "txnTimeZone": "+08:00",
    "orderAmount": "0.00", // 初始订阅设置的零金额
    "orderCurrency": "IDR",
    "txnAmount": null,
    "txnCurrency": null,
    "status": "R", 
    "redirectUrl": "https://sandbox-stc.onerway.com/local-payment?orderId=8002091921510358975213568&returnUrl=https://sandbox-gw-dmz.onerway.com/front/return/8002091921510358975213568", 
    "contractId": null,
    "tokenId": "",
    "eci": null,
    "periodValue": null,
    "codeForm": null,
    "presentContext": null,
    "actionType": "RedirectURL", 
    "subscriptionManageUrl": null, 
    "sign": "1b46d107b1d4c2b34797d1e30cea3ae0d18a72684e5c2ec17725e3951c38a6f2"
  }
}

json

{
  "notifyType": "TXN",
  "transactionId": "1921582195139805184",
  "txnType": "BIND_CARD", // 注意：尽管不是卡交易，但为BIND_CARD
  "merchantNo": "800209",
  "merchantTxnId": "1746975870000",
  "responseTime": "2025-05-11 23:04:31",
  "txnTime": "2025-05-11 23:04:31",
  "txnTimeZone": "+08:00",
  "orderAmount": "0.00", // 合同建立的零金额
  "orderCurrency": "IDR",
  "status": "S", 
  "contractId": "1921582195420823553", // 未来扣款使用的合同ID
  "tokenId": "e0ed3f5ea3a4c402df66a9e37f84159ab86edf50d5df7b1943fa7e6024a14209", // 未来扣款使用的token
  "tokenExpireTime": "2099-12-31 23:59:59",
  "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
  "sign": "3d6c9c205bb7802a836cf2761a8595655aa47eb6742c427b4f8eabdfe639b944",
  "paymentMethod": "DANA", 
  "subscriptionStatus": "active", 
  "dataStatus": "1",
  "products": "[{\"price\":\"20000\",\"num\":\"1\",\"name\":\"iphone11\",\"currency\":\"IDR\"}]",
  "channelRequestId": "8002091921582200847998976",
  "scenarios": "SUBSCRIPTION_INITIAL" // 表示这是初始订阅设置
}

json

{
  "notifyType": "TXN",
  "transactionId": "1921583161943654402",
  "txnType": "SALE", // 常规SALE交易
  "merchantNo": "800209",
  "merchantTxnId": "1746975870000",
  "responseTime": "2025-05-11 23:08:24",
  "txnTime": "2025-05-11 23:08:21",
  "txnTimeZone": "+08:00",
  "orderAmount": "20000.00", // 实际扣款金额
  "orderCurrency": "IDR",
  "status": "S", 
  "contractId": "1921582195420823553", // 与初始设置相同的合同ID
  "tokenId": "e0ed3f5ea3a4c402df66a9e37f84159ab86edf50d5df7b1943fa7e6024a14209", // 与初始设置相同的token
  "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
  "sign": "bc7e1b705f9b30c6b5f0d4385a7e2d3fb4fae1199630166cba49a527b6bd3934",
  "paymentMethod": "DANA", 
  "subscriptionStatus": "active", 
  "dataStatus": "1",
  "products": "[{\"price\":\"20000\",\"num\":\"1\",\"name\":\"iphone11\",\"currency\":\"IDR\"}]",
  "channelRequestId": "8002091921583164418039809"
}

常见错误场景和解决方案

常见错误代码

处理订阅交易

对于支持订阅的本地支付方式，重要的是理解并正确实施两步交易流程：

初始零金额合同建立

Webhook识别：初始订阅设置可通过以下方式识别：
- txnType：BIND_CARD（尽管不是卡交易）
- orderAmount：0.00
- scenarios：SUBSCRIPTION_INITIAL
数据存储：收到此webhook时，您应该：
- 在数据库中安全存储 contractId 和 tokenId
- 将它们与客户档案关联
- 根据 subscriptionStatus 更新订阅状态
- 根据 expireTime 设置订阅到期时间

后续扣款交易

Webhook识别：实际扣款交易可通过以下方式识别：
- txnType：SALE
- 非零 orderAmount
- 与初始设置相同的 contractId 和 tokenId
数据处理：收到这些webhook时，您应该：
- 将支付记录到订阅中
- 更新系统中的扣款记录
- 跟踪订阅的支付历史
- 验证 subscriptionStatus 以确保订阅保持活跃

实施说明

某些本地支付方式可能需要为每个扣款周期单独进行身份验证，尽管使用相同的合同。您的实施应考虑后续扣款中可能出现的客户身份验证重定向。

此外，尽管初始webhook的 orderAmount=0.00，但您的原始请求应在 orderAmount 字段和产品详情中包含实际的订阅金额。此金额将用于参考，并将出现在后续扣款交易中。

支持的本地支付方式

以下是Onerway支持的流行本地支付方式摘要：

Type	Name	Countries (ISO Standard)	Supported Currencies	Required Fields	Transaction Limit
JdPay	JdPay	GB	GBP, EUR, CNY, SGD, USD, JPY, HKD, AUD, CAD	country	No limit
Alipay+	Alipay+	Worldwide	EUR, USD, GBP	email, country	No limit
WeChat	WeChat	GB	GBP	email, country	No limit
AlipayHK	AlipayHK	AT, BE, BG, HR, CY, CZ, DK, EE, FI, FR, DE, GR, HU, IE, IT, LV, LT, LU, MT, NL, PL, PT, RO, SK, SI, ES, SE, IS, LI, NO, GB, CH	GBP, USD, EUR, HKD, MYR, PHP, IDR, KRW, THB, CNY	email, country	No limit
AlipayCN	AlipayCN	AT, BE, BG, HR, CY, CZ, DK, EE, FI, FR, DE, GR, HU, IE, IT, LV, LT, LU, MT, NL, PL, PT, RO, SK, SI, ES, SE, IS, LI, NO, GB, CH	EUR, GBP, USD, AUD, CNY, HKD, THB, MYR, KRW, IDR, PHP	email, country	No limit
Kakao_Pay	Kakao Pay	AT, BE, BG, HR, CY, CZ, DK, EE, FI, FR, DE, GR, HU, IE, IT, LV, LT, LU, MT, NL, PL, PT, RO, SK, SI, ES, SE, IS, LI, NO, GB, CH	USD, GBP, EUR, KRW, HKD, MYR, PHP, IDR, CNY, THB	email, country	No limit
Klarna	Klarna	AU, AT, BE, FI, FR, DE, GR, IE, IT, NL, PT, ES, CZ, DK, NO, PL, SE, CH, GB	AUD, EUR, CZK, DKK, NOK, PLN, SEK, CHF, GBP	email, country, language, products	No limit
Boleto	Boleto	BR	BRL, EUR, USD	email, country, identityNumber, province, street, city, postalCode	No limit
BankTransfer	BankTransfer	BR, PH, JP	BRL, EUR, USD, PHP, JPY	email, country, identityNumber, province, street, city, postalCode, name	Min: 1
Banrisul	Banrisul	BR	BRL, EUR, USD	email, country, identityNumber, province, street, city, postalCode	No limit
Bradesco	Bradesco	BR	BRL, EUR, USD	email, country, identityNumber, province, street, city, postalCode	No limit
Banco do Brasil	Banco do Brasil	BR	BRL, EUR, USD	email, country, identityNumber, province, street, city, postalCode	No limit
Itau	Itau	BR	BRL, EUR, USD	email, country, identityNumber, province, street, city, postalCode	No limit
MercadoPago	MercadoPago	BR, MX	BRL, EUR, USD, MXN	email, country, identityNumber, province, street, city, postalCode	No limit
PIX	PIX	BR	BRL, EUR, USD	email, country, identityNumber, province, street, city, postalCode	No limit
Servipag	Servipag	CL	CLP, EUR, USD	email, country	No limit
Sencillito	Sencillito	CL	CLP, EUR, USD	email, country	No limit
Webpay	Webpay	CL	CLP, EUR, USD	email, country	No limit
Multicaja	Multicaja	CL	CLP, EUR, USD	email, country	No limit
Baloto	Baloto	CO	COP, EUR, USD	email, country	No limit
EFT	EFT	CO	COP, EUR, USD	email, country, identityNumber, bankName	No limit
Efecty	Efecty	CO	COP, EUR, USD	email, country	No limit
SPEI	SPEI	MX	MXN, USD	email, country	No limit
OXXO	OXXO	MX	MXN, USD	email, country	No limit
OXXOPAY	OXXOPAY	MX	MXN, USD	email, country	No limit
PagoEfectivo	PagoEfectivo	PE	PEN, USD	email, country	No limit
safetypay-cash	SafetyPay Cash	PE, EC	PEN, USD	email, country	No limit
safetypay-online	SafetyPay Online	PE, EC	PEN, USD	email, country	No limit
PayU	PayU	PL, CZ	PLN, CZK	email, country	No limit
Przelewy24	Przelewy24	PL	PLN	email, country, bankName	No limit
Pagosnet	Pagosnet	BO	BOB, USD	email, country	No limit
SEPADD	SEPADD	AT, BE, BG, HR, CY, CZ, DK, EE, FI, FR, DE, GR, HU, IE, IT, LV, LT, LU, MT, NL, PL, PT, RO, SK, SI, ES, SE, IS, LI, NO, AD, SM, MC, VA, PF, TF, GI, GG, IM, JE, BL, PM, CH, GB, WF	EUR	Checkout: email, country API: email, country, IBAN	0.10 - 1,000 EUR
Sofort	Sofort	AT, BE, DE, NL, ES, CH	EUR, CHF	email, country	No limit
Giropay	Giropay	DE	EUR	email, country	No limit
iDEAL	iDEAL	NL	AUD, CAD, DKK, EUR, GBP, HKD, NOK, SEK, USD	email, country	No limit
Konbini	Konbini	JP	JPY	country	1 - 300,000
PayEasy	PayEasy	JP	JPY	Checkout: country API: country, firstName, lastName, jpFirstName, jpLastName, phone	1 - 300,000
POLi	POLi	AU	AUD	email, country	No limit
Bancontact	Bancontact	BE	EUR	email, country	No limit
OVO	OVO	ID	IDR	country	1 - 10,000
MyBank	MyBank	IT	EUR	email, country	No limit
Dragonpay	Dragonpay	Worldwide	PHP	email, country	No limit
Skrill	Skrill	Worldwide	EUR, GBP, USD	email, country	No limit
eNETS	eNETS	SG	SGD	email, country	No limit
PayseraWallet	PayseraWallet	LT, LV, EE	EUR	email, country	No limit
LithuanianBanks	LithuanianBanks	LT	EUR	email, country	No limit
PaySafeCard	PaySafeCard	AT, AU, BE, BG, CA, CH, CY, CZ, DE, DK, ES, FI, FR, GB, GE, GI, GR, HR, HU, IE, IT, LI, LT, LU, MT, MX, NL, NZ, NO, PE, PL, PT, RO, SE, SI, SK, UY	AUD, CAD, CHF, EUR, GBP, NOK, PLN, RON, SEK, USD	email, country	No limit
Paysafecash	Paysafecash	AT, BE, CA, CH, CY, CZ, DK, ES, FR, GB, GR, HR, HU, IE, IT, LU, LT, MT, NL, PL, PT, RO, SE, SI, SK	AUD, CAD, CHF, EUR, GBP, NOK, PLN, RON, SEK, USD	email, country	No limit
Payconiq	Payconiq	BE, NL, LU	EUR	email, country	No limit
Trustly	Trustly	DE, DK, EE, ES, FI, GB, LT, LV, NL, NO, PL, SE, SK	DKK, EUR, GBP, NOK, PLN, SEK	email, country	No limit
GCash	GCash	PH	PHP	email, identityNumber, name	1 - 10,000 PHP
GrabPay	GrabPay	PH	PHP	email, identityNumber, name	Min: 1 PHP
PayMaya	PayMaya	PH	PHP	email, identityNumber, name	1 - 50,000 PHP
ELEVEN	ELEVEN	PH	PHP	email, identityNumber, name	1 - 10,000 PHP
GrabPay SG	GrabPay SG	SG	SGD	country	Min: 0.01
TrueMoney Wallet	TrueMoney Wallet	TH	THB	Checkout: country API: country, phone	20 - 100,000
Rabbit_Line_pay	Rabbit Line Pay	TH	THB	country	20 - 150,000
PromptPay	PromptPay	TH	THB	country	20 - 150,000
KRUNGSRI_ONLINE	Krungsri Online	TH	THB	country	20 - 150,000
BUALUANG_IBANKING	Bualuang iBanking	TH	THB	country	20 - 150,000
CITI_POINTS	Pay with Points - Citi Rewards	TH	THB	country	20 - 150,000
K_PLUS	K PLUS	TH	THB	country	20 - 150,000
MCASH	MCASH	MY	MYR	country	Min: 1.00
TOUCH_GO_EWALLET	Touch 'n Go eWallet	MY	MYR	country	Min: 1.00
ShopeePay	ShopeePay	MY, ID	MYR, IDR	country	Min: 1.00
Boost	Boost	MY	MYR	country	Min: 1.00
BNI	BNI VA	ID	IDR	country	1 - 10,000
MANDIRI	Mandiri ATM	ID	IDR	country	1 - 10,000
Maybank	Maybank VA	ID	IDR	country	1 - 10,000
PERMATA	Permata VA	ID	IDR	country	1 - 10,000
BRI	BRI VA	ID	IDR	country	1 - 10,000
CIMB	CIMB VA	ID	IDR	country	1 - 10,000
DANA	DANA	ID	IDR	country	1 - 10,000
QRIS	QRIS	ID	IDR	country	1 - 10,000
AKULAKU	AKULAKU	ID	IDR	country	1 - 10,000
BankTransfer	Bank Transfer Japan	JP	JPY	Checkout: country API: country, firstName, lastName, jpFirstName, jpLastName, phone	Min: 1
Paypay	PayPay	JP	JPY	country	1 - 1,000,000
LINE_Pay	LINE Pay	JP	JPY	country	1 - 1,000,000
Merpay	merPay	JP	JPY	country	1 - 1,000,000
Rakuten_Pay	Rakuten Pay	JP	JPY	country	100 - 9,999,999
BitCash	Bit Cash	JP	JPY	Checkout: country API: country, prepaidNumber	1 - 20,000
Net_Cash	Net Cash	JP	JPY	Checkout: country API: country, prepaidNumber	1 - 20,000
WebMoney	Web Money	JP	JPY	Checkout: country API: country, prepaidNumber	1 - 20,000
au	au KDDI	JP	JPY	country	1 - 100,000
SoftBank	SoftBank	JP	JPY	country	1 - 100,000
NTT_Docomo	NTT Docomo	JP	JPY	country	1 - 100,000
Paidy	Paidy	JP	JPY	country	1 - 1,000,000
BLIK	BLIK	PL	PLN	Checkout: country API: country, walletAccountId	0.01 - 50,000 PLN (most issuers: 10,000 PLN)
BLIK_SEAMLESS	BLIK Seamless	PL	PLN	Checkout: country API: country, walletAccountId	0.01 - 50,000 PLN (most issuers: 10,000 PLN)

地区要求

某些本地支付方式可能需要额外的商户注册或有特定的地区要求。请联系Onerway支持以了解每种支付方式的详细要求。

实施最佳实践

货币匹配：确保交易货币与所选支付方式支持的货币匹配
返回URL处理：实施适当的返回URL处理以处理支付状态参数
用户体验：向客户显示清晰的支付说明和状态更新
支付方式选择：根据客户的地区和货币筛选可用的支付方式
Webhook验证：始终验证webhook签名以防止篡改
错误处理：实施健壮的错误处理，向客户提供清晰的消息
交易追踪：维护交易日志以便对账和故障排除
延迟结算：某些本地支付方式有延迟结算 - 相应设计您的系统
超时处理：为保持待处理状态的交易实施适当的超时处理
订阅管理：对于支持订阅的方式，安全存储合同和token信息
用户界面：提供与本地支付平台之间的无缝过渡
移动优化：确保您的重定向流程在移动设备上运行良好，因为许多本地支付方式是移动优先的

商户集成检查清单

在上线本地支付集成之前，请确保您已完成：

收银台

下单

WebSDK

Android

绑卡支付

订阅支付

本地支付

Apple Pay

Google Pay

Ethoca

RDR

本地支付方式

API请求参数

TransactionAddress

LpmsInfo

Subscription

TxnOrderMsg

Products

响应参数

data

本地支付集成流程

1. 支付发起

2. 支付处理

3. 支付结果通知

4. 本地支付的订阅流程

API使用示例

标准本地支付请求（DANA）

本地支付订阅示例

常见错误场景和解决方案

处理订阅交易

初始零金额合同建立

后续扣款交易

支持的本地支付方式

实施最佳实践

商户集成检查清单

收银台

下单

WebSDK

Android

绑卡支付

订阅支付

本地支付

Apple Pay

Google Pay

本地支付方式 ​

API请求参数 ​

TransactionAddress ​

LpmsInfo ​

Subscription ​

TxnOrderMsg ​

Products ​

响应参数 ​

data ​

本地支付集成流程 ​

1. 支付发起 ​

2. 支付处理 ​

3. 支付结果通知 ​

4. 本地支付的订阅流程 ​

API使用示例 ​

标准本地支付请求（DANA） ​

本地支付订阅示例 ​

常见错误场景和解决方案 ​

处理订阅交易 ​

初始零金额合同建立 ​

后续扣款交易 ​

支持的本地支付方式 ​

实施最佳实践 ​

商户集成检查清单 ​

本地支付方式

API请求参数

TransactionAddress

LpmsInfo

Subscription

TxnOrderMsg

Products

响应参数

data

本地支付集成流程

1. 支付发起

2. 支付处理

3. 支付结果通知

4. 本地支付的订阅流程

API使用示例

标准本地支付请求（DANA）

本地支付订阅示例

常见错误场景和解决方案

处理订阅交易

初始零金额合同建立

后续扣款交易

支持的本地支付方式

实施最佳实践

商户集成检查清单