话费充值 API 接入文档

1. 快速开始

接入步骤总览

1. 获取商户开放应用 app_id 与 app_secret（用于 OpenAPI 签名，详见第 5 节），以及 SDK 通知密钥 apiSecret（用于异步通知验签，详见第 9 节）。
2. 下游服务端调用创建订单接口，传入手机号、面额、异步通知地址等参数，获得来福 orderNo。
3. 调用查询接口取得本单锁价（totalAmount/payAmount），按 totalAmount 在自有收银台向用户收款。
4. 下游服务端确认用户真实付款成功后，调用支付成功通知接口，传入 totalAmount 触发来福履约。
5. 接收来福异步通知，按 X-LYP-Sign 验签，以 orderStatus=SUCCESS 为充值成功最终口径。
6. 任何时候不确定订单状态，优先查单而非重复创建。

2. 标准业务时序

① POST /openapi/v1/order/create 创建 WAIT_PAY 订单，保存 orderNo
② GET  /openapi/v1/order/query  查询 totalAmount 与 payAmount
③ 下游按 totalAmount 在自有收银台向用户收款
④ 下游服务端验真自己的支付结果
⑤ POST /openapi/v1/sdk/payment/notify 通知来福已收款
⑥ 来福校验订单、金额、签名和幂等，按 payAmount 扣商户账户并请求上游
⑦ 来福向下游 notifyUrl 发送异步通知（含 X-LYP-* 签名头）
⑧ 下游验签后仅以 SUCCESS 作为充值成功；PROCESSING 继续等待

3. 公共响应结构

所有 OpenAPI 接口统一使用以下 JSON 响应结构。下游必须同时检查 HTTP 状态码（应为 200）和业务码（code 应为 200）以判定成功。

4. 产品、面额与价格

5. 创建待支付订单

由下游服务端调用，创建一笔话费充值待支付订单。请求必须携带第 6 节 OpenAPI 签名头。

POST https://api.laifuagi.cn/prod-api/openapi/v1/order/create
Content-Type: application/json
app_id: {appId}
timestamp: {unix-seconds}
nonce: {unique-random-string}
sign: {base64url-hmac-sha256}

{"typeCode":"PrepaidRefill","merchantRequestNo":"M202607250001","bizParams":{"mobile":"13800138000","faceValue":"100","notifyUrl":"https://merchant.example.com/laifu/notify","callbackUrl":"https://merchant.example.com/order/result"}}

请求头字段

请求体字段

成功响应体字段

{"code":200,"msg":"操作成功","data":{"orderNo":"UP20260725123456789","requestId":"req_a1b2c3d4"}}

6. 查询订单锁价与状态

创建订单后，下游必须主动查询以获取本单锁价（totalAmount/payAmount），并按 totalAmount 向用户收款。请求携带 OpenAPI 签名头。

GET https://api.laifuagi.cn/prod-api/openapi/v1/order/query?orderNo={orderNo}
app_id: {appId}
timestamp: {unix-seconds}
nonce: {unique-random-string}
sign: {base64url-hmac-sha256}

签名规则补充

GET 请求签名原文：METHOD + "\n" + URI + "\n" + timestamp + "\n" + nonce + "\n"。URI 固定为 /openapi/v1/order/query，不包含 ?orderNo=... QueryString，也不包含公网 /prod-api 前缀。

成功响应体字段

{"code":200,"msg":"操作成功","data":{"orderNo":"UP20260725123456789","status":"WAIT_PAY","totalAmount":100.00,"payAmount":101.00,"createTime":"2026-07-25T10:00:00","requestId":"req_b2c3d4e5"}}

7. 下游支付成功通知

POST https://api.laifuagi.cn/prod-api/openapi/v1/sdk/payment/notify
Content-Type: application/json

{"merchantId":44,"orderNo":"UP20260725123456789","quoteId":"","amount":"100.00","timestamp":"1784532897689","nonce":"f40ff48166e5e663","sign":"{sha256-hex}"}

请求体字段

签名算法

payload = merchantId={merchantId}&orderNo={orderNo}&quoteId={quoteId}&amount={amount两位小数}&timestamp={timestamp}&nonce={nonce}
signText = payload + "&key=" + app_secret + "&sandbox=false"
sign = SHA256(signText).hexLowercase()

