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

# ExternalCancel

`/ExternalCancel` 方法由第三方服务器调用，用于取消已授权但尚未结算的交易。如果交互过程中或第三方服务器上发生故障，就需要取消交易。此操作对于释放消费者支付卡上已扣留的资金至关重要。

虽然 API 方法始终是 `/ExternalCancel`，但具体的财务术语取决于机器的流程类型：

* **预授权（Pre-Authorization）流程**：此方法称为\*\*“取消”（Cancel）\*\*。
* **预选（Pre-Selection）流程**：此方法称为\*\*“作废”（Void）\*\*。

请求必须指定所需的取消类型。

## 识别交易

要成功取消交易，您的请求必须包含三个必填标识符，且必须与原始交易数据完全一致。

* **NayaxTransactionID**：授权期间生成的唯一 ID。
* **SiteID**：机器所在位置的标识符。
* **MachineAuTime**：确切的授权时间戳。此字段为可选，但建议提供。
  * 由于 Transfer Data 不向机器提供此信息，Marshall 机器目前无法提供 MachineAUTime（因此第三方服务器在发送 ExternalCancel 时也不会有此信息）。

如果缺少其中任何字段或字段不匹配，系统将返回“交易未找到”（Transaction not found）错误。

> [!NOTE]
>
> **自动重试（AutoCancel）：**
>
> 如果请求失败，Nayax 提供 **AutoCancel** 功能，即 Nayax 会在稍后自动重试取消操作。前提条件是该运营商必须已启用 **AutoCancel** 功能。

## 排查被拒绝的取消请求

如果取消请求被拒绝，响应将返回 **ErrorCode 51**：“外部取消失败”（External Cancel Failed）。

* **强制使用**：如果您知道不会提供任何产品或服务，必须立即发送 `ExternalCancel`。
* **对消费者的影响**：如果不取消，消费者的资金将保持被扣留状态，造成糟糕的用户体验，并可能引发纠纷。
* **审计记录**：建议包含 `ReasonCode` 和 `ReasonText`（例如“75 - Service not provided”），以记录交易被作废的原因。


## OpenAPI

````yaml /openapi/zh/spark.yaml post /ExternalCancel
openapi: 3.0.1
info:
  title: Nayax Spark API
  description: RemoteStart V2
  version: v2
servers:
  - url: https://nayax-spark-dmz.nayax.com/api
    description: The same host serves the integration and production environments.
security: []
tags:
  - name: Transactions
paths:
  /ExternalCancel:
    post:
      tags:
        - Transactions
      summary: ExternalCancel
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalCancelRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/ExternalCancelRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/ExternalCancelRequest'
      responses:
        '200':
          description: 成功
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ExternalCancelResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalCancelResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/ExternalCancelResponse'
components:
  schemas:
    ExternalCancelRequest:
      type: object
      nullable: true
      description: 取消外部支付交易的请求详情（例如，作废预授权）。
      properties:
        NayaxTransactionId:
          type: integer
          format: int64
          description: 被取消交易的 Nayax 内部唯一标识符。
          example: 987654321
        SparkTransactionId:
          type: string
          nullable: true
          description: 此交易的 Spark 唯一标识符。
          example: f8e7d6c5-b4a3-2109-fedc-ba9876543210
        SiteId:
          type: integer
          format: int16
          nullable: true
          description: 可选。向 Nayax Engine 指示交易发起的站点。回显授权回调（Authorization Callback）中的值。
          example: 2
        MachineAuTime:
          type: string
          nullable: true
          description: '`/Authorization` 或 `/Sale` 发生时的日期时间字符串，使用本地（机器）时间。'
          format: yyyyMMddHHmmssfff.
          example: '20251212110000500'
        TerminalId:
          type: string
          nullable: false
          description: Nayax 终端的唯一标识符。
          maxLength: 255
          example: NX0087654321
        TerminalIdType:
          type: integer
          format: int32
          nullable: true
          description: 指示 TerminalId 的类型。1 - Nayax HW serial，2 - Nayax Machine ID
          enum:
            - 1
            - 2
          example: 1
        CancellationType:
          type: integer
          format: int32
          description: >-
            指示所实施的取消流程。1 - 预授权取消（Pre-Authorization Cancel），2 -
            预选作废（Pre-Selection Void）
          enum:
            - 1
            - 2
          example: 1
        ReasonCode:
          type: string
          format: int16
          nullable: true
          description: 条件必填。取消原因代码。请参见[取消类型代码](/docs/zh/cortina/cancel-types)。
          example: '01'
        ReasonText:
          type: string
          nullable: true
          description: >-
            条件必填。取消原因的详细描述或文本。必须提供 ReasonCode 或 ReasonText
            之一。如果两者都不提供，ExternalCancel 请求将失败。
          example: User requested cancellation
        CancelAmount:
          type: number
          format: double
          nullable: true
          description: 始终必填。要取消的金额。不能高于已授权金额。
          example: 5
    ExternalCancelResponse:
      type: object
      nullable: true
      description: 外部交易取消请求的响应详情。
      properties:
        SparkTransactionId:
          type: string
          nullable: true
          description: 此交易的 Spark 唯一标识符。
          example: f8e7d6c5-b4a3-2109-fedc-ba9876543210
        Status:
          $ref: '#/components/schemas/Status'
          description: 取消请求的状态。
        AuthCode:
          type: string
          nullable: true
          description: 对于信用卡实施，交易获批时，这是外部（通常为发卡行）授权码。
          example: D4E5F6
        MachineAuTime:
          type: string
          nullable: true
          description: '`/Authorization` 或 `/Sale` 发生时的日期时间字符串，使用本地（机器）时间。'
          format: yyyyMMddHHmmssfff
          example: '20251212110000500'
    Status:
      type: object
      nullable: false
      description: 交易状态详情
      properties:
        Verdict:
          type: string
          nullable: false
          description: 请求的状态（Approved / Declined）
        ErrorCode:
          type: integer
          format: int16
          nullable: true
          description: |
            - 条件必填
            - 请求被拒绝的原因
        ErrorDescription:
          type: string
          nullable: true
          description: |
            - 条件必填
            - 长度：255
            - 错误描述
        StatusMessage:
          type: string
          nullable: true
          description: |
            - 可选
            - 长度：255
            - 交易状态消息，自由文本字段

````

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