verify-et-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Verify.et API

This portable skill applies to backend integrations in Node.js, Python, PHP, Go, Java, Ruby, .NET, Rust, and mobile apps that proxy through a trusted backend.

该可移植 skill 适用于 Node.js、Python、PHP、Go、Java、Ruby、.NET、Rust 中的后端集成，以及通过可信后端进行代理的移动应用。

Core Workflow

核心工作流

Identify the integration surface: backend REST adapter, checkout/payment verification, webhook receiver, polling/SSE status UI, dashboard/reporting usage, or framework-specific wrapper.
Load only the references needed:
- ```
references/api-endpoints.md
```
  for auth, endpoints, payloads, responses, permissions, and status flow.
- ```
references/bank-specs.md
```
  for explicit bank payloads and universal-router disambiguators.
- ```
references/error-codes.md
```
  for HTTP failures, verification error codes, retry decisions, credits, quotas, and idempotency conflicts.
- ```
patterns/integration-methods.md
```
  for choosing sync, queued, webhook, polling, or SSE flows.
- ```
patterns/webhooks.md
```
  for account webhook setup (dashboard or API), the signing secret, test delivery, signatures, and retries.
- ```
patterns/image-processing.md
```
  for opt-in receipt photos, QR then OCR, image credits, and multipart upload.
- ```
debugging/common-mistakes.md
```
  for production anti-patterns.
- ```
debugging/production-checklist.md
```
  for pre-launch validation.
Inspect the user's code before changing it. Find where API keys and
```
VERIFY_ET_WEBHOOK_SECRET
```
are stored, where
```
POST /api/verify
```
is called, whether an account webhook is active, whether a receipt photo is sent as multipart, how
```
202
```
is handled, whether duplicate submissions are possible, and whether Verify.et calls run server-side.
Keep Verify.et API keys server-side. Browser and mobile clients should call the user's backend, not Verify.et directly.
Prefer one small server-side Verify.et client/adapter over scattered raw
```
fetch
```
calls.
Send an
```
Idempotency-Key
```
for payment and checkout attempts, and persist the returned Verify.et
```
requestId
```
.
Treat
```
200
```
as an inline terminal response and
```
202
```
as queued work. Register one account webhook, save its
```
whsec_
```
secret, and prove the endpoint is
```
active
```
before relying on it. For
```
202
```
, store
```
requestId
```
. Use polling or SSE only when a screen needs progress. Leave
```
webhookUrl
```
off once that endpoint is active. Details are in
```
patterns/webhooks.md
```
.
Treat
```
confirmationHistory.confirmedBefore === true
```
as a repeat-confirmation signal. Do not fulfill blindly without applying the product's duplicate-payment policy.
Add focused tests at the user's boundary: request builder tests, webhook signature tests, image-upload tests, polling tests, idempotency conflict tests, and error mapping tests.

确定集成界面：后端 REST adapter、结账/支付验证、webhook 接收器、polling/SSE 状态界面、Dashboard/报表使用场景，或特定框架的 wrapper。
仅加载所需的参考资料：
- ```
references/api-endpoints.md
```
  ：认证、端点、payload、响应、权限和状态流。
- ```
references/bank-specs.md
```
  ：明确的银行 payload 和通用 router 消歧标识。
- ```
references/error-codes.md
```
  ：HTTP 失败、验证错误码、重试决策、credits、quota 和幂等冲突。
- ```
patterns/integration-methods.md
```
  ：选择同步、队列、webhook、polling 或 SSE 流程。
- ```
patterns/webhooks.md
```
  ：账户 webhook 设置（Dashboard 或 API）、签名密钥、测试投递、签名和重试。
- ```
patterns/image-processing.md
```
  ：可选的收据照片、QR 优先于 OCR、图像 credits 和 multipart 上传。
- ```
debugging/common-mistakes.md
```
  ：生产环境反模式。
- ```
debugging/production-checklist.md
```
  ：上线前验证。
