Tamara 集成

概述

Tamara 是支持阿联酋、科威特和沙特阿拉伯地区的分期付款服务（买现在付以后）。本文档涵盖通过 Onerway 支付网关接入 Tamara 的完整技术集成流程，从前提条件到生产部署。

技术特性：

支付流程：重定向式（分期付款服务）
支持国家：AE（阿联酋）, KW（科威特）, SA（沙特阿拉伯）
支持币种：AED（阿联酋迪拉姆）, KWD（科威特第纳尔）, SAR（沙特里亚尔）
结算货币：USD（美元）
交易金额：单笔交易金额范围 0.1-10000 SAR（或等值其他支持币种）
交易类型：实时
集成方式：REST API

支持功能:

单次支付
分期付款服务
实体商品交易（需上传物流信息以触发结算）
虚拟商品交易（无需物流信息）

不支持:

订阅支付

结算流程要求

Tamara 针对不同商品类型有特殊的结算要求：

实体商品交易: 支付成功后，必须上传已签收的物流信息才能触发资金结算
虚拟商品交易: 无需物流信息，支付成功后自动结算
订单状态要求: 实体商品订单必须达到成功状态后才能上传物流信息
上传时机: 实体商品必须在包裹签收后 30 天内完成物流信息上传

详细的物流信息上传流程，请参考物流信息上传文档。

技术前提条件

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

基础设施要求

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

集成要求

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

可选增强

阿拉伯语界面支持（提升用户体验）
移动应用深度链接支持
从右至左（RTL）UI 布局

技术配置

步骤 1：API 凭证配置

从 Onerway 获取以下凭证信息：

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

步骤 2：Webhook 配置

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

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

Webhook 配置示例：

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

步骤 3：返回 URL 配置

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

returnUrl：支付完成后客户重定向地址（成功或失败）
查询参数将包含：transactionId、status、merchantTxnId

交易状态轮询

收到 returnUrl 回跳后，商户可以主动调用交易查询接口轮询交易状态，以验证最终支付状态，而不是仅依赖重定向参数。

集成流程

Tamara 集成采用基于重定向的支付流程：

支付流程图

流程步骤说明

阶段 1：支付发起

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

阶段 2：客户认证

商户将客户重定向到 Tamara 支付页面
客户选择分期方案进行身份认证
客户在 Tamara 中确认支付
Tamara 重定向回商户网站

阶段 3：支付确认

Tamara 通知 Onerway 支付结果
Onerway 向商户发送 webhook
商户确认接收 webhook
商户向客户显示结果

阶段 4：结算确认（实体商品）

商户在包裹签收后上传物流信息
Onerway 验证物流信息有效性
结算流程自动触发

虚拟商品

虚拟商品交易无需阶段 4，支付成功后自动结算。

重要提示

始终依赖 webhook 通知来获取最终支付状态
重定向返回您的网站可能无法准确反映支付结果
实体商品: 支付成功后必须上传物流信息才能触发结算，详见物流信息上传
虚拟商品: 支付成功后自动结算，无需额外操作

Tamara 特殊要求

Tamara 支付需要以下配置和参数：

lpmsInfo 配置

设置 lpmsInfo 参数标识使用 Tamara：

json

"lpmsInfo": "{\"lpmsType\":\"tamara\"}"

必填参数

以下参数在 Tamara 支付中为必填：

merchantCustId

客户在商户系统中的唯一标识。

txnOrderMsg

必须包含以下字段：

customerPlatform - 商户平台标识
- Web：传入域名（如 merchant.example.com）
- App：传入应用名称（如 Merchant iOS App）
products - 商品信息
- type：商品类型（physical 或 virtual），影响结算方式
- productAvatarUrl：商品图片 URL

完整字段定义见 Products

billingInformation

无论实体商品还是虚拟商品，始终必填：

firstName, lastName, phone, email

完整字段定义见 TransactionAddress

shippingInformation

无论实体商品还是虚拟商品，始终必填：

firstName, lastName, phone
country, city, address, postalCode

完整字段定义见 TransactionAddress

不同场景传参示例

实体商品虚拟商品

json

{
  "merchantCustId": "customer_12345", // 必填
  "lpmsInfo": "{\"lpmsType\":\"tamara\"}", // Tamara 标识
  "billingInformation": "{\"firstName\":\"Ahmad\",\"lastName\":\"Al-Salem\",\"phone\":\"966501234567\",\"email\":\"customer@example.com\"}", // firstName, lastName, phone, email 始终必填
  "shippingInformation": "{\"firstName\":\"Ahmad\",\"lastName\":\"Al-Salem\",\"phone\":\"966501234567\",\"country\":\"SA\",\"city\":\"Riyadh\",\"address\":\"King Fahd Road\",\"postalCode\":\"12345\"}", // 始终必填完整收货信息
  "txnOrderMsg": "{\"customerPlatform\":\"merchant.example.com\",\"products\":\"[{\\\"type\\\":\\\"physical\\\",\\\"productAvatarUrl\\\":\\\"https://cdn.example.com/product.jpg\\\"}]\"}" // type=physical, productAvatarUrl 必填
}

