支付流程概览

本章节说明支付应用可支持的支付和退款流程。

核心功能

支付应用必须支持以下核心能力：

处理支付：发起并处理支付交易。
处理退款：处理已完成支付的退款请求。
结果通知：向 Shoplazza 通知支付和退款结果。
测试模式：支持开发和验证用的测试交易。Shoplazza 会传入 test 参数表示交易是否处于测试模式。

3DS 验证

如果信用卡支付根据国家或地区要求需要 3-D Secure 验证，支付系统必须支持 3DS 验证。

幂等性

所有支付和退款请求都必须具备幂等性。Shoplazza 会在请求参数中包含唯一 id，支付系统必须确保同一个 id 不会被重复处理。

重试策略

支付应用依赖异步通信向 Shoplazza 通知支付和退款结果。如果 Shoplazza 没有以 HTTP 200 OK 确认回调，请按照重试策略重试请求。

参数	说明	值
最大重试次数	未收到 HTTP `200` 时允许的总重试次数。	18 次
初始重试延迟	第一次重试前的等待时间。	5 秒
指数退避因子	后续重试按递增间隔执行，直到收到确认或超时。	见示例

重试间隔示例：

[0 seconds, 5 seconds, 10 seconds, 30 seconds, 45 seconds, 1 minute, 2 minutes, 5 minutes, 12 minutes, 38 minutes, 1 hour, 2 hours] + [4 hours] * 5

支付模型

一个支付应用可以支持一种支付模式。需要不同支付模式时，可以使用多个支付应用。

方式	说明	备注
Sale	顾客跳转到第三方支付页面完成交易。	适合大多数支付网关。
Card	顾客直接在 Shoplazza 结账页输入信用卡信息。	需要 PCI-DSS 合规，并在需要时支持 3DS。
Iframe	第三方支付窗口以内嵌 iframe 形式显示在 Shoplazza 结账页。	支持自定义 iframe 尺寸。

iframe 支付尺寸要求：

最小宽度：300px
最小高度：200px
最大宽高：不超过屏幕尺寸。超过屏幕尺寸时默认使用 80vw x 80vh。

数字签名

Shoplazza 与支付系统之间的所有请求都必须包含数字签名用于校验。

按字母顺序对请求体 JSON 字段排序。
将所有 key-value 拼接成一个字符串。
使用 HMAC-SHA256 生成签名。
将签名放入 Shoplazza-Hmac-Sha256 HTTP 请求头。

PHP 示例

$data = json_decode('{
    "id": "1c2bbaf5-774d-4a44-b2b8-641d09151c12",
    "app_id": "99999",
    "account_id": "10013",
    "shoplazza_order_id": "999993147340725412810",
    "amount": "10.00",
    "currency": "USD",
    "test": false,
    "type": "sale",
    "timestamp": "1724155549"
}', true);

ksort($data);
$str = '';
foreach ($data as $key => $value) {
    if ($key == 'amount') {
        $value = bcadd($value, 0, 2);
    }
    if (is_bool($value)) {
        $value = $value ? 'true' : 'false';
    }
    if (is_array($value)) {
        $value = json_encode($value);
    }
    if (mb_strlen($value) > 0) {
        $str .= $key . $value;
    }
}

$key = '47adb962a5e4425185333564ab8a2fbe';
echo hash_hmac('sha256', $str, $key);

常见签名错误

参数值格式不正确。
密钥与商家配置的密钥不一致。
布尔值没有转换为 true 或 false 字符串。
金额没有格式化为两位小数。
空字段被加入签名字符串。
拼接字符串包含 = 或 &；正确形式应为 key1value1key2value2...。

商家配置

要启用支付系统，商家需要在 Shoplazza 店铺后台进入 Settings > Payments，填写支付服务商提供的商户号和密钥。

核心功能​

3DS 验证​

幂等性​

重试策略​

支付模型​

数字签名​

PHP 示例​

常见签名错误​

商家配置​