修改用户代码前先检查代码。查明 API key 和
```
VERIFY_ET_WEBHOOK_SECRET
```
的存储位置、
```
POST /api/verify
```
的调用位置、账户 webhook 是否已启用、收据照片是否以 multipart 方式发送、
```
202
```
如何处理、是否可能重复提交，以及 Verify.et 调用是否在服务端执行。
将 Verify.et API key 保留在服务端。浏览器和移动客户端应调用用户的后端，而不是直接调用 Verify.et。
优先使用一个精简的服务端 Verify.et client/adapter，避免分散的原始
```
fetch
```
调用。
为支付和结账请求发送
```
Idempotency-Key
```
，并持久化返回的 Verify.et
```
requestId
```
。
将
```
200
```
视为即时终态响应，将
```
202
```
视为排队任务。注册一个账户 webhook，保存其
```
whsec_
```
密钥，并确认端点状态为
```
active
```
后再依赖它。对于
```
202
```
，存储
```
requestId
```
。仅当界面需要显示进度时使用 polling 或 SSE。端点激活后，在验证请求中省略
```
webhookUrl
```
。详细信息见
```
patterns/webhooks.md
```
。
将
```
confirmationHistory.confirmedBefore === true
```
视为重复确认信号。未应用产品的重复支付策略前，不要盲目执行履约。
在用户系统边界添加有针对性的测试：请求构建器测试、webhook 签名测试、图像上传测试、polling 测试、幂等冲突测试和错误映射测试。

Integration Decisions

集成决策

Use
```
POST /api/verify?waitMs=...
```
only as a best-effort convenience. Production workflows must still work when Verify.et returns
```
202
```
.
Register one account webhook when the backend must learn the result even if the browser or mobile app closes. The user can add it under API Keys → Webhooks, or call
```
POST /api/webhook-endpoints
```
with their API key. Save the secret, prove the endpoint is active, then leave
```
webhookUrl
```
off the verify request.
Use polling when the client needs a simple pending-status screen.
Use SSE when an authenticated web UI needs lower-latency updates without frequent polling.
Use both webhooks and polling/SSE for robust checkout UX: webhook updates server truth; polling/SSE updates the visible user flow.
Use explicit
```
bank
```
payloads when the product already knows the provider. Use universal
```
reference
```
payloads when the UI accepts mixed receipts or links. Optional
```
settlementAccount
```
checks that the receipt paid the expected receiver; details are in
```
references/api-endpoints.md
```
.
Send a receipt photo only as an optional multipart
```
image
```
after Image Processing is enabled. QR and OCR are chosen by Verify.et. See
```
patterns/image-processing.md
```
.
Put irreversible fulfillment behind terminal state checks, duplicate-confirmation policy checks, and
```
settlementAccountMatch
```
when the product uses receiver matching.

仅将
```
POST /api/verify?waitMs=...
```
作为最佳努力的便捷方案。即使 Verify.et 返回
```
202
```
，生产工作流也必须能够正常运行。
当后端需要在浏览器或移动应用关闭后仍能获知结果时，注册一个账户 webhook。用户可以在 API Keys → Webhooks 中添加，也可以使用 API key 调用
```
POST /api/webhook-endpoints
```
。保存密钥并确认端点已激活，然后在验证请求中省略
```
webhookUrl
```
。
当客户端需要简单的待处理状态界面时，使用 polling。
当已认证的 Web UI 需要低延迟更新且不想频繁轮询时，使用 SSE。
为构建稳健的结账体验，可同时使用 webhook 和 polling/SSE：webhook 更新服务端权威状态，polling/SSE 更新用户可见的交互流程。
当产品已知付款机构时，使用明确的
```
bank
```
payload；当 UI 接受混合收据或链接时，使用通用的
```
reference
```
payload。可选的
```
settlementAccount
```
检查可用于确认收据中的付款是否支付给预期接收方；详细信息见
```
references/api-endpoints.md
```
。
仅在启用 Image Processing 后，才将收据照片作为可选的 multipart
```
image
```
发送。使用 QR 还是 OCR 由 Verify.et 决定。参见
```
patterns/image-processing.md
```
。
仅在通过终态检查和重复确认策略检查后才执行不可逆履约；当产品使用接收方匹配时，还必须通过
```
settlementAccountMatch
```
检查。

Debugging Baseline

调试基线

Before diagnosing, capture:

Request method, URL, body shape, headers used, and whether the API key was server-side.
HTTP status, response body,
```
x-request-id
```
,
```
Retry-After
```
, and
```
X-Verify-Cache
```
.

Verify.et

requestId

processingStatus

status

error.code

, and

error.retryable

Bank/provider, raw receipt/reference, suffix/phone/settlementAccount disambiguators, account webhook status, image-processing enabled state and balance, and any legacy per-request webhook URL.
Whether the same checkout attempt reused the same
```
Idempotency-Key
```
.

诊断前先收集：

请求方法、URL、body 结构、使用的 headers，以及 API key 是否位于服务端。
HTTP 状态、响应 body、
```
x-request-id
```
、
```
Retry-After
```
和
```
X-Verify-Cache
```
。

Verify.et 的