json

{
  "merchantCustId": "customer_12345", // 必填
  "lpmsInfo": "{\"lpmsType\":\"tamara\"}", // Tamara 标识
  "billingInformation": "{\"firstName\":\"Ahmad\",\"lastName\":\"Al-Salem\",\"phone\":\"966501234567\",\"email\":\"customer@example.com\"}", // 虚拟商品也必须包含 phone, email
  "shippingInformation": "{\"firstName\":\"Ahmad\",\"lastName\":\"Al-Salem\",\"phone\":\"966501234567\",\"country\":\"SA\",\"city\":\"Riyadh\",\"address\":\"King Fahd Road\",\"postalCode\":\"12345\"}", // 虚拟商品也必须收集完整收货信息
  "txnOrderMsg": "{\"customerPlatform\":\"merchant.example.com\",\"products\":\"[{\\\"type\\\":\\\"virtual\\\",\\\"productAvatarUrl\\\":\\\"https://cdn.example.com/product.jpg\\\"}]\"}" // type=virtual, productAvatarUrl 必填
}

商品类型影响结算

physical（实体商品）：支付成功后需上传物流信息才能结算
virtual（虚拟商品）：支付成功后自动结算

重要: 无论实体还是虚拟商品，Tamara 都要求收集完整的客户信息（billingInformation 和 shippingInformation）。

类型枚举值见 StoreProductTypeEnum

API 请求参数

POST

关键参数

对于 Tamara 集成，您必须设置：

productType: LPMS
lpmsInfo: JSON 字符串，包含 lpmsType 设置为 tamara
orderCurrency: AED, KWD, 或 SAR
orderAmount: 单笔交易金额范围 0.1-10000 SAR（或等值其他支持币种）

标准请求参数

完整的标准 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.
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 字符串，Tamara 支付配置：

参数	类型	必填	说明
lpmsType	String	是	固定值 `tamara`

响应

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

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

响应处理

Tamara 交易通常返回 status=R 和 actionType=RedirectURL。您必须重定向客户到 Tamara 支付页面完成支付。

API 使用示例

标准支付请求

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

json

{
  "merchantNo": "800209", // Onerway 商户号
  "merchantCustId": "1763979160000", // 客户唯一标识
  "merchantTxnId": "1763979160000", // 唯一交易 ID
  "merchantTxnTime": "2025-11-24 18:12:40", // 交易时间
  "orderAmount": "250.00", // 订单金额（0.1-10000 SAR）
  "orderCurrency": "SAR", // 支持 SAR, AED, KWD
  "productType": "LPMS", // 本地支付方式
  "subProductType": "DIRECT",
  "lpmsInfo": "{\"lpmsType\":\"tamara\"}", // Tamara 配置
  "billingInformation": "{\"firstName\":\"xxx\",\"lastName\":\"xxx\",\"phone\":\"966501234567\",\"email\":\"abel.wang@onerway.com\",\"postalCode\":\"35802\",\"address\":\"test\",\"country\":\"SA\",\"province\":\"AS\",\"city\":\"city\",\"street\":\"Amsterdam Ave\",\"number\":10}", // 完整账单信息（始终必填）
  "shippingInformation": "{\"firstName\":\"xxx\",\"lastName\":\"xxx\",\"phone\":\"966501234567\",\"email\":\"abel.wang@onerway.com\",\"postalCode\":\"35802\",\"address\":\"test\",\"country\":\"SA\",\"province\":\"AS\",\"city\":\"city\",\"street\":\"Amsterdam Ave\",\"number\":10}", // 完整收货信息（始终必填）
  "txnOrderMsg": "{\"returnUrl\":\"https://merchant.com/return\",\"notifyUrl\":\"https://www.merchant-store-website.com/\",\"appId\":\"1727880846378401792\",\"customerPlatform\":\"merchant.example.com\",\"products\":\"[{\\\"name\\\":\\\"iPhone 15\\\",\\\"price\\\":\\\"250.00\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"SAR\\\",\\\"type\\\":\\\"physical\\\",\\\"productAvatarUrl\\\":\\\"https://cdn.merchant.com/iphone15.jpg\\\"}]\"}", // Tamara 必填字段
  "txnType": "SALE",
  "sign": "1d307518fd390f91945887eaa681d65f1e317dedfece5f537fc2a4b4c538bfca" // 请求签名
}

json