签名使用该商户启用的 OpenAPI 应用 app_secret。参数按固定顺序拼接待签字符串，不排序。

成功响应

{"code":200,"msg":"操作成功","data":true}

8. 来福异步通知

来福在订单状态变更时向下游配置的通知地址发送异步通知。通知可能重复送达，下游须按 orderNo + event + orderStatus 幂等处理。通知地址优先级以订单/商户实际配置解析结果为准，接入前请在各商户后台的「通知配置」页面确认实际生效地址。

POST {notifyUrl}
Content-Type: application/json
X-LYP-Timestamp: {unix-milliseconds}
X-LYP-Nonce: {unique-random-string}
X-LYP-Sign: {hmac-sha256-hex}

{"event":"ORDER_SUCCESS","orderNo":"UP20260725123456789","merchantId":44,"typeCode":"PrepaidRefill","orderStatus":"SUCCESS","totalAmount":100.00,"payAmount":101.00,"userPayAmount":100.00,"merchantSettleAmount":101.00,"merchantProfitAmount":-1.00,"upstreamOrderNo":"UPSTREAM20260725001","upstreamStatus":"SUCCESS","mobile":"13800138000","faceValue":"100","timestamp":1784532897689,"nonce":"abc123def456","sign":"{hmac-sha256-hex}"}

通知请求头

通知体字段

通知验签算法

1. 解析 JSON 通知体，取得全部一级字段
2. 排除 sign 字段（该字段不参与自身签名原文）
3. 排除值为 null 的字段
4. 剩余一级字段放入按字段名字典序排列的对象（Java TreeMap 语义）
5. 将整个排序后对象序列化为紧凑 JSON；字符串仍带 JSON 双引号，数字和布尔值保持 JSON 类型，嵌套值按原 JSON 值参与
6. 将该完整紧凑 JSON 字符串作为 HMAC 的 data 输入
7. expectedSign = HMAC-SHA256(apiSecret, jsonString).hexLowercase()
8. 使用常量时间比较 expectedSign 与请求头 X-LYP-Sign

注意：header 中的 sign 与 body 中的 sign 值相同。验签密钥使用商户后台 SDK 安全配置中的通知密钥（apiSecret），不是 OpenAPI 的 app_secret。两者不同。

成功应答要求

9. 签名算法汇总

本文档涉及两套签名算法，其用途和密钥各不相同，请严格区分。

OpenAPI 签名（创建/查单）

// POST 请求
signText = METHOD + "\n" + URI + "\n" + timestamp + "\n" + nonce + "\n" + rawBody
// GET 请求
signText = METHOD + "\n" + URI + "\n" + timestamp + "\n" + nonce + "\n"
sign = base64url(HMAC-SHA256(app_secret, signText))
// 去掉 base64url 结果中的 '=' 补位符

• URI 使用内部路径，不含公网 /prod-api 前缀，不含 QueryString：创建为 /openapi/v1/order/create，查询为 /openapi/v1/order/query。
• rawBody 必须与实际发送的 HTTP 请求体字节一致。签名后不要重新格式化 JSON。
• 不使用 MD5、字段排序签名或 nonceStr。app_secret 只能保存在下游服务端。

支付通知签名

payload = merchantId={merchantId}&orderNo={orderNo}&quoteId={quoteId}&amount={amount}&timestamp={timestamp}&nonce={nonce}
signText = payload + "&key=" + app_secret + "&sandbox=false"
sign = SHA256(signText).hexLowercase()

异步通知验签

// 1. 取 JSON 体所有一级字段
// 2. 排除 sign 字段和 null 值字段
// 3. ASCII 升序排列字段名
// 4. 将排序后的字段值序列化为紧凑 JSON 字符串（无空格、无换行）
//    - 对象/Map → 紧凑 JSON（如 {"a":1}）
//    - 数组/List → 紧凑 JSON（如 [1,2,3]）
//    - 其他值按 JSON 语义使用文本值
// 5. expected = HMAC-SHA256(apiSecret, jsonString).hexLowercase()
// 6. 使用常量时间比较 expected 与 X-LYP-Sign

10. 状态码、订单状态与事件

公共业务状态码

订单状态枚举

异步通知事件枚举

11. 成功判定与错误排查

成功判定原则

