> ## 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

The `/ExternalCancel` method is used by the third-party server to cancel a transaction that has been authorized but not yet settled. Cancellation is necessary if a failure occurs during the interaction or on the third-party server. This process is vital for releasing any funds captured on the consumer's payment card.

While the API method is always `/ExternalCancel`, the financial terminology depends on the machine flow type:

* **Pre-Authorization Flow**: This method is called to as a **"Cancel"**.
* **Pre-Selection Flow**: This the method is referred a **"Void"**.

The request must specify the required cancellation type.

## Identifying the Transaction

To successfully cancel a transaction, your request must include the three required identifiers that exactly match the original transaction data.

* **NayaxTransactionID**: The unique ID generated during authorization.
* **SiteID**: The identifier for the machine's location.
* **MachineAuTime**: The exact authorization timestamp. Optional field but recommended
  * MachineAUTime is currently not available for Marshall machines due to Transfer Data not providing this information to the machine (hence the 3rd party servers would not have this information when trying to send the ExternalCancel)

If any of these fields are missing or mismatched, the system will return a "Transaction not found" error.

<Note>
  **Automatic Retries (AutoCancel):**

  In case the request fails, Nayax provides an **AutoCancel** feature, which means Nayax will automatically attempt to retry the cancellation later. The prerequisite is that the **AutoCancel** feature must be enabled for the specific operator.
</Note>

## Troubleshooting Declined Cancellations

If a cancellation request is declined, the response will return **ErrorCode 51**: "External Cancel Failed".

* **Mandatory Use**: You must send an `ExternalCancel` immediately if you know no product or service will be provided.
* **Consumer Impact**: If not canceled, consumer funds will remain captured, leading to a poor user experience and potential disputes.
* **Audit Trail**: It is recommended to include a `ReasonCode` and `ReasonText` (e.g., "75 - Service not provided") to document why the transaction was voided.


## OpenAPI

````yaml /openapi/spark.yaml post /ExternalCancel
openapi: 3.0.1
info:
  title: Nayax Spark API
  description: RemoteStart V2
  version: v2
servers:
  - url: https://{domain}/api
    variables:
      domain:
        default: nayax-spark-dmz.nayax.com
        description: >-
          Your Nayax-assigned domain (e.g., nayax-spark-dmz.nayax.com). Nayax
          provides a QA domain during sandbox onboarding and a production domain
          after certification.
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: Success
          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: >-
        Request details for canceling an external payment transaction (e.g.,
        voiding a pre-authorization).
      properties:
        NayaxTransactionId:
          type: integer
          format: int64
          description: >-
            Nayax Internal Unique identifier for the transaction being
            cancelled.
          example: 987654321
        SparkTransactionId:
          type: string
          nullable: true
          description: Spark Unique identifier for this transaction.
          example: f8e7d6c5-b4a3-2109-fedc-ba9876543210
        SiteId:
          type: integer
          format: int16
          nullable: true
          description: >-
            Optional. Indication for the Nayax Engine in which Site the
            transaction originated. Echo value from Authorization Callback.
          example: 2
        MachineAuTime:
          type: string
          nullable: true
          description: >-
            The date time string of when the `/Authorization` or `/Sale` took
            place, in local (machine) time.
          format: yyyyMMddHHmmssfff.
          example: '20251212110000500'
        TerminalId:
          type: string
          nullable: false
          description: Unique Identifier for the Nayax Terminal.
          maxLength: 255
          example: NX0087654321
        TerminalIdType:
          type: integer
          format: int32
          nullable: true
          description: >-
            Indicates the type of TerminalId. 1 - Nayax HW serial, 2 - Nayax
            Machine ID
          enum:
            - 1
            - 2
          example: 1
        CancellationType:
          type: integer
          format: int32
          description: >-
            Indicates which cancellation flow is implemented. 1 -
            Pre-Authorization Cancel, 2 - Pre-Selection Void
          enum:
            - 1
            - 2
          example: 1
        ReasonCode:
          type: string
          format: int16
          nullable: true
          description: Conditional. Cancel reason code.
          example: '01'
        ReasonText:
          type: string
          nullable: true
          description: >-
            Conditional. Detailed description or text of the cancel reason.
            Either ReasonCode or ReasonText must be provided. ExternalCancel
            request without both will cause failure.
          example: User requested cancellation
        CancelAmount:
          type: number
          format: double
          nullable: true
          description: >-
            Always mandatory. Amount to be cancelled. Can’t be higher than the
            authorized amount.
          example: 5
    ExternalCancelResponse:
      type: object
      nullable: true
      description: Response details for an external transaction cancellation request.
      properties:
        SparkTransactionId:
          type: string
          nullable: true
          description: The Spark unique identifier for this transaction.
          example: f8e7d6c5-b4a3-2109-fedc-ba9876543210
        Status:
          $ref: '#/components/schemas/Status'
          description: The status of the cancellation request.
        AuthCode:
          type: string
          nullable: true
          description: >-
            For Credit card implementation, when the transaction is approved,
            this is the External (usually Card issuer's) Authorization Code.
          example: D4E5F6
        MachineAuTime:
          type: string
          nullable: true
          description: >
            The date time string of when the `/Authorization` or `/Sale` took
            place, in local (machine) time. 
          format: yyyyMMddHHmmssfff
          example: '20251212110000500'
    Status:
      type: object
      nullable: false
      description: Transaction Status Details
      properties:
        Verdict:
          type: string
          nullable: false
          description: Status of the request (Approved / Declined)
        ErrorCode:
          type: integer
          format: int16
          nullable: true
          description: |
            - Conditional
            - Reason for declined request
        ErrorDescription:
          type: string
          nullable: true
          description: |
            - Conditional
            - Length: 255
            - Error description
        StatusMessage:
          type: string
          nullable: true
          description: |
            - Optional
            - Length: 255
            - Transaction status message as free text field

````