# Ethoca 报备状态通知

> Ethoca 报备状态变更通知的字段、验签和应答要求。

```yaml
openapi: 3.1.0
info:
  title: Ethoca 报备状态通知
  version: 1.0.0
  description: Ethoca 报备状态变更通知的字段、验签和应答要求。
webhooks:
  ethoca.enrollment.changed:
    post:
      summary: Ethoca 报备状态通知
      description: Ethoca 报备状态变更通知的字段、验签和应答要求。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: number
                  description: 申请单号。
                  x-onerway-constraints:
                    - kind: rule
                      text: 该 JSON 数字可能超出 JavaScript 安全整数范围。解析 JSON 时须无损保留完整十进制值，用于验签和应答。
                    - kind: rule
                      text: 同一申请的不同状态变化可携带相同 `id`，不要仅凭该字段对通知去重。
                  x-onerway-signature-participation: included
                merchantNo:
                  type: number
                  description: Onerway 分配的商户号，标识商户账户。
                  x-onerway-signature-participation: included
                preDisputeService:
                  type: string
                  description: 申请对应的服务类型，固定为 `ETHOCA_ALERT`。
                  enum:
                    - ETHOCA_ALERT
                  x-enum-descriptions:
                    ETHOCA_ALERT: Ethoca 拒付预警服务。
                  x-onerway-signature-participation: included
                billDesc:
                  type: string
                  description: 申请中登记的商户账单描述，即持卡人账单上显示的商户描述。
                  x-onerway-signature-participation: included
                resellerSubMerchantId:
                  type: string
                  description: 代理运营商的子商户标识。
                  x-onerway-signature-participation: included
                fromEnrollmentStatus:
                  type: string
                  description: 本次变更前的申请状态。
                  enum:
                    - PENDING_SUBMISSION
                    - SUBMITTED_AND_PENDING_ENROLLMENT
                    - ENROLLING
                    - ENROLLED
                    - ENROLLMENT_FAILED
                    - SUBMITTED_AND_PENDING_DISENROLLMENT
                    - DISENROLLING
                    - DISENROLLED
                  x-enum-descriptions:
                    PENDING_SUBMISSION: 待提交。
                    SUBMITTED_AND_PENDING_ENROLLMENT: 已提交，等待开通。
                    ENROLLING: 开通中。
                    ENROLLED: 已开通，服务已生效。
                    ENROLLMENT_FAILED: 开通失败。
                    SUBMITTED_AND_PENDING_DISENROLLMENT: 已提交，等待关闭服务。
                    DISENROLLING: 关闭中。
                    DISENROLLED: 已关闭，服务已停用。
                  x-onerway-signature-participation: included
                enrollmentStatus:
                  type: string
                  description: 本次变更后的申请状态。
                  enum:
                    - PENDING_SUBMISSION
                    - SUBMITTED_AND_PENDING_ENROLLMENT
                    - ENROLLING
                    - ENROLLED
                    - ENROLLMENT_FAILED
                    - SUBMITTED_AND_PENDING_DISENROLLMENT
                    - DISENROLLING
                    - DISENROLLED
                  x-enum-descriptions:
                    PENDING_SUBMISSION: 待提交。
                    SUBMITTED_AND_PENDING_ENROLLMENT: 已提交，等待开通。
                    ENROLLING: 开通中。
                    ENROLLED: 已开通，服务已生效。
                    ENROLLMENT_FAILED: 开通失败。
                    SUBMITTED_AND_PENDING_DISENROLLMENT: 已提交，等待关闭服务。
                    DISENROLLING: 关闭中。
                    DISENROLLED: 已关闭，服务已停用。
                  x-onerway-constraints:
                    - kind: rule
                      text: 不要假定每种申请状态变化都会触发通知。
                  x-onerway-signature-participation: included
                notes:
                  type: string
                  description: 申请或状态变更备注。
                  x-onerway-signature-participation: included
                comments:
                  type: string
                  description: 申请的审核意见。
                  x-onerway-signature-participation: included
                createOpr:
                  type: string
                  description: 创建申请记录的操作人。
                  x-onerway-signature-participation: included
                createTime:
                  type: string
                  description: 申请记录创建时间。
                  x-onerway-constraints:
                    - kind: rule
                      text: 格式为 `yyyy-MM-dd HH:mm:ss`。
                  x-onerway-signature-participation: included
                updateOpr:
                  type: string
                  description: 最近一次更新申请记录的操作人。
                  x-onerway-signature-participation: included
                updateTime:
                  type: string
                  description: 申请记录更新时间。
                  x-onerway-constraints:
                    - kind: rule
                      text: 格式为 `yyyy-MM-dd HH:mm:ss`。
                  x-onerway-signature-participation: included
                sign:
                  type: string
                  description: 通知签名。使用当前环境的 `SECRET`，按 [Payments
                    签名算法](/zh/payments/get-started/request-signing)验签。
                  x-onerway-constraints:
                    - kind: rule
                      text: 计算签名时排除 `sign` 字段自身。
                  x-onerway-signature-participation: signature-field
            examples:
              onerway_review_approved:
                summary: Ethoca 开通中
                value:
                  id: 100001
                  merchantNo: 100000
                  preDisputeService: ETHOCA_ALERT
                  billDesc: EXAMPLE STORE US
                  resellerSubMerchantId: demo_sub_merchant_001
                  fromEnrollmentStatus: SUBMITTED_AND_PENDING_ENROLLMENT
                  enrollmentStatus: ENROLLING
                  notes: Example enrollment request
                  comments: Example review approved
                  createOpr: demo_operator
                  createTime: 2026-09-01 10:00:00
                  updateOpr: demo_reviewer
                  updateTime: 2026-09-01 10:01:00
                  sign: replace_with_sha256_signature
              ethoca_enrollment_completed:
                summary: Ethoca 已开通
                value:
                  id: 100001
                  merchantNo: 100000
                  preDisputeService: ETHOCA_ALERT
                  billDesc: EXAMPLE STORE US
                  resellerSubMerchantId: demo_sub_merchant_001
                  fromEnrollmentStatus: ENROLLING
                  enrollmentStatus: ENROLLED
                  notes: Example enrollment request
                  comments: Example enrollment completed
                  createOpr: demo_operator
                  createTime: 2026-09-01 10:00:00
                  updateOpr: demo_reviewer
                  updateTime: 2026-09-01 10:02:00
                  sign: replace_with_sha256_signature
      responses:
        "200":
          description: 验签通过并受理通知后，返回 HTTP 200，Content-Type 为 text/plain。响应体须原样返回收到的 id
            值，不得丢失精度。未收到成功响应时，Onerway 以 30 分钟间隔重试，最多 3 次。
          content:
            text/plain:
              schema:
                type: string
              examples:
                return_enrollment_id:
                  summary: 返回收到的申请单号
                  value: "100001"
```