接收和获取争议 | Welcome to Afterpay Documentation

在本节中，您可以了解：

当客户开启争议时，Afterpay 将调用带有 webhook_event_type = created 的 webhook。商户可以使用下面的获取争议端点获取争议的详细信息。

接收争议

获取争议 - 端点

GET https://{afterpay_global_url}/v2/disputes/{dispute_id}

连接超时

超时类型	时间（秒）
`OPEN`	10
`Read`	20

请求头

头部	类型	示例
`User-Agent`	String	`MyAfterpayModule/1.0.0 (E-Commerce Platform Name/1.0.0; PHP/7.0.0; Merchant/60032000) https://merchant.example.com`

头部	类型	默认值
`Accept`	String	application/json

请求参数

字段名称	数据类型	描述
`dispute_id`	String	（必需）争议标识符

响应

字段名称	数据类型	描述
`dispute`	DisputeObject	更新的争议对象

争议对象

字段名称	数据类型	描述
`id`	String	争议标识符
`order`	String	争议所针对的订单令牌
`amount`	String	争议金额（示例：40.13）
`currency`	String	争议货币（ISO-4217 标准，示例：AUD）
`reason`	String	争议原因。请参见下面的争议原因部分建议。
`status`	String	争议的当前状态。值取决于争议状态机的建模方式。请参见下面的争议状态部分建议。
`open`	Boolean	如果尚未对争议做出最终决定，则为 `True`。
`responseDueBy`	时间戳	商户必须对此争议作出响应的截止日期。（以秒为单位的纪元时间戳，时区：UTC +0:00）
`createdAt`	时间戳	表示争议创建时间的时间戳。（以秒为单位的纪元时间戳，时区：UTC +0:00）
`openingNote`	String	客户描述开启争议原因或投诉原因的文本。虽然争议类别代码有助于告知商户应该提供什么，但它不提供客户投诉背后的原因。在某些情况下，这可以帮助商户直接与客户解决争议。
`openingNoteAttachments`	FileId	补充 `openingNote` 的附件。如果客户在描述争议原因时提供了照片或截图
`updatedAt`	时间戳 (可选)	争议更新的时间戳。（以秒为单位的纪元时间戳，时区：UTC +0:00）
`closingReason`	String	表示如何达成争议最终决定的原因。建议的可能值列在下面的结束原因中。
`closingNote`	String (可选)	详细描述如何达成争议最终决定的文本。这补充了 `closingReason`。
`merchantOrderId`	String	商户端的交易标识符。
`transactionDate`	时间戳	客户创建订单的时间戳。（以秒为单位的纪元时间戳，时区：UTC +0:00）
`settlementAmount`	String	用于审计的结算金额。
`meta`	MetaObject (可选)	供商户匹配支付的额外信息。

Meta 对象

字段名称	数据类型	描述
`transactionAmount`	String	订单的交易金额。
`network`	String (可选)	客户使用的支付网络。（通常是 Visa 或 MasterCard）
`networkReferenceId`	String(可选)	支付的标识符。（对于店内支付，此字段存在）
`orderType`	String	订单类型，应为 `ONLINE` 或 `INSTORE`。

争议对象示例

字段名称	数据类型	示例
`id`	String	dp_N64jYg4RC4ZBUsXjLzE3W5
`order`	String	123456789
`amount`	String	48.46
`currency`	String	AUD
`reason`	String	fraudulent
`status`	String	won
`open`	Boolean	false
`responseDueBy`	时间戳	1691884800
`createdAt`	时间戳	1691884800
`openingNote`	String	Customer has no knowledge of the Payment.
`openingNoteAttachments`	FileId	[“fi_48vmw3sXdVqvtJGXbgKbAZ”]
`updatedAt`	时间戳 (可选)	1691884800
`closingReason`	String	merchant_accepted
`closingNote`	String (可选)	Merchant accepted the dispute.
`merchantOrderId`	String	merchantorderid12345
`transactionDate`	时间戳	1691884800
`settlementAmount`	String	48.46
`meta`	MetaObject (可选)	`"transactionAmount": "48.46"`, `"orderType":"ONLINE"`

争议状态

Afterpay 支持以下争议状态：

我们在第一个版本中不支持 partially_won 状态，但计划在未来支持它。

状态	描述
`needs_response`	Afterpay 已创建争议并通知商户，但商户尚未采取行动。
`under_review`	商户已向 Afterpay 提交证据，目前正在审查中。
`partially_won`	如果最终争议解决金额小于原始争议金额，则表示商户部分赢得争议。注意，这是一个终态。
`won`	提交的证据被 Afterpay 接受，商户赢得争议。注意，这是一个终态。
`lost`	提交的证据被 Afterpay 拒绝，商户失去争议。注意，这是一个终态。
`merchant_refunded`	商户已发起退款。如果退款金额等于或大于争议金额，则这是一个终态。
`merchant_voided`	商户已取消全部或部分订单。如果取消金额等于或大于争议金额，则这是一个终态。

争议窗口

