支付宝实名认证 API 文档

注意事项： 使用本接口前，请确保已在原平台购买“支付宝实名认证”服务，并配置好域名白名单和API Key。

接口概述

本接口通过支付宝官方渠道完成用户实名认证，包含两个步骤：发起认证和查询结果。用户扫码或跳转授权后，系统自动回调处理，您只需通过查询接口获取最终结果。

请求地址

POST https://api.mcve.top/API.php?action=api_gateway

通用请求头

参数	必填	说明
X-API-Key	是	您的API Key（原平台用户中心获取）
Content-Type	是	application/json

1. 发起认证 (realname_start)

请求体

{
    "api_code": "ALIPAY_REALNAME",
    "action": "realname_start",
    "params": {
        "user_name": "张三",
        "cert_no": "110101199001011234",
        "mobile": "13800138000",
        "logon_id": "zhangsan@alipay.com"
    }
}

成功响应

{
    "code": 0,
    "msg": "ok",
    "data": {
        "token": "a1b2c3d4e5f6g7h8i9j0",
        "verify_id": "20260221abcdef123456",
        "auth_url": "https://openauth.alipay.com/...",
        "qr_text": "https://openauth.alipay.com/..."
    }
}

2. 查询认证结果 (realname_result)

请求体

{
    "api_code": "ALIPAY_REALNAME",
    "action": "realname_result",
    "params": {
        "token": "a1b2c3d4e5f6g7h8i9j0"
    }
}

成功响应

{
    "code": 0,
    "msg": "ok",
    "data": {
        "status": 2,
        "passed": "T",
        "fail_reason": null,
        "fail_params": null,
        "updated_at": "2026-02-21 15:30:00"
    }
}

错误码说明

code	说明
0	成功
400	参数错误
401	API Key无效
403	未授权（域名/未购买）
404	token不存在
429	请求频繁
500	服务器错误

完整流程示例

# 1. 发起认证
curl -X POST https://api.mcve.top/API.php?action=api_gateway \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"api_code":"ALIPAY_REALNAME","action":"realname_start","params":{"user_name":"张三","cert_no":"110101199001011234"}}'

# 2. 引导用户访问 auth_url 完成授权

# 3. 轮询查询结果（建议间隔3秒）
curl -X POST https://api.mcve.top/API.php?action=api_gateway \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"api_code":"ALIPAY_REALNAME","action":"realname_result","params":{"token":"a1b2c3d4e5f6g7h8i9j0"}}'