> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clinkbill.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 回报支付结果

> Reports the outcome observed on the merchant page after using a credential. Requires `portal:write`.

Clink 用该回报闭环订单和指令 usage。回报只记录商户页面显示的结果，不会执行或验证支付。

> [!NOTE]
>
> 该接口是支付结果确认入口。它是确认或回报交易结果的唯一入口，Clink 不提供独立的“确认交易”接口。请在下方说明的 24 小时回报窗口内，通过该接口回报最终结果（包括在 `UNKNOWN` 回报之后补报最终结果）。

| Outcome | 含义 |
| - | - |
| `SUCCEEDED` | 商户明确确认支付成功。 |
| `FAILED` | 卡已提交后，商户明确显示失败。 |
| `NOT_SUBMITTED` | 卡从未提交。 |
| `UNKNOWN` | 卡已提交，但无法确定结果。Clink 不发布结果，返回 `PENDING` 和 `report_deadline`；请在该时间前回报最终结果。 |

## 回报规则

* Clink 在 `report_deadline` 之前接受最终结果，即凭证签发后 24 小时。超过窗口的回报返回 `410`，`code` 为 `71211018`（`report_window_expired`）。
* usage 不存在或不属于 token 对应用户时返回 `404`。
* Clink 按两类比较最终结果：`SUCCEEDED` 属于成功类；`FAILED` 和 `NOT_SUBMITTED` 都属于失败类。同一类内重复回报会以 HTTP `200` 返回已记录的结果；例如已记录 `NOT_SUBMITTED` 后再回报 `FAILED` 不冲突。已记录终态后回报另一类结果返回 `409`，`code` 为 `71211017`（`result_already_reported`）。
* `SUCCEEDED`、`FAILED` 和 `NOT_SUBMITTED` 会闭环 usage，并进入 Clink 既有的支付结果处理链路。
* `UNKNOWN` 不记录终态、不发布结果消息，返回 `PENDING`；请在 `report_deadline` 之前回报最终结果。
* `paid_amount` 和 `currency_code` 必须成对出现。`paid_amount` 与授权金额不一致时，Clink 记录 `paid_amount_mismatch: true`，不覆盖授权金额。


## OpenAPI

````yaml POST /agent/platform/credential-results
openapi: 3.1.0
info:
  title: Clink Agent Portal API
  description: >-
    Agent Portal APIs let an Agent platform read and manage one user's Clink
    account with a portal user token: payment methods, orders, refunds, purchase
    instructions, payment credentials, payment results, and settings.
  version: 1.0.0
servers:
  - url: https://uat-api.clinkbill.com
    description: Sandbox
security:
  - PortalToken: []
paths:
  /agent/platform/credential-results:
    post:
      summary: Report credential result
      description: >-
        Reports the outcome observed on the merchant page after using a
        credential. Requires `portal:write`.
      operationId: reportCredentialResult
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportResultRequest'
            example:
              client_reference_id: platform-ref-001
              outcome: SUCCEEDED
              paid_amount: '12.50'
              currency_code: USD
              failure_reason: null
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    format: int32
                    description: '`200` on success.'
                    example: 200
                  msg:
                    type: string
                    description: Result message.
                    example: Success
                  data:
                    $ref: '#/components/schemas/ReportResultResponse'
              example:
                code: 200
                msg: Success
                data:
                  status: SUCCEEDED
                  report_deadline: '2026-11-10T09:00:00Z'
                  paid_amount_mismatch: false
        '400':
          description: Invalid request body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, expired, or invalid portal token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: >-
            Wrong token audience, missing `portal:write` scope, or a platform
            client token used instead of a portal token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The usage does not exist or does not belong to the token's customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: >-
            A terminal result of the other class was already reported
            (`result_already_reported`, `code` `71211017`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '410':
          description: >-
            The reporting window has expired (`report_window_expired`, `code`
            `71211018`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ReportResultRequest:
      type: object
      required:
        - client_reference_id
        - outcome
      properties:
        client_reference_id:
          type: string
          description: >-
            Value used when requesting the credential. Clink finds the usage by
            this value for the token's customer.
          example: platform-ref-001
        outcome:
          type: string
          description: >-
            `SUCCEEDED`: the merchant explicitly confirmed that the payment
            succeeded. `FAILED`: the merchant explicitly showed failure after
            the card was submitted. `NOT_SUBMITTED`: the card was never
            submitted. `UNKNOWN`: the card was submitted, but the result cannot
            be determined; Clink returns `PENDING` with `report_deadline`.
          enum:
            - SUCCEEDED
            - FAILED
            - NOT_SUBMITTED
            - UNKNOWN
          example: SUCCEEDED
        paid_amount:
          type: string
          description: >-
            Amount shown by the merchant, decimal string in major currency
            units. Must be paired with `currency_code`.
          example: '12.50'
        currency_code:
          type: string
          description: Three-letter currency code. Must be paired with `paid_amount`.
          example: USD
        failure_reason:
          type: string
          description: >-
            Reason for a failed or unsubmitted payment. Accepted only with
            `FAILED` or `NOT_SUBMITTED`.
          enum:
            - CARD_DECLINED
            - AUTHENTICATION_REQUIRED
            - AMOUNT_CHANGED
            - CREDENTIAL_EXPIRED
            - CREDENTIAL_LOST
            - MERCHANT_ERROR
            - BUYER_CANCELLED
            - OTHER
    ReportResultResponse:
      type: object
      properties:
        status:
          type: string
          description: Recorded outcome. For an `UNKNOWN` report it is `PENDING`.
          example: SUCCEEDED
        report_deadline:
          type: string
          description: Latest time a terminal result can be reported.
          format: date-time
          example: '2026-11-10T09:00:00Z'
        paid_amount_mismatch:
          type: boolean
          description: >-
            `true` when `paid_amount` differs from the authorized amount. The
            report does not overwrite the authorized amount.
          example: false
    ErrorResponse:
      type: object
      description: Business errors use the standard envelope without `data`.
      properties:
        code:
          type: integer
          description: >-
            Numeric business error code. Judge an error by the HTTP status
            together with `code`, not by a string error code.
        msg:
          type: string
          description: Human-readable description.
  securitySchemes:
    PortalToken:
      type: http
      scheme: bearer
      description: >-
        Portal user token from `POST /agent/cwallet/platform/portal/tokens`.
        Reads require `portal:read`; writes require `portal:write`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.