Afterpay 将根据争议窗口时间框架更新争议状态并触发争议通知。以下是行使和辩护拒付的时间框架（以日历天为单位）：

摘要	描述
争议开启窗口	可以开启争议的最大时间窗口（从交易日期起），超过此时间客户将无法发起争议。	120 天
商户证据提交窗口	从商户收到争议通知到最终提交证据的允许时间。	13 天
Afterpay 决定窗口	从提交证据时刻到 Afterpay 做出最终决定的允许时间。	30 天

争议原因

当触发争议时，总会有一个争议原因。以下是争议 API 当前将响应和支持的争议原因：

Afterpay 的争议原因目前仅限于 product_not_received，我们计划在未来更新这一点。Cash App Pay 的争议系统已完全实施，包含所有原因，包括卡网络拒付。

商户端争议原因	活动	描述
`product_not_received`	Afterpay / Cash App Pay	客户声称他们没有收到购买的产品或服务。
`product_unacceptable`	Afterpay (Q4 发布) / Cash App pay	收到了产品或服务，但有缺陷、损坏或与描述不符。
`credit_not_processed`	Afterpay (Q4 发布) / Cash App pay	客户声称已退回购买的产品或交易已取消，但商户尚未提供退款或退款。
`order_canceled`	Cash App pay	商品/服务已取消。
`duplicate`	Cash App pay	客户声称他们被多次收取相同产品或服务的费用。
`incorrect_amount`	Cash App pay	支付金额与约定金额不符。
`paid_by_other_means`	Cash App pay	客户通过其他支付方式支付。
`fraudulent`	Cash App pay	客户声称他们没有授权支付。
`fraudulent_merchant`	Cash App pay	客户对支付没有认知，且由于共谋、欺诈监控程序阈值或任何其他原因，责任已转移给商户。

结束原因

向商户显示表明如何达成争议最终决定的结束原因。以下是结束原因及其描述：

商户端结束原因	描述
`merchant_accepted`	商户接受了争议。
`evidence_accepted`	商户提交的证据被接受，争议以商户胜诉结束。
`evidence_rejected`	商户提交了证据但被拒绝，争议以客户胜诉结束。
`deadline_expired`	商户未能为争议提交证据，提交窗口超时。争议以客户胜诉结束。
`customer_cancelled`	客户撤回了争议，因此以商户胜诉结束。

获取争议

列出争议 - 端点

根据特定条件列出某个日期范围内的争议。如果您无法使用 webhook 方法，此端点可用于调试或从 Afterpay 同步争议。

GET https://{afterpay_global_url}/v2/disputes

连接超时

超时类型	时间（秒）
`OPEN`	10
`Read`	20

请求头

头部	类型	示例
`User-Agent`	String	`MyAfterpayModule/1.0.0 (E-Commerce Platform Name/1.0.0; PHP/7.0.0; Merchant/60032000) https://merchant.example.com`

头部	类型	默认值
`Accept`	String	application/json

请求参数

字段名称	数据类型	描述
`order`	Integer	可用于筛选列表的支付或订单令牌。
`merchant`	String	可用于筛选列表的商户令牌。
`status`	String	可用于筛选列表的争议状态。
`openedAfter`	时间戳	筛选在此时间戳当天或之后创建的争议（包含）。
`openedBefore`	时间戳	筛选在此时间戳当天或之前创建的争议（包含）。
`offset`	Integer	搜索结果的偏移量。示例：Offset = 0，limit = 10 意味着我们将显示前十个争议。Offset = 10，limit = 10 意味着我们将显示搜索结果中编号为 10-20 的争议。
`limit`	Integer	您希望从此请求返回的最大记录数。

响应

字段名称	数据类型	描述
`data`	Array (DisputeObject)	符合请求中筛选条件的争议对象数组。
`offset`	Integer	搜索结果的偏移量。示例：Offset = 0，limit = 10 意味着我们将显示前十个争议。Offset = 10，limit = 10 意味着我们将显示搜索结果中编号为 10-20 的争议。
`limit`	Integer	您希望从此请求返回的最大记录数。
`total`	Integer	搜索条件中的总争议记录数。

响应示例

字段名称	数据类型	示例
`data`	Array (DisputeObject)	见下面的数据示例代码
`offset`	Integer	0
`limit`	Integer	1
`total`	Integer	1

数据示例代码

1 [
2   {
3     "id": "dp_N64jYg4RC4ZBUsXjLzE3W5",
4     "order": "12312312312",
5     "amount": "48.46",
6     "currency": "AUD",
7     "status": "won",
8     "reason": "fraudulent",
9     "open": false,
10     "responseDueBy": -1,
11     "openingNote": "Cash dispute: Customer has no knowledge of the Payment.",
12     "openingNoteAttachments": [],
13     "merchantOrderId": "12312312312",
14     "transactionDate": 1690836227,
15     "createdAt": 1691884800,
16     "updatedAt": 1692067909,
17     "meta": {
18               "transactionAmount": "48.46",
19               "orderType": "ONLINE"
20             }
21   }
22 ]