Skip to main content
POST
/
ExternalSettlement
ExternalSettlement
curl --request POST \
  --url https://{domain}/api/ExternalSettlement \
  --header 'Content-Type: application/json' \
  --data '
{
  "NayaxTransactionId": 1234567890,
  "SparkTransactionId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "MachineAuTime": "20251212104530123",
  "SiteId": 2,
  "TerminalId": "0434334921100366",
  "TerminalIdType": 1,
  "Amount": 15.75,
  "EReceiptData": "<string>",
  "ProductInfo": [
    {
      "Value": 15.75,
      "Code": 0,
      "Quantity": 1
    }
  ]
}
'
{
  "SparkTransactionId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "Status": {
    "Verdict": "<string>",
    "ErrorCode": 123,
    "ErrorDescription": "<string>",
    "StatusMessage": "<string>"
  },
  "AuthCode": "A1B2C3",
  "MachineAuTime": "20251212104530123",
  "Amount": 15.75
}
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 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 ExternalSettlement)

​
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
Note: MachineAuTime retrieval for Marshall is currently a work-in-progress.
  • 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.
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.
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:
FieldTypeDescription
ValueDecimalThe price of a single unit of the product.

* 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)
CodeIntegerThe Product Code as defined in your Nayax Products Map.

* The value is taken as is (Decimal place of 0)
QuantityIntegerThe number of units of this product provided.

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

Body

Settlement request details for an external transaction.

​
NayaxTransactionId
integer<int64>

Nayax Internal Unique identifier for the transaction.

Example:

1234567890

​
SparkTransactionId
string | null

Unique identifier for this transaction, used by Spark.

Maximum string length: 36
Example:

"a1b2c3d4-e5f6-7890-1234-567890abcdef"

​
MachineAuTime
string<yyyyMMddHHmmssfff.> | null

The date time string of when the /Authorization took place, in local (machine) time.

Example:

"20251212104530123"

​
SiteId
integer<int16> | null

Optional. Echo value from Authorization Callback. Represents the Site ID.

Example:

2

​
TerminalId
string

Unique Identifier for the Nayax Terminal.

Example:

"0434334921100366"

​
TerminalIdType
enum<integer> | null

Indicates the type of TerminalId. 1 - Nayax HW serial, 2 - Nayax Machine ID

Available options:
1,
2
Example:

1

​
Amount
number<double>

The value to be provided to the Terminal for transaction initiation. Decimal (max 2 digits for cents)

Example:

15.75

​
EReceiptData
string | null

Optional. Transaction's 3rd party data for receipt generation.

​
ProductInfo
object[] | null

Array of products associated with the settlement.

Response

object | null

Success

Response details for an external settlement request.

​
SparkTransactionId
string | null

The Spark unique identifier for this transaction.

Example:

"a1b2c3d4-e5f6-7890-1234-567890abcdef"

​
Status
object

The status of the settlement request.

​
AuthCode
string | null

For Credit card implementation, when the transaction is approved, this is the External (usually Card issuer's) Authorization Code.

Example:

"A1B2C3"

​
MachineAuTime
string<yyyyMMddHHmmssfff> | null

The date time string of when the /Authorization or /Sale took place, in local (machine) time.

Example:

"20251212104530123"

​
Amount
number<double>

The value Settled by the card issuer during the Settlement phase.

Example:

15.75