Skip to main content
POST
/
ExternalCancel
ExternalCancel
curl --request POST \
  --url https://{domain}/api/ExternalCancel \
  --header 'Content-Type: application/json' \
  --data '
{
  "NayaxTransactionId": 987654321,
  "SparkTransactionId": "f8e7d6c5-b4a3-2109-fedc-ba9876543210",
  "SiteId": 2,
  "MachineAuTime": "20251212110000500",
  "TerminalId": "NX0087654321",
  "TerminalIdType": 1,
  "CancellationType": 1,
  "ReasonCode": "01",
  "ReasonText": "User requested cancellation",
  "CancelAmount": 5
}
'
{
  "SparkTransactionId": "f8e7d6c5-b4a3-2109-fedc-ba9876543210",
  "Status": {
    "Verdict": "<string>",
    "ErrorCode": 123,
    "ErrorDescription": "<string>",
    "StatusMessage": "<string>"
  },
  "AuthCode": "D4E5F6",
  "MachineAuTime": "20251212110000500"
}
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.
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.

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

Body

Request details for canceling an external payment transaction (e.g., voiding a pre-authorization).

​
NayaxTransactionId
integer<int64>

Nayax Internal Unique identifier for the transaction being cancelled.

Example:

987654321

​
SparkTransactionId
string | null

Spark Unique identifier for this transaction.

Example:

"f8e7d6c5-b4a3-2109-fedc-ba9876543210"

​
SiteId
integer<int16> | null

Optional. Indication for the Nayax Engine in which Site the transaction originated. Echo value from Authorization Callback.

Example:

2

​
MachineAuTime
string<yyyyMMddHHmmssfff.> | null

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

Example:

"20251212110000500"

​
TerminalId
string

Unique Identifier for the Nayax Terminal.

Maximum string length: 255
Example:

"NX0087654321"

​
TerminalIdType
enum<integer> | null

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

Available options:
1,
2
Example:

1

​
CancellationType
enum<integer>

Indicates which cancellation flow is implemented. 1 - Pre-Authorization Cancel, 2 - Pre-Selection Void

Available options:
1,
2
Example:

1

​
ReasonCode
string<int16> | null

Conditional. Cancel reason code.

Example:

"01"

​
ReasonText
string | null

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
number<double> | null

Always mandatory. Amount to be cancelled. Can’t be higher than the authorized amount.

Example:

5

Response

object | null

Success

Response details for an external transaction cancellation request.

​
SparkTransactionId
string | null

The Spark unique identifier for this transaction.

Example:

"f8e7d6c5-b4a3-2109-fedc-ba9876543210"

​
Status
object

The status of the cancellation request.

​
AuthCode
string | null

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

Example:

"D4E5F6"

​
MachineAuTime
string<yyyyMMddHHmmssfff> | null

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

Example:

"20251212110000500"