0. 统一响应结构 (Response Envelope) 0. Unified Response Envelope

成功响应示例 (200 / 202) Success Response Sample

{
  "success": true,
  "code": 200,
  "message": "",
  "result": { ... }
}

失败响应示例 (业务校验错误) Failure Response Sample (Business / Validation)

{
  "success": false,
  "code": 400,
  "message": "Account does not exist or is invalid",
  "result": {
    "errorCode": "RECHARGE_REJECTED",
    "traceId": "a1b2c3d4"
  }
}

失败响应示例 (网关鉴权 / IP / 限流前置拦截) Failure Response Sample (Pre-API Auth / Security / Rate Limit)

// HTTP Response Headers:
// X-Trace-Id: 7f8a9b0c1d2e3f4a

{
  "success": false,
  "code": 403,
  "message": "Source IP is not allowed",
  "result": {
    "errorCode": "IP_NOT_ALLOWED"
  }
}

1. 接口成功响应对照表 1. Endpoint Success Responses

2. 授权认证、安全与限流错误码 (网关前置校验) 2. Authentication, Security & Rate Limiting Codes

3. 业务错误码 (Business Error Codes) 3. Business Error Codes

*注：对于 RECHARGE_REJECTED，HTTP 状态码透传下游业务状态码（通常为 400）。若下游未返回状态码或返回 5xx，则自动降级为 502。若批次号冲突则单独返回 409（BATCH_REQUEST_NO_EXISTS）。 *Note: For RECHARGE_REJECTED, the HTTP status is the upstream status returned for a business rejection (typically 400). If upstream returns 5xx or null, HTTP status degrades to 502. 409 conflict is reported as BATCH_REQUEST_NO_EXISTS.

4. RECHARGE_REJECTED 业务拒绝提示明细 (HTTP 400) 4. RECHARGE_REJECTED Rejection Reasons (HTTP 400)

5. 响应不一致异常明细 (HTTP 502) 5. Inconsistent Response Messages (HTTP 502)

6. 批量充值子单明细错误 (Batch Item-Level Errors) 6. Batch Item-Level Errors (202 Accepted Items)

1. 公共请求头参数 (Headers) 1. Common Request Headers

每次调用接口时，客户端必须在 Request Header 中包含以下字段： The client must include the following headers on every API invocation:

注意：Notice: 必须妥善保管与 App Key 对应的 App Secret，绝对不要将其放在请求中传输。App Secret 仅用于在本地计算签名。 Keep your App Secret confidential. Never transmit it over HTTP/HTTPS. It is used strictly for local signature generation.

2. 签名计算规则 2. Signature Calculation Process

签名的生成依赖于 HMAC-SHA256 算法，最终输出为 Base64 编码字符串，分为以下三个步骤： The signature is generated using HMAC-SHA256 and encoded in Base64, structured in three steps:

HTTP_METHOD + "
" +
REQUEST_PATH + "
" +
RAW_QUERY + "
" +
X_TIMESTAMP + "
" +
X_NONCE + "
" +
BODY_HASH

Signature = Base64(HMAC_SHA256(CanonicalRequest, AppSecret))

3. 代码示例 3. Code Samples

Java (Pure JDK javax.crypto)

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.Base64;

