跳转到主要内容
ExternalCancel
/ExternalCancel 方法由第三方服务器调用,用于取消已授权但尚未结算的交易。如果交互过程中或第三方服务器上发生故障,就需要取消交易。此操作对于释放消费者支付卡上已扣留的资金至关重要。 虽然 API 方法始终是 /ExternalCancel,但具体的财务术语取决于机器的流程类型:
  • 预授权(Pre-Authorization)流程:此方法称为**“取消”(Cancel)**。
  • 预选(Pre-Selection)流程:此方法称为**“作废”(Void)**。
请求必须指定所需的取消类型。

识别交易

要成功取消交易,您的请求必须包含三个必填标识符,且必须与原始交易数据完全一致。
  • NayaxTransactionID:授权期间生成的唯一 ID。
  • SiteID:机器所在位置的标识符。
  • MachineAuTime:确切的授权时间戳。此字段为可选,但建议提供。
    • 由于 Transfer Data 不向机器提供此信息,Marshall 机器目前无法提供 MachineAUTime(因此第三方服务器在发送 ExternalCancel 时也不会有此信息)。
如果缺少其中任何字段或字段不匹配,系统将返回“交易未找到”(Transaction not found)错误。
自动重试(AutoCancel):如果请求失败,Nayax 提供 AutoCancel 功能,即 Nayax 会在稍后自动重试取消操作。前提条件是该运营商必须已启用 AutoCancel 功能。

排查被拒绝的取消请求

如果取消请求被拒绝,响应将返回 ErrorCode 51:“外部取消失败”(External Cancel Failed)。
  • 强制使用:如果您知道不会提供任何产品或服务,必须立即发送 ExternalCancel。
  • 对消费者的影响:如果不取消,消费者的资金将保持被扣留状态,造成糟糕的用户体验,并可能引发纠纷。
  • 审计记录:建议包含 ReasonCode 和 ReasonText(例如“75 - Service not provided”),以记录交易被作废的原因。

请求体

取消外部支付交易的请求详情(例如,作废预授权)。

NayaxTransactionId
integer<int64>

被取消交易的 Nayax 内部唯一标识符。

示例:

987654321

SparkTransactionId
string | null

此交易的 Spark 唯一标识符。

示例:

"f8e7d6c5-b4a3-2109-fedc-ba9876543210"

SiteId
integer<int16> | null

可选。向 Nayax Engine 指示交易发起的站点。回显授权回调(Authorization Callback)中的值。

示例:

2

MachineAuTime
string<yyyyMMddHHmmssfff.> | null

/Authorization 或 /Sale 发生时的日期时间字符串,使用本地(机器)时间。

示例:

"20251212110000500"

TerminalId
string

Nayax 终端的唯一标识符。

Maximum string length: 255
示例:

"NX0087654321"

TerminalIdType
enum<integer> | null

指示 TerminalId 的类型。1 - Nayax HW serial,2 - Nayax Machine ID

可用选项:
1,
2
示例:

1

CancellationType
enum<integer>

指示所实施的取消流程。1 - 预授权取消(Pre-Authorization Cancel),2 - 预选作废(Pre-Selection Void)

可用选项:
1,
2
示例:

1

ReasonCode
string<int16> | null

条件必填。取消原因代码。请参见取消类型代码。

示例:

"01"

ReasonText
string | null

条件必填。取消原因的详细描述或文本。必须提供 ReasonCode 或 ReasonText 之一。如果两者都不提供,ExternalCancel 请求将失败。

示例:

"User requested cancellation"

CancelAmount
number<double> | null

始终必填。要取消的金额。不能高于已授权金额。

示例:

5

响应

object | null

成功

外部交易取消请求的响应详情。

SparkTransactionId
string | null

此交易的 Spark 唯一标识符。

示例:

"f8e7d6c5-b4a3-2109-fedc-ba9876543210"

Status
object

取消请求的状态。

AuthCode
string | null

对于信用卡实施,交易获批时,这是外部(通常为发卡行)授权码。

示例:

"D4E5F6"

MachineAuTime
string<yyyyMMddHHmmssfff> | null

/Authorization 或 /Sale 发生时的日期时间字符串,使用本地(机器)时间。

示例:

"20251212110000500"