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

# ExternalSettlement

The `/ExternalSettlement` method is called by the 3rd-party server to finalize a transaction after the payment provider has authorized the initial amount and the service or products have been provided to the consumer. This request must contain the final amount to be charged.

To successfully settle a transaction, you must provide three mandatory identifiers that match the original authorization data exactly:

* **NayaxTransactionID**: The unique identifier for the transaction in the Nayax system.
* **SiteID**: The ID of the site where the machine is located.
* **MachineAUTime**: The authorization timestamp from the terminal. Optional field but recommended.
  * MachineAUTime is not available for Marshall machines. However, as this field is optional, you can still use ExternalSettlement without it.

## Where to Find this Information

Depending on your hardware, these identifiers are retrieved through different channels:

* **OTI Devices**: Information is sent via the **CommerceAPI**.

* **Marshall Devices**: Information is sent via **Transfer Data**

* **Alternative**: All integrators can retrieve this data via **Amazon SQS**.

## Adding Digital Receipts (`EReceiptData`)

If you use the Nayax eReceipt platform, you can use the `EReceiptData` field to add custom information to the digital receipt that isn't stored in the Nayax Backoffice.

<Danger>
  Any information shared in this field will be visible to the consumer on their receipt. Avoid sharing sensitive data that is not relevant to the transaction.
</Danger>

The data must be sent as a JSON string containing:

* **Section Naming**: To display fields without a section header, use a blank space for the section name: `{" ":[...]}`.
* **Order**: Fields appear on the receipt in the exact order they are listed in the string.
* **Characters**: Use escape characters (e.g., `\"`) for internal quotes within the JSON string.

## Reporting Products (`ProductInfo`)

For operators who manage a **Products Map** in Nayax Core, the `ProductInfo` object allows you to report exactly which items were sold.

This is an array of objects where each item requires:

| Field        | Type    | Description                                                                                                                                                                                                                                        |
| ------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Value**    | Decimal | The price of a single unit of the product.<br /><br />\*   The value is taken as is (Decimal place of 0), meaning if you send value of 6.50 the value that the consumer would be charged for is 6.50, and if you send 65 the value would be 65.00) |
| **Code**     | Integer | The Product Code as defined in your Nayax Products Map.<br /><br />\*   The value is taken as is (Decimal place of 0)                                                                                                                              |
| **Quantity** | Integer | The number of units of this product provided.<br /><br />\*   The value is taken as is (Decimal place of 0)                                                                                                                                        |

**Example Format**: `[{"Value": 6.50, "Code": 12, "Quantity": 3}]`

## Troubleshooting Declined Settlements

If a settlement request is declined, the response will include an **ErrorCode 50**: "External Settlement Failed".

Common reasons for failure include:

* **Missing Identifiers**: Mandatory fields like `SiteId` were missing from the request.
* **Data Mismatch**: The IDs provided do not match the original authorization record.
* **Time Limit**: The request was sent more than 48 hours after the transaction started.


## OpenAPI

````yaml /openapi/spark.yaml post /ExternalSettlement
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:
  /ExternalSettlement:
    post:
      tags:
        - Transactions
      summary: ExternalSettlement
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalSettlementRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/ExternalSettlementRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/ExternalSettlementRequest'
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ExternalSettlementResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalSettlementResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/ExternalSettlementResponse'
components:
  schemas:
    ExternalSettlementRequest:
      type: object
      nullable: true
      description: Settlement request details for an external transaction.
      properties:
        NayaxTransactionId:
          type: integer
          format: int64
          description: Nayax Internal Unique identifier for the transaction.
          example: 1234567890
        SparkTransactionId:
          type: string
          nullable: true
          description: Unique identifier for this transaction, used by Spark.
          maxLength: 36
          example: a1b2c3d4-e5f6-7890-1234-567890abcdef
        MachineAuTime:
          type: string
          nullable: true
          description: >
            The date time string of when the `/Authorization` took place, in
            local (machine) time. 
          format: yyyyMMddHHmmssfff.
          example: '20251212104530123'
        SiteId:
          type: integer
          format: int16
          nullable: true
          description: >-
            Optional. Echo value from Authorization Callback. Represents the
            Site ID.
          example: 2
        TerminalId:
          type: string
          nullable: false
          description: Unique Identifier for the Nayax Terminal.
          example: '0434334921100366'
        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
        Amount:
          type: number
          format: double
          description: >-
            The value to be provided to the Terminal for transaction initiation.
            Decimal (max 2 digits for cents)
          example: 15.75
        EReceiptData:
          type: string
          nullable: true
          description: Optional. Transaction's 3rd party data for receipt generation.
        ProductInfo:
          type: array
          nullable: true
          description: Array of products associated with the settlement.
          items:
            $ref: '#/components/schemas/ProductInfo'
    ExternalSettlementResponse:
      type: object
      nullable: true
      description: Response details for an external settlement request.
      properties:
        SparkTransactionId:
          type: string
          nullable: true
          description: The Spark unique identifier for this transaction.
          example: a1b2c3d4-e5f6-7890-1234-567890abcdef
        Status:
          $ref: '#/components/schemas/Status'
          description: The status of the settlement 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: A1B2C3
        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: '20251212104530123'
        Amount:
          type: number
          format: double
          description: The value Settled by the card issuer during the Settlement phase.
          example: 15.75
    ProductInfo:
      type: object
      description: Information about a single product in the transaction.
      properties:
        Value:
          type: number
          format: decimal
          example: 15.75
          nullable: false
          description: Mandatory. The monetary amount of the product.
        Code:
          type: integer
          format: int64
          example: 0
          nullable: true
          description: Represents the product code in the product's map.
        Quantity:
          type: integer
          format: int64
          example: 1
          nullable: true
          description: Quantity of the product purchased.
    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

````