• 同时检查 HTTP 状态码（应为 200）与 JSON code（应为 200），两者均满足才是接口受理成功。
• 支付成功通知的 code=200 只代表来福受理，不代表充值成功。充值成功以异步通知 orderStatus=SUCCESS 为准。
• 网络超时/连接中断不等于失败，先使用原 orderNo 查单，禁止直接新建订单。

常见错误与排查

12. 幂等机制与重试策略

创建订单防重

merchantRequestNo 是下游业务请求号。下游必须自行保证唯一并持久化它与来福 orderNo 的映射；网络结果不确定时先查已保存的 orderNo，不要假设重复创建必然返回同一订单。

支付通知幂等

相同 orderNo + sign 重复请求被幂等处理。每次须复用完全相同的数据，平台按订单和签名自动去重。

异步通知幂等

下游收到重复通知时，按 orderNo + event + orderStatus 去重。终态通知（SUCCESS/FAILED/REFUNDED）到达后不应再触发用户侧重复处理。

下游重试指南

13. 联调与安全上线门禁

以下为上线前的必检项目，逐项确认后方可切换真实流量。

1. 基本信息确认：商户已审核、权益已开通、应用已启用、产品已授权、固定出口 IP 已加白名单。
2. SKU 价格确认：传 carrierCode 时确认 PrepaidRefill + carrierCode + faceValue 存在唯一有效 SKU；不传时确认该面额三网 SKU 完整且商户结算价、用户支付价一致。
3. 数据持久化：下游保存 merchantRequestNo / orderNo / totalAmount / payAmount 并可对账。
4. 服务端安全：支付回调必须由下游服务端验真；前端/H5 不得直接调用支付成功通知。密钥仅保存在服务端。
5. 边界测试：验证金额不一致、错误签名、重复通知、超时查单和异步通知幂等场景。
6. 不可逆操作：真实话费充值不可逆。未经双方明确授权不得使用真实号码执行测试。联调应使用来福提供的测试手机号。
7. 异步通知验签确认：已按第 9 节算法实现 X-LYP-Sign 验签，并确认使用了 apiSecret 而非 app_secret。
8. 响应处理确认：异步通知收到后返回 HTTP 2xx 且 body 为 ok 或 success。

14. Java 与 Node.js 签名示例

以下示例供参考，生产环境请将密钥配置在安全配置中心或环境变量中。

Java OpenAPI 签名示例

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.Base64;

public class OpenApiSigner {

    public static String sign(String method, String uri, long timestamp,
                              String nonce, String rawBody, String secret) throws Exception {
        String signText = method + "\n" + uri + "\n" + timestamp + "\n" + nonce + "\n";
        if (rawBody != null && !rawBody.isEmpty()) {
            signText += rawBody;
        }
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(secret.getBytes("UTF-8"), "HmacSHA256"));
        byte[] hmac = mac.doFinal(signText.getBytes("UTF-8"));
        String base64 = Base64.getUrlEncoder().withoutPadding().encodeToString(hmac);
        return base64;
    }

    // 使用示例
    public static void main(String[] args) throws Exception {
        String secret = "your-app-secret";
        long timestamp = System.currentTimeMillis() / 1000;
        String nonce = java.util.UUID.randomUUID().toString();
        String body = "{\"typeCode\":\"PrepaidRefill\",\"merchantRequestNo\":\"M202607250001\",\"bizParams\":{\"mobile\":\"13800138000\",\"faceValue\":\"100\",\"notifyUrl\":\"https://merchant.example.com/laifu/notify\"}}";

        String sign = sign("POST", "/openapi/v1/order/create",
                           timestamp, nonce, body, secret);
        System.out.println("sign: " + sign);
    }
}

Java 支付通知签名示例

import java.security.MessageDigest;

public class PaymentNotifySigner {

    public static String sign(long merchantId, String orderNo, String quoteId,
                              String amount, String timestamp, String nonce,
                              String secret) throws Exception {
        String payload = "merchantId=" + merchantId
                       + "&orderNo=" + orderNo
                       + "&quoteId=" + (quoteId == null ? "" : quoteId)
                       + "&amount=" + amount
                       + "&timestamp=" + timestamp
                       + "&nonce=" + nonce;
        String signText = payload + "&key=" + secret + "&sandbox=false";

        MessageDigest md = MessageDigest.getInstance("SHA-256");
        byte[] hash = md.digest(signText.getBytes("UTF-8"));
        StringBuilder hex = new StringBuilder();
        for (byte b : hash) {
            hex.append(String.format("%02x", b & 0xFF));
        }
        return hex.toString();
    }
}

