取消支付

2024-08-26 01:55

POST /v1/payments/cancel

使用此接口实现在长时间未返回支付结果时取消支付。如果超出合同中规定的可取消期限，则无法取消。使用与支付接口中相同的 paymentId 或 paymentRequestId 来取消支付交易。

结构

报文由报文头和报文体组成。本文主要介绍报文体结构信息，有关报文头的结构信息，请参阅：

注意：将每个字段（除数组外）的数据类型设置为字符串。这意味字段值必须使用双引号（" "）括起来。例如：

如果字段的数据类型为整数属性，且其值为 20，设置为 "20"。
如果字段的数据类型为布尔属性，且其值为 true，设置为 "true"。

入参

paymentId String

在商家发起首次支付时，Antom 生成的识别该支付的原始支付 ID。该 ID 也是一个待取消支付请求的原始支付 ID。 paymentId 和 paymentRequestId 不能同时为null。paymentId 和 paymentRequestId 之间存在一一对应关系。

更多信息：

最大长度：64 字符

paymentRequestId String

商家生成的待取消支付请求的原始支付请求 ID。该 ID 用于识别某一次特定支付。paymentRequestId 和 paymentId 不能同时为null。如果同时提供了paymentRequestId 和 paymentId，则优先使用 paymentId。

更多信息：

最大长度：64 字符

出参

result Result object REQUIRED

指示此接口是否调用成功。如果此接口调用成功，支付将成功取消。

Show child parameters

paymentId String

Antom 为识别支付而分配的支付 ID。

注意：此字段在取消成功（result.resultStatus 的值为S）时返回。

更多信息：

最大长度：64 字符

paymentRequestId String

商户为识别支付请求而分配的支付请求 ID。

注意：当取消成功时（即 result.resultStatus 的值为S），会返回此字段。

更多信息：

最大长度：64 字符

cancelTime Datetime

支付取消过程的实际执行完成时间，即支付取消成功时的日期和时间。

注意：此字段在取消成功（result.resultStatus 的值为S）时返回。

更多信息：

值遵循 ISO 8601 标准格式。例如，“2019-11-27T12:01:01+08:00”。

API Explorer

示例代码沙箱运行

请求

URL

请求体

响应

Case

Success

响应体

结果处理逻辑

对于不同的请求结果，需要执行不同的操作。详细信息如下：

如果 result.resultStatus 的值为 S，取消操作成功。
如果 result.resultStatus 的值为F，取消操作失败。查看返回的错误代码并确定进一步的操作。
如果 result.resultStatus 的值为 U，取消结果未知。使用相同的请求参数重试取消请求。
如果没有返回响应，使用相同的请求参数重试取消请求。

结果码

结果码	值	结果码信息	行动建议
SUCCESS	S	成功	订单已成功取消。
ACCESS_DENIED	F	访问被拒绝。	请联系 Antom 技术支持以获取详细原因。
INVALID_API	F	调用的接口无效或未激活。	请联系 Antom 技术支持解决此问题。
CANCEL_WINDOW_EXCEED	F	取消日期超出支持取消的期限，该期限在合同中约定。	交易无法再取消。
KEY_NOT_FOUND	F	未找到 Antom 或商户的私钥或公钥。	检查私钥或公钥是否存在。如果不存在，请在 Antom 开发者中心上传私钥。
MERCHANT_BALANCE_NOT_ENOUGH	F	商户余额不足。	在商户有足够的余额后，再次调用接口。
NO_INTERFACE_DEF	F	接口未定义。	检查链接是否正确。请参考接口文档中的端点。
ORDER_NOT_EXIST	F	订单不存在。	检查 paymentId 是否正确。如果正确，请联系 Antom 技术支持以获取具体原因。
ORDER_STATUS_INVALID	F	由于订单状态无效，交易无法进一步处理。	检查交易的订单状态，或联系 Antom 技术支持以获取详细原因。
PARAM_ILLEGAL	F	缺少必需的参数，或者存在非法参数。例如，非数字输入，无效的日期，或者参数的长度和类型错误。	检查并验证当前接口所需的请求字段（包括头字段和正文字段）是否正确传递并有效。
PROCESS_FAIL	F	发生了常见的业务失败。	在获取 Antom 技术支持前请不要重试。
SYSTEM_ERROR	F	发生了系统错误。	在获取 Antom 技术支持前请不要重试。
REQUEST_TRAFFIC_EXCEED_LIMIT	U	请求流量超过了限制。	再次调用接口以解决问题。如果未解决，请联系 Antom 技术支持。
PAYMENT_METHOD_NOT_SUPPORTED	F	如果支付状态为成功，支付方式不支持取消或退款交易。	获取 Antom 技术支持前请勿重试。
UNKNOWN_EXCEPTION	U	由于未知原因，接口调用失败。	再次调用接口以解决问题。如果未解决，请联系 Antom 技术支持。
USER_NOT_EXIST	F	在支付方式端用户不存在。	请联系 Antom 技术支持以获取详细原因。
USER_STATUS_ABNORMAL	F	在支付方式端用户状态异常。	请联系 Antom 技术支持了解具体原因。