public class SignUtil {
    public static String sha256Hex(String data) {
        try {
            MessageDigest digest = MessageDigest.getInstance("SHA-256");
            byte[] hash = digest.digest((data == null ? "" : data).getBytes(StandardCharsets.UTF_8));
            StringBuilder hexString = new StringBuilder();
            for (byte b : hash) {
                String hex = Integer.toHexString(0xff & b);
                if (hex.length() == 1) hexString.append('0');
                hexString.append(hex);
            }
            return hexString.toString();
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }

    public static String hmacSha256Base64(String data, String secret) {
        try {
            Mac mac = Mac.getInstance("HmacSHA256");
            SecretKeySpec keySpec = new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
            mac.init(keySpec);
            return Base64.getEncoder().encodeToString(mac.doFinal(data.getBytes(StandardCharsets.UTF_8)));
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }

    public static String generateSignature(String method, String path, String rawQuery,
                                           String timestamp, String nonce, String body, String secret) {
        String bodyHash = sha256Hex(body == null ? "" : body);
        String canonicalRequest = String.join("
",
                method.toUpperCase(), path, rawQuery == null ? "" : rawQuery,
                timestamp, nonce, bodyHash);
        return hmacSha256Base64(canonicalRequest, secret);
    }
}

JavaScript (CryptoJS / Node.js)

const CryptoJS = require("crypto-js");

function generateSignature({ method, path, rawQuery = "", timestamp, nonce, body = "", secret }) {
    const bodyHash = CryptoJS.SHA256(CryptoJS.enc.Utf8.parse(body)).toString(CryptoJS.enc.Hex);
    const canonicalRequest = [
        method.toUpperCase(), path, rawQuery, timestamp, nonce, bodyHash
    ].join("
");
    return CryptoJS.enc.Base64.stringify(CryptoJS.HmacSHA256(canonicalRequest, secret));
}

接口说明 Endpoint Overview

请求 Header 参数 Request Headers

请求 Body (application/json) Request Body (application/json)

{
  "clientRequestNo": "APIFOX-20260915-0005",
  "accountId": "333333",
  "amount": 27
}

返回响应 (202 Accepted) Response (202 Accepted)

{
    "success": true,
    "message": "充值请求已受理",
    "code": 202,
    "result": {
        "orderNo": "RC202609070001",
        "clientRequestNo": "APIFOX-20260907-0001",
        "status": "PROCESSING"
    },
    "timestamp": 1788786000000
}

接口说明 Endpoint Overview

请求 Header 参数 Request Headers

路径参数 (Path Parameters) Path Parameters

返回响应示例 (200 OK) Response Example (200 OK)

{
    "success": true,
    "code": 200,
    "message": "查询成功",
    "result": {
        "orderNo": "RC202609070001",
        "clientRequestNo": "APIFOX-20260915-0005",
        "accountId": "333333",
        "amount": 27,
        "status": "SUCCESS",
        "failReason": null,
        "finishTime": "2026-09-15 10:20:30"
    },
    "timestamp": 1788786050000
}

接口说明 Endpoint Overview

请求 Header 参数 Request Headers

路径参数 (Path Parameters) Path Parameters

返回响应示例 (200 OK) Response Example (200 OK)

{
    "success": true,
    "code": 200,
    "message": "查询成功",
    "result": {
        "orderNo": "RC202609070001",
        "clientRequestNo": "APIFOX-20260915-0005",
        "accountId": "333333",
        "amount": 27,
        "status": "SUCCESS",
        "finishTime": "2026-09-15 10:20:30"
    },
    "timestamp": 1788786050000
}

接口说明 Endpoint Overview

请求 Header 参数 Request Headers

请求 Body (application/json) Request Body (application/json)

{
  "batchNo": "BATCH-20260915-001",
  "items": [
    {
      "subRequestNo": "REQ-001",
      "accountId": "333333",
      "amount": 50
    },
    {
      "subRequestNo": "REQ-002",
      "accountId": "444444",
      "amount": 100
    }
  ]
}

返回响应 (202 Accepted) Response (202 Accepted)

{
    "success": true,
    "message": "批量充值已持久化受理",
    "code": 202,
    "result": {
        "platformBatchNo": "BAT20260915000001",
        "batchNo": "BATCH-20260915-001",
        "totalCount": 2,
        "status": "PROCESSING"
    },
    "timestamp": 1788786100000
}

接口说明 Endpoint Overview

请求 Header 参数 Request Headers

路径参数 (Path Parameters) Path Parameters

返回响应示例 (200 OK) Response Example (200 OK)

{
    "success": true,
    "code": 200,
    "message": "查询成功",
    "result": {
        "batchNo": "BATCH-20260915-001",
        "platformBatchNo": "BAT20260915000001",
        "totalCount": 2,
        "successCount": 2,
        "failCount": 0,
        "status": "COMPLETED",
        "details": [
            {
                "subRequestNo": "REQ-001",
                "orderNo": "RC202609150001",
                "accountId": "333333",
                "amount": 50,
                "status": "SUCCESS"
            },
            {
                "subRequestNo": "REQ-002",
                "orderNo": "RC202609150002",
                "accountId": "444444",
                "amount": 100,
                "status": "SUCCESS"
            }
        ]
    },
    "timestamp": 1788786200000
}

接口说明 Endpoint Overview

请求 Header 参数 Request Headers

请求 Body (application/json) Request Body (application/json)

Body JSON Sample:

{
  "eventId": "evt_2100831915776983042_SUCCESS",
  "eventType": "RECHARGE_STATUS_CHANGED",
  "appKey": "meta_E-HNGb7FfzM916trGCWiA9dB",
  "customerId": "93",
  "orderNo": "2100831915776983042",
  "clientRequestNo": "APIFOX-20260908-00874",
  "accountId": "c9dabd2aa2a311f1b5b60242c0a80002",
  "amount": 1,
  "status": "SUCCESS",
  "failureCode": null,
  "failureReason": null,
  "occurredAt": "2026-09-18T14:23:48.777+08:00"
}