requestId

、

processingStatus

、

status

、

error.code

和

error.retryable

。

银行/付款机构、原始 receipt/reference、用于消歧的 suffix/phone/settlementAccount、账户 webhook 状态、图像处理启用状态和余额，以及是否仍使用旧式的按请求 webhook URL。
同一次结账尝试是否复用了相同的
```
Idempotency-Key
```
。

Security Rules

安全规则

Do not place
```
x-api-key
```
or
```
whsec_
```
values in frontend code, mobile apps, logs, screenshots, or committed files.
Do not trust a webhook payload before the endpoint secret verifies the raw body. Rules are in
```
patterns/webhooks.md
```
.
Store
```
VERIFY_ET_WEBHOOK_SECRET
```
in the server environment that serves the receiver. The API returns that secret once.
Make webhook processing idempotent by
```
X-Webhook-Event-Id
```
.
Honor
```
Retry-After
```
for rate limits and temporary unavailability.
Keep logs useful but redacted: include
```
requestId
```
, bank, status, and error code; omit API keys, cookies, receipt image bytes, and full authorization headers.

不要将
```
x-api-key
```
或
```
whsec_
```
值放入前端代码、移动应用、日志、截图或已提交的文件中。
在端点密钥验证原始 body 之前，不要信任 webhook payload。相关规则见
```
patterns/webhooks.md
```
。
将
```
VERIFY_ET_WEBHOOK_SECRET
```
存储在承载接收器的服务端环境中。API 仅会返回该密钥一次。
基于
```
X-Webhook-Event-Id
```
实现 webhook 处理的幂等性。
遇到速率限制或临时不可用时，遵守
```
Retry-After
```
。
日志应保持实用但经过脱敏：包含
```
requestId
```
、银行、状态和错误码；排除 API key、cookies、收据图像字节和完整的 authorization headers。

Dashboard Setup

Dashboard 设置

Webhook registration can be done with the API key. Image Processing enablement and image-credit top-ups cannot. Other account settings may also exist only in the dashboard.

When one of those settings is missing:

Say what is missing, which page changes it, and what to copy back into the project.
Ask the user to choose. They can do it themselves, or they can explicitly allow a browser or computer-use tool to do it while they are signed in.
Do not open a browser, sign in, click through verify.et, or enable a plugin until they choose help for that task. A general request to integrate Verify.et is not that permission.
If no browser tool is available, ask before installing or enabling one.
Do not ask for, store, or type their password. They sign in themselves.
Do not submit a payment or image-credit top-up unless they explicitly ask to complete that payment and give the pack and payment reference.
After either path, prove the setting with the API. Webhook proof is in
```
patterns/webhooks.md
```
. Image Processing proof is
```
data.enabled: true
```
and a positive
```
data.balance
```
from
```
GET /api/image-processing
```
.

Webhook 注册可以使用 API key 完成，但启用 Image Processing 和充值 image credits 无法通过 API 完成。其他账户设置也可能仅能在 Dashboard 中修改。

缺少其中某项设置时：

说明缺少什么、哪个页面可以修改，以及需要复制回项目的内容。
让用户选择：由用户自行完成，或明确允许 browser 或 computer-use tool 在用户登录后代为完成。
在用户选择为该任务提供协助之前，不要打开 browser、登录、点击操作 verify.et 或启用 plugin。一般的 Verify.et 集成请求并不构成此类授权。
如果没有可用的 browser 工具，请在安装或启用前征求用户同意。
不要索取、存储或输入用户密码。用户应自行登录。
除非用户明确要求完成付款并提供套餐和支付 reference，否则不要提交付款或 image-credit 充值。
无论采用哪种方式，都通过 API 验证设置。Webhook 验证方式见
```
patterns/webhooks.md
```
。Image Processing 的验证条件为
```
data.enabled: true
```
，且
```
GET /api/image-processing
```
返回正的
```
data.balance
```
。

Sources

来源

Use the current public docs when internet access is available:

```
https://verify.et/docs/get-started
```
```
https://verify.et/docs/api
```
```
https://verify.et/docs/sdk
```

If working inside the Verify.et repository, prefer implementation source over stale docs. Relevant source paths are listed in

references/api-endpoints.md

可以访问互联网时，使用当前公开文档：

```
https://verify.et/docs/get-started
```
```
https://verify.et/docs/api
```
```
https://verify.et/docs/sdk
```

如果在 Verify.et 仓库中工作，应优先参考实现源代码，而不是可能过时的文档。相关源码路径列于

references/api-endpoints.md

。