MoMo API 对接文档

快速开始

先创建任务，再使用响应中的 job_id 和 job_secret 查询结果。

POST/api/v1/momo/checkout

curl -sS https://hahz7zf.ink/api/v1/momo/checkout \
  -H "Content-Type: application/json" \
  -d '{
    "session": "<SESSION>",
    "entry_proxies": [
      "http://<PROXY_USER>:<PROXY_PASSWORD>@<PROXY_HOST>:<PROXY_PORT>"
    ]
  }'

创建成功返回 HTTP 202：

{
  "ok": true,
  "job_id": "<JOB_ID>",
  "job_secret": "<JOB_SECRET>",
  "status": "queued",
  "queue_position": 1
}

curl -sS https://hahz7zf.ink/api/v1/jobs/<JOB_ID> \
  -H "X-Momo-Job-Secret: <JOB_SECRET>"

请求参数

单个接口使用 session，批量接口使用 sessions。Token、Session JSON 和代理都由调用方在每次请求中提供。

字段	类型	必填	说明
`session`	string	单个任务是	Access Token 或完整 Session JSON。
`sessions`	string[]	批量任务是	每项一套凭证，单批最多 100 套。
`entry_proxies`	string[]	否	代理池，最多读取前 500 条；任务每次 Checkout 最多尝试 3 条。
`proxy`	string	否	单代理简写；存在 `entry_proxies` 时忽略。
`timeout`	integer	否	上游请求超时秒数，默认 25，范围 8–120。
`trial_days`	integer	否	试用天数，默认 30，范围 1–90。
`retry_count`	integer	否	兼容字段；服务端始终固定为 5 次。
`auto_pay`	boolean	否	提链成功后自动提交 MoMo 支付。
`auto_payment_cdk`	string	自动支付时是	自动支付接口 CDK；服务端只在任务内存中临时使用。
`strategy`	string	否	默认 `custom_promo`，通常无需传入。
`pre_proxy`	string	否	默认 `off`，通常无需传入。

创建单个提链任务

POST/api/v1/momo/checkout

session 必填。请求进入共享调度器后返回 202，超过运行上限时自动排队；达到排队安全上限时返回 429 queue_full。

{
  "session": "<SESSION>",
  "entry_proxies": ["http://<PROXY>"],
  "timeout": 25,
  "trial_days": 30,
  "retry_count": 5,
  "auto_pay": true,
  "auto_payment_cdk": "MOMO-XXXX-XXXX-XXXX"
}

创建批量提链任务

POST/api/v1/momo/checkout/batch

每个有效账号会获得独立的 job_id 和 job_secret。空项不会创建任务，并会出现在 rejected 中。

{
  "sessions": ["<SESSION_1>", "<SESSION_2>"],
  "entry_proxies": ["http://<PROXY>"],
  "retry_count": 5,
  "auto_pay": true,
  "auto_payment_cdk": "MOMO-XXXX-XXXX-XXXX"
}

{
  "ok": true,
  "jobs": [
    {
      "job_id": "<JOB_ID_1>",
      "job_secret": "<JOB_SECRET_1>",
      "row": 1,
      "queue_position": 0
    }
  ],
  "rejected": []
}

查询与停止任务

GET/api/v1/jobs/{job_id}

curl -sS https://hahz7zf.ink/api/v1/jobs/<JOB_ID> \
  -H "X-Momo-Job-Secret: <JOB_SECRET>"

响应中的 job 只包含公开任务状态、进度、脱敏日志与结果，不返回原始 Session、代理配置或任务密钥。

POST/api/v1/jobs/{job_id}/cancel

curl -sS -X POST https://hahz7zf.ink/api/v1/jobs/<JOB_ID>/cancel \
  -H "Content-Type: application/json" \
  -H "X-Momo-Job-Secret: <JOB_SECRET>" \
  -d '{}'

MoMo 资格检测

POST/api/v1/momo/eligibility

单账号传 session，批量账号传 sessions。创建后使用资格任务自己的密钥查询。

{
  "sessions": ["<SESSION_1>", "<SESSION_2>"],
  "entry_proxies": ["http://<PROXY>"]
}

GET/api/v1/eligibility/{job_id}

curl -sS https://hahz7zf.ink/api/v1/eligibility/<JOB_ID> \
  -H "X-Momo-Job-Secret: <JOB_SECRET>"

单项检测状态包括 eligible、ineligible_momo、ineligible_amount、pending 和 error。

健康与容量

GET/api/v1/health

GET/api/v1/capacity

这两个只读接口不需要任务密钥。容量响应包含全站、当前访问者和当前 IP 的运行数、排队数与上限。

状态与错误

任务状态	含义
`queued`	任务已创建，正在等待调度。
`running`	正在创建链接、等待付款确认或同步 Plus 状态。
`succeeded`	提链成功，或付款与 Plus 到账均已确认。
`done`	上游监听已结束，但 Plus 最终状态仍需按结果字段判断。
`failed`	提链或回调处理失败，查看 `error` 与日志。
`cancelled`	任务已停止。

HTTP	常见错误	处理
`200`	—	查询或停止成功。
`202`	—	任务已创建并进入运行或排队。
`400`	`missing session`、`missing sessions`	检查请求字段、单批数量和参数类型。
`403`	`job_forbidden`	检查任务类型、任务编号和请求头中的任务密钥。
`409`	`auto_payment_in_flight`	自动支付已经提交，等待上游终态后再操作。
`404`	`job_not_found`	任务不存在，或终态任务已超过保留时间。
`415`	`json_required`	设置 `Content-Type: application/json`。
`429`	`queue_full`	访问者、IP 或全站待处理任务达到安全上限，请延迟重试。

Python 完整示例

把 Session 和代理放在环境变量中，任务密钥只保存在当前进程内存里。

import os
import time

import requests


BASE_URL = "https://hahz7zf.ink"
SESSION = os.environ["MOMO_SESSION"]
PROXY = os.environ.get("MOMO_PROXY", "").strip()

payload = {
    "session": SESSION,
    "retry_count": 5,
}
if PROXY:
    payload["entry_proxies"] = [PROXY]

created = requests.post(
    f"{BASE_URL}/api/v1/momo/checkout",
    json=payload,
    timeout=30,
)
created.raise_for_status()
task = created.json()

job_id = task["job_id"]
headers = {"X-Momo-Job-Secret": task["job_secret"]}

while True:
    response = requests.get(
        f"{BASE_URL}/api/v1/jobs/{job_id}",
        headers=headers,
        timeout=30,
    )
    response.raise_for_status()
    job = response.json()["job"]
    print(job["status"], job.get("percent"), job.get("text"))

    if job["status"] in {"succeeded", "done", "failed", "cancelled"}:
        print(job.get("result") or {"error": job.get("error")})
        break

    time.sleep(2)

安全使用

推荐由自己的后端调用；公网默认不提供跨域浏览器调用。
不要把 Session、代理凭证或 job_secret 写入前端源码、URL、公开日志和分析平台。
每个任务使用独立密钥；不要拿一个任务的密钥查询另一个任务。
自动支付 CDK 通过 HTTPS 请求提交；后端只在任务内存中临时使用，不写入任务响应和日志。
客户端只记录 job_id、终态和必要业务结果；任务结束后删除临时密钥。
文档页面本身不执行脚本、不读取浏览器存储，也不调用任何 API。