Java 异步通知验签示例

import com.fasterxml.jackson.databind.ObjectMapper;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.*;

public class NotifyVerifier {

    public static boolean verify(String jsonBody,
                                 String apiSecret) throws Exception {
        ObjectMapper mapper = new ObjectMapper();
        Map<String, Object> body = mapper.readValue(jsonBody, Map.class);

        // 1. 排除 sign 和 null 值字段
        TreeMap<String, Object> sorted = new TreeMap<>();
        for (Map.Entry<String, Object> e : body.entrySet()) {
            if ("sign".equals(e.getKey()) || e.getValue() == null) continue;
            sorted.put(e.getKey(), e.getValue());
        }

        // 2. 按 ASCII 排序后的键值对，序列化为紧凑 JSON 字符串
        //    TreeMap 保证字典序；Jackson writeValueAsString 输出紧凑 JSON
        String jsonString = mapper.writeValueAsString(sorted);

        // 3. HMAC-SHA256
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(apiSecret.getBytes("UTF-8"), "HmacSHA256"));
        byte[] hmac = mac.doFinal(jsonString.getBytes("UTF-8"));
        StringBuilder expectedHex = new StringBuilder();
        for (byte b : hmac) {
            expectedHex.append(String.format("%02x", b & 0xFF));
        }

        // 4. 从原始 JSON 体中提取 sign 值做常量时间比较
        String actualSign = (String) body.get("sign");
        return MessageDigest.isEqual(
            expectedHex.toString().getBytes("UTF-8"),
            actualSign.getBytes("UTF-8"));
    }
}

Node.js OpenAPI 签名示例

const crypto = require('crypto');

function sign(method, uri, timestamp, nonce, rawBody, secret) {
  let signText = method + '\n' + uri + '\n' + timestamp + '\n' + nonce + '\n';
  if (rawBody) signText += rawBody;

  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(signText, 'utf8');
  return hmac.digest('base64url'); // Node.js 15.7+ 支持 base64url
}

// 使用示例
const secret = 'your-app-secret';
const timestamp = Math.floor(Date.now() / 1000);
const nonce = crypto.randomUUID();
const body = JSON.stringify({
  typeCode: 'PrepaidRefill',
  merchantRequestNo: 'M202607250001',
  bizParams: {
    mobile: '13800138000',
    faceValue: '100',
    notifyUrl: 'https://merchant.example.com/laifu/notify'
  }
});

const s = sign('POST', '/openapi/v1/order/create',
               timestamp, nonce, body, secret);
console.log('sign:', s);

Node.js 支付通知签名示例

const crypto = require('crypto');

function paymentSign(merchantId, orderNo, quoteId, amount,
                     timestamp, nonce, secret) {
  const payload = `merchantId=${merchantId}&orderNo=${orderNo}` +
    `&quoteId=${quoteId || ''}&amount=${amount}` +
    `&timestamp=${timestamp}&nonce=${nonce}`;
  const signText = payload + `&key=${secret}&sandbox=false`;
  return crypto.createHash('sha256')
    .update(signText, 'utf8')
    .digest('hex');
}

Node.js 异步通知验签示例

const crypto = require('crypto');

function verifyNotify(jsonBody, apiSecret) {
  const body = JSON.parse(jsonBody);

  // 1. 排除 sign 和 null，ASCII 排序后再序列化为紧凑 JSON
  const sorted = {};
  Object.keys(body)
    .filter(k => k !== 'sign' && body[k] !== null)
    .sort()
    .forEach(k => { sorted[k] = body[k]; });

  // 2. 紧凑 JSON 字符串即为签名原文
  const jsonString = JSON.stringify(sorted);

  // 3. HMAC-SHA256 hex
  const hmac = crypto.createHmac('sha256', apiSecret);
  hmac.update(jsonString, 'utf8');
  const expected = hmac.digest('hex');

  // 4. 常量时间比较
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'utf8'),
    Buffer.from(body.sign, 'utf8')
  );
}