ExternalCancel
curl --request POST \
--url https://nayax-spark-dmz.nayax.com/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
}
'import requests
url = "https://nayax-spark-dmz.nayax.com/api/ExternalCancel"
payload = {
"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
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
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
})
};
fetch('https://nayax-spark-dmz.nayax.com/api/ExternalCancel', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://nayax-spark-dmz.nayax.com/api/ExternalCancel",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://nayax-spark-dmz.nayax.com/api/ExternalCancel"
payload := strings.NewReader("{\n \"NayaxTransactionId\": 987654321,\n \"SparkTransactionId\": \"f8e7d6c5-b4a3-2109-fedc-ba9876543210\",\n \"SiteId\": 2,\n \"MachineAuTime\": \"20251212110000500\",\n \"TerminalId\": \"NX0087654321\",\n \"TerminalIdType\": 1,\n \"CancellationType\": 1,\n \"ReasonCode\": \"01\",\n \"ReasonText\": \"User requested cancellation\",\n \"CancelAmount\": 5\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://nayax-spark-dmz.nayax.com/api/ExternalCancel")
.header("Content-Type", "application/json")
.body("{\n \"NayaxTransactionId\": 987654321,\n \"SparkTransactionId\": \"f8e7d6c5-b4a3-2109-fedc-ba9876543210\",\n \"SiteId\": 2,\n \"MachineAuTime\": \"20251212110000500\",\n \"TerminalId\": \"NX0087654321\",\n \"TerminalIdType\": 1,\n \"CancellationType\": 1,\n \"ReasonCode\": \"01\",\n \"ReasonText\": \"User requested cancellation\",\n \"CancelAmount\": 5\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://nayax-spark-dmz.nayax.com/api/ExternalCancel")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"NayaxTransactionId\": 987654321,\n \"SparkTransactionId\": \"f8e7d6c5-b4a3-2109-fedc-ba9876543210\",\n \"SiteId\": 2,\n \"MachineAuTime\": \"20251212110000500\",\n \"TerminalId\": \"NX0087654321\",\n \"TerminalIdType\": 1,\n \"CancellationType\": 1,\n \"ReasonCode\": \"01\",\n \"ReasonText\": \"User requested cancellation\",\n \"CancelAmount\": 5\n}"
response = http.request(request)
puts response.read_body{
"SparkTransactionId": "f8e7d6c5-b4a3-2109-fedc-ba9876543210",
"Status": {
"Verdict": "<string>",
"ErrorCode": 123,
"ErrorDescription": "<string>",
"StatusMessage": "<string>"
},
"AuthCode": "D4E5F6",
"MachineAuTime": "20251212110000500"
}Transactions
ExternalCancel
ExternalCancel
curl --request POST \
--url https://nayax-spark-dmz.nayax.com/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
}
'import requests
url = "https://nayax-spark-dmz.nayax.com/api/ExternalCancel"
payload = {
"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
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
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
})
};
fetch('https://nayax-spark-dmz.nayax.com/api/ExternalCancel', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://nayax-spark-dmz.nayax.com/api/ExternalCancel",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://nayax-spark-dmz.nayax.com/api/ExternalCancel"
payload := strings.NewReader("{\n \"NayaxTransactionId\": 987654321,\n \"SparkTransactionId\": \"f8e7d6c5-b4a3-2109-fedc-ba9876543210\",\n \"SiteId\": 2,\n \"MachineAuTime\": \"20251212110000500\",\n \"TerminalId\": \"NX0087654321\",\n \"TerminalIdType\": 1,\n \"CancellationType\": 1,\n \"ReasonCode\": \"01\",\n \"ReasonText\": \"User requested cancellation\",\n \"CancelAmount\": 5\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://nayax-spark-dmz.nayax.com/api/ExternalCancel")
.header("Content-Type", "application/json")
.body("{\n \"NayaxTransactionId\": 987654321,\n \"SparkTransactionId\": \"f8e7d6c5-b4a3-2109-fedc-ba9876543210\",\n \"SiteId\": 2,\n \"MachineAuTime\": \"20251212110000500\",\n \"TerminalId\": \"NX0087654321\",\n \"TerminalIdType\": 1,\n \"CancellationType\": 1,\n \"ReasonCode\": \"01\",\n \"ReasonText\": \"User requested cancellation\",\n \"CancelAmount\": 5\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://nayax-spark-dmz.nayax.com/api/ExternalCancel")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"NayaxTransactionId\": 987654321,\n \"SparkTransactionId\": \"f8e7d6c5-b4a3-2109-fedc-ba9876543210\",\n \"SiteId\": 2,\n \"MachineAuTime\": \"20251212110000500\",\n \"TerminalId\": \"NX0087654321\",\n \"TerminalIdType\": 1,\n \"CancellationType\": 1,\n \"ReasonCode\": \"01\",\n \"ReasonText\": \"User requested cancellation\",\n \"CancelAmount\": 5\n}"
response = http.request(request)
puts response.read_body{
"SparkTransactionId": "f8e7d6c5-b4a3-2109-fedc-ba9876543210",
"Status": {
"Verdict": "<string>",
"ErrorCode": 123,
"ErrorDescription": "<string>",
"StatusMessage": "<string>"
},
"AuthCode": "D4E5F6",
"MachineAuTime": "20251212110000500"
}/ExternalCancel 方法由第三方服务器调用,用于取消已授权但尚未结算的交易。如果交互过程中或第三方服务器上发生故障,就需要取消交易。此操作对于释放消费者支付卡上已扣留的资金至关重要。
虽然 API 方法始终是 /ExternalCancel,但具体的财务术语取决于机器的流程类型:
- 预授权(Pre-Authorization)流程:此方法称为**“取消”(Cancel)**。
- 预选(Pre-Selection)流程:此方法称为**“作废”(Void)**。
识别交易
要成功取消交易,您的请求必须包含三个必填标识符,且必须与原始交易数据完全一致。- NayaxTransactionID:授权期间生成的唯一 ID。
- SiteID:机器所在位置的标识符。
- MachineAuTime:确切的授权时间戳。此字段为可选,但建议提供。
- 由于 Transfer Data 不向机器提供此信息,Marshall 机器目前无法提供 MachineAUTime(因此第三方服务器在发送 ExternalCancel 时也不会有此信息)。
自动重试(AutoCancel):如果请求失败,Nayax 提供 AutoCancel 功能,即 Nayax 会在稍后自动重试取消操作。前提条件是该运营商必须已启用 AutoCancel 功能。
排查被拒绝的取消请求
如果取消请求被拒绝,响应将返回 ErrorCode 51:“外部取消失败”(External Cancel Failed)。- 强制使用:如果您知道不会提供任何产品或服务,必须立即发送
ExternalCancel。 - 对消费者的影响:如果不取消,消费者的资金将保持被扣留状态,造成糟糕的用户体验,并可能引发纠纷。
- 审计记录:建议包含
ReasonCode和ReasonText(例如“75 - Service not provided”),以记录交易被作废的原因。
请求体
application/jsontext/jsonapplication/*+json
取消外部支付交易的请求详情(例如,作废预授权)。
被取消交易的 Nayax 内部唯一标识符。
示例:
987654321
此交易的 Spark 唯一标识符。
示例:
"f8e7d6c5-b4a3-2109-fedc-ba9876543210"
可选。向 Nayax Engine 指示交易发起的站点。回显授权回调(Authorization Callback)中的值。
示例:
2
/Authorization 或 /Sale 发生时的日期时间字符串,使用本地(机器)时间。
示例:
"20251212110000500"
Nayax 终端的唯一标识符。
Maximum string length:
255示例:
"NX0087654321"
指示 TerminalId 的类型。1 - Nayax HW serial,2 - Nayax Machine ID
可用选项:
1, 2 示例:
1
指示所实施的取消流程。1 - 预授权取消(Pre-Authorization Cancel),2 - 预选作废(Pre-Selection Void)
可用选项:
1, 2 示例:
1
条件必填。取消原因的详细描述或文本。必须提供 ReasonCode 或 ReasonText 之一。如果两者都不提供,ExternalCancel 请求将失败。
示例:
"User requested cancellation"
始终必填。要取消的金额。不能高于已授权金额。
示例:
5
响应
object | null
成功
外部交易取消请求的响应详情。
此交易的 Spark 唯一标识符。
示例:
"f8e7d6c5-b4a3-2109-fedc-ba9876543210"
取消请求的状态。
Show child attributes
Show child attributes
对于信用卡实施,交易获批时,这是外部(通常为发卡行)授权码。
示例:
"D4E5F6"
/Authorization 或 /Sale 发生时的日期时间字符串,使用本地(机器)时间。
示例:
"20251212110000500"
此页面对您有帮助吗?