{
  "respCode": "20000", // 成功代码
  "respMsg": "Success",
  "data": {
    "transactionId": "1992899161619828736", // Onerway 交易 ID
    "responseTime": "2025-11-24 18:12:41",
    "txnTime": "2025-11-24 18:12:41",
    "txnTimeZone": "+08:00",
    "orderAmount": "250.00",
    "orderCurrency": "SAR",
    "txnAmount": null,
    "txnCurrency": null,
    "status": "R", // 需要重定向
    "redirectUrl": "https://cashier-dev.gccpay.cn/en-US/order/ORD251124131241558257507", // Tamara 支付页面 URL
    "contractId": null,
    "tokenId": null,
    "eci": null,
    "periodValue": null,
    "codeForm": null,
    "presentContext": null,
    "actionType": "RedirectURL", // 操作类型：重定向
    "subscriptionManageUrl": null,
    "sign": "39dc0cd41a050f297a9300e46e980f66edbd3bb740b0c09d3e404c5a40d48946"
  }
}

json

{
  "notifyType": "TXN",
  "transactionId": "1992899161619828736", // Onerway 交易 ID
  "txnType": "SALE",
  "merchantNo": "800209",
  "merchantTxnId": "1763979160000",
  "responseTime": "2025-11-24 18:16:16",
  "txnTime": "2025-11-24 18:12:41",
  "txnTimeZone": "+08:00",
  "orderAmount": "250.00",
  "orderCurrency": "SAR",
  "status": "S", // 成功状态
  "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
  "sign": "a12a1a4d704b0f8e2b1c1b23b504d6f064a704a7b4627f999f852d2e08a8ed45", // 验证签名
  "paymentMethod": "tamara", // 支付方式
  "walletTypeName": "tamara", // 钱包类型名称
  "channelRequestId": "8002091992899163351810049"
}

技术集成检查清单

生产环境部署前：

API 集成

支付请求 API 已实现并测试
请求签名生成正常工作
错误响应处理已实现
重定向流程已实现（处理 status=R）
支持的国家和币种验证已实现（AE/AED, KW/KWD, SA/SAR）
交易金额限制验证已实现（0.1-10000 SAR 或等值）

Tamara 特殊要求

商品信息包含 type 字段（physical 或 virtual）
商品信息包含 productAvatarUrl 字段（HTTPS 图片链接）
txnOrderMsg 包含 customerPlatform 字段（Web 传域名，App 传应用名）
无论商品类型，billingInformation 包含完整信息（firstName, lastName, phone, email）
无论商品类型，shippingInformation 包含完整信息（firstName, lastName, phone, country, city, address, postalCode）
实体商品：物流信息上传 API 已实现
实体商品：包裹签收状态验证已实现
实体商品：订单终态检查已实现
实体商品：物流上传时机控制已实现（30天内）

Webhook 实现

Webhook 端点通过 HTTPS 公网可访问
Webhook 签名验证已实现
幂等性 webhook 处理已实现
Webhook 确认返回 HTTP 200 及 transactionId
Webhook 负载异步处理

安全性

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

测试验证

监控与运维

API 请求/响应日志已实现
错误监控和告警已配置
交易状态跟踪已实现
Webhook 重试机制已实现

技术支持

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

收银台

下单

WebSDK

Android

绑卡支付

订阅支付

本地支付

Apple Pay

支付流程

Google Pay

Tamara 集成 ​

概述 ​

技术前提条件 ​

基础设施要求 ​

集成要求 ​

可选增强 ​

技术配置 ​

步骤 1：API 凭证配置 ​

步骤 2：Webhook 配置 ​

步骤 3：返回 URL 配置 ​

集成流程 ​

支付流程图 ​

流程步骤说明 ​

阶段 1：支付发起 ​

阶段 2：客户认证 ​

阶段 3：支付确认 ​

阶段 4：结算确认（实体商品） ​

Tamara 特殊要求 ​

lpmsInfo 配置 ​

必填参数 ​

merchantCustId ​

txnOrderMsg ​

billingInformation ​

shippingInformation ​

不同场景传参示例 ​

API 请求参数 ​

标准请求参数 ​

lpmsInfo 参数说明 ​

响应 ​

data ​

API 使用示例 ​

标准支付请求 ​

技术集成检查清单 ​

API 集成 ​

Tamara 特殊要求 ​

Webhook 实现 ​

安全性 ​

测试验证 ​

监控与运维 ​

Tamara 集成

概述

技术前提条件

基础设施要求

集成要求

可选增强

技术配置

步骤 1：API 凭证配置

步骤 2：Webhook 配置

步骤 3：返回 URL 配置

集成流程

支付流程图

流程步骤说明

阶段 1：支付发起

阶段 2：客户认证

阶段 3：支付确认

阶段 4：结算确认（实体商品）

Tamara 特殊要求

lpmsInfo 配置

必填参数

merchantCustId

txnOrderMsg

billingInformation

shippingInformation

不同场景传参示例

API 请求参数

标准请求参数

lpmsInfo 参数说明

响应

data

API 使用示例

标准支付请求

技术集成检查清单

API 集成

Tamara 特殊要求

Webhook 实现

安全性

测试验证

监控与运维