- HTTP 请求
- 请求正文
- 响应正文
- RequestHeader
- 时间戳
- 版本
- PaymentLookupCriteria
- ArnCriteria
- GoogleTransactionReferenceNumberCriteria
- CaptureRequestCriteria
- RequestOriginator
- GetDisputeInquiryReportResponse
- ResponseHeader
- GetDisputeInquiryReportResult
- SuccessDetails
- PurchaseReport
- CustomerAccount
- 订单
- 金额
- 地址
- 单品
- 税费
- 付款
- 退款
- PaymentCardDetails
- AuthResult
- 空
- ErrorResponse
- ErrorResponseResult
- InvalidApiVersion
- InvalidPayloadSignature
- InvalidPayloadEncryption
- RequestTimestampOutOfRange
- InvalidIdentifier
- IdempotencyViolation
- InvalidFieldValueInvalidFieldValue
- MissingRequiredField
- PreconditionViolation
- UserActionInProgress
- InvalidDecryptedRequest
- 已禁止
获取一份报告,其中提供相关信息,帮助用户就潜在的付款争议与客户支持展开对话。
如果此方法未返回 HTTP 200,对此查询的响应可能为空。
如果端点在处理请求时遇到错误,来自此端点的响应将是
类型。ErrorResponse
如果此方法未返回 HTTP 200,对此查询的响应可能为空。如果可以使用包含明确说明的
来帮助攻击者了解其他集成商的付款集成商帐号标识符,则响应正文为空。在这些情况下,无论是签名密钥不匹配,未找到付款集成商标识符,或者加密密钥未知,此方法将返回正文为空的 HTTP 404。如果请求签名可以得到验证,则会在响应正文中返回有关错误的其他信息。ErrorResponse
示例请求如下所示:
{
"requestHeader": {
"protocolVersion": {
"major": 3
},
"requestId": "HsKv5pvtQKTtz7rdcw1YqE",
"requestTimestamp": {
"epochMillis": "1519996751331"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD"
},
"paymentLookupCriteria": {
"googleTransactionReferenceNumberCriteria": {
"googleTransactionReferenceNumber": "714545417102363157911822",
"authorizationCode": "111111"
}
},
"existingGoogleClaimId": "138431383281",
"requestOriginator": {
"organizationId": "ISSUER_256",
"organizationDescription": "Community Bank of Some City",
"agentId": "982749"
}
}
示例响应如下所示:
{
"responseHeader": {
"responseTimestamp": {
"epochMillis": "1519996752221"
}
},
"result": {
"success": {
"googleClaimId": "138431383281",
"report": {
"customerAccount": {
"customerEmail": "example@gmail.com",
"customerName" : "Example Customer"
},
"order": {
"timestamp": {
"epochMillis": "1517992525972"
},
"orderId": "SOP.8976-1234-1234-123456..99",
"subTotalAmount": {
"amountMicros": "206990000",
"currencyCode": "USD"
},
"totalAmount": {
"amountMicros": "212990000",
"currencyCode": "USD"
},
"shippingAddress": {
"addressLine": ["123 Main St"],
"localityName": "Springfield",
"administrativeAreaName": "CO",
"postalCodeNumber": "80309",
"countryCode": "US"
},
"taxes": [
{
"description": "Colorado Sales Tax",
"amount": {
"amountMicros": "6000000",
"currencyCode": "USD"
}
}
],
"items": [
{
"description": "Super cool gizmo",
"merchant": "HTC",
"googleProductName": "Google Store",
"quantity": "2",
"totalPrice": {
"amountMicros": "198000000",
"currencyCode": "USD"
}
},
{
"description": "Gizmo charger",
"merchant": "HTC",
"googleProductName": "Google Store",
"quantity": "1",
"totalPrice": {
"amountMicros": "8990000",
"currencyCode": "USD"
}
}
]
},
"payment": {
"billingAddress" : {
"addressLine": ["123 Main St"],
"localityName": "Springfield",
"administrativeAreaName": "CO",
"postalCodeNumber": "80309",
"countryCode": "US"
},
"amount": {
"amountMicros": "100000000",
"currencyCode": "USD"
},
"refunds": [
{
"amount": {
"amountMicros": "9250000",
"currencyCode": "USD"
},
"initiatedTimestamp": {
"epochMillis": "1518811245384"
}
}
],
"cardDetails": {
"authResult": "APPROVED"
}
}
}
}
}
}
HTTP 请求
POST https://vgw.googleapis.com/secure-serving/gsp/v3/getDisputeInquiryReport/:PIAID
请求正文
请求正文中包含结构如下的数据:
JSON 表示法 |
---|
{ "requestHeader": { object ( |
字段 | |
---|---|
requestHeader |
必需:所有请求的通用标头。 |
paymentLookupCriteria |
必需:指明针对此查询要查询的付款的条件。 |
existingGoogleClaimId |
可选:上一次调用 如果缺少该 ID,系统会生成新的版权主张 ID。如果调用方可以提供之前调用 此处填充或生成的声明 ID 将在响应的 提供之前对 |
requestOriginator |
必需:发起此请求的组织或组织子群组的相关信息。 |
响应正文
此方法支持多个返回值类型。如需详细了解随 ErrorResponse
一起返回的 4XX 或 5XX HTTP 状态代码,请参阅 ErrorResponse
对象和 HTTP 状态代码文档。
此方法支持多个返回值类型。如需详细了解随 ErrorResponse
一起返回的 4XX 或 5XX HTTP 状态代码,请参阅 ErrorResponse
对象和 HTTP 状态代码文档。
如果成功,响应正文将包含结构如下的数据:
可能的响应消息 | |
---|---|
HTTP 200 状态 |
|
HTTP 4XX / 5XX 状态 |
|
RequestHeader
发送到服务器的所有请求中定义的标头对象。
JSON 表示法 |
---|
{ "requestId": string, "requestTimestamp": { object ( |
字段 | |
---|---|
requestId |
必需:此请求的唯一标识符。 这是一个最大长度为 100 个字符的字符串,并且仅包含字符“a-z”“A-Z”“0-9”“:”“-”和“_”。 |
requestTimestamp |
必需:此请求的时间戳。接收方必须验证此时间戳是否为“现在”的 ±60 秒,如果不是,则拒绝请求。此请求时间戳在重试时不具有幂等性。 |
protocolVersion |
必需:此请求的版本。 |
paymentIntegratorAccountId |
必需:用于标识具有合同限制的唯一帐号。 |
时间戳
表示 ISO 时间轴上某个点的时间戳对象(以毫秒为单位,从 Unix 纪元开始算起)。
JSON 表示法 |
---|
{ "epochMillis": string } |
字段 | |
---|---|
epochMillis |
必需:自 Unix 纪元起经过的毫秒数 |
版本
Version 对象包含 API 的主要版本。同一主要版本的版本保证兼容。集成商必须支持针对同一主要版本的所有请求。
JSON 表示法 |
---|
{ "major": integer } |
字段 | |
---|---|
major |
必需:主要版本。此属性会被标记为不同版本的兼容性请求,但这并不保证兼容。 |
PaymentLookupCriteria
用于存放可唯一查找付款的条件的容器。必须填充一个(且只能一个)成员字段。
JSON 表示法 |
---|
{ // Union field |
字段 | |
---|---|
联合字段
|
|
arnCriteria |
可选:根据收单机构参考编号 (ARN) 查找。 |
googleTransactionReferenceNumberCriteria |
可选:根据 Google 交易参考号进行查询。 |
captureRequestCriteria |
可选:根据原始拍摄请求进行查找。 |
ArnCriteria
基于收单机构参考编号 (ARN) 的付款查询条件。
JSON 表示法 |
---|
{ "acquirerReferenceNumber": string, "authorizationCode": string } |
字段 | |
---|---|
acquirerReferenceNumber |
必需:用于唯一标识付款的收单机构参考编号 (ARN)。长度必须为 23 位数。 |
authorizationCode |
必需:交易的授权代码。 |
GoogleTransactionReferenceNumberCriteria
基于 Google 生成的交易参考号的付款查询条件。
JSON 表示法 |
---|
{ "googleTransactionReferenceNumber": string, "authorizationCode": string } |
字段 | |
---|---|
googleTransactionReferenceNumber |
必需:Google 生成的交易参考号,用于唯一标识付款。 |
authorizationCode |
必需:交易的授权代码。 |
CaptureRequestCriteria
基于原始捕获请求的付款查询条件。
JSON 表示法 |
---|
{ "captureRequestId": string } |
字段 | |
---|---|
captureRequestId |
必需:此交易的唯一标识符。这是 Google 在查询 |
RequestOriginator
发起此请求的组织或组织子群组(可选)的相关信息。这样,Google 就可以发现问题或滥用行为,并实施比 paymentIntegratorAccountId
更精细的控制措施。当被调用 是来自多个外部客户端请求的中间服务提供商时,此 API 尤其有用。
JSON 表示法 |
---|
{ "organizationId": string, "organizationDescription": string, "agentId": string } |
字段 | |
---|---|
organizationId |
必需:发起此请求的公司、组织或组织群组的标识符。在此 |
organizationDescription |
必需:便于用户阅读的组织名称或说明,便于 Google 员工与该组织集成商之间的沟通。 |
agentId |
可选:该组织中特定代理(员工)的唯一标识符(由 |
GetDisputeInquiryReportResponse
getDisputeInquiryReport
方法的响应载荷。
JSON 表示法 |
---|
{ "responseHeader": { object ( |
字段 | |
---|---|
responseHeader |
必需:所有响应的通用标头。 |
result |
必需:此调用的结果。 |
ResponseHeader
从服务器发送的所有响应中定义的标头对象。
JSON 表示法 |
---|
{
"responseTimestamp": {
object ( |
字段 | |
---|---|
responseTimestamp |
必需:此响应的时间戳。接收者必须验证此时间戳是否为“现在”的 ±60 秒,如果不是,则拒绝响应。 |
GetDisputeInquiryReportResult
JSON 表示法 |
---|
{ // Union field |
字段 | |
---|---|
联合字段
|
|
success |
找到付款并提供了报告。 |
paymentNotFound |
未找到所请求的付款。 |
paymentTooOld |
找到了所请求的付款,但由于付款时间的关系,未能提供报告。 |
orderCannotBeReturned |
所请求的付款属于某个已存在的订单,但无法退款。原因包括:我们应所有者的要求移除了相应命令。 |
noAdditionalDetails |
找到了所请求的付款,但是无法提供报告。 |
SuccessDetails
JSON 表示法 |
---|
{
"googleClaimId": string,
"report": {
object ( |
字段 | |
---|---|
googleClaimId |
必需:Google 生成的字符串,用于唯一标识此客户异议。 如果请求中填充了 |
report |
必需:与请求中指明的付款争议相关的详细信息。 |
PurchaseReport
包含与所请求付款相关的购买详情的报告。
JSON 表示法 |
---|
{ "customerAccount": { object ( |
字段 | |
---|---|
customerAccount |
必需:与客户及其帐号相关的信息。 |
order |
可选:与进行付款的订单相关的信息。只适用于部分购买报告。 |
payment |
必需:与付款相关的信息。注意:可以针对一个订单进行多笔付款,但其中仅包含原始请求中识别出的付款的相关信息。 |
CustomerAccount
客户账号的相关信息。
JSON 表示法 |
---|
{ "customerEmail": string, "customerName": string } |
字段 | |
---|---|
customerEmail |
可选:与客户的 Google 帐号相关联的电子邮件地址。 |
customerName |
必需:客户的名称。 |
订单
订单的相关信息。
JSON 表示法 |
---|
{ "timestamp": { object ( |
字段 | |
---|---|
timestamp |
必需:下单时的时间戳。 |
orderId |
必需:唯一标识此订单的字符串。 |
subTotalAmount |
必需:此订单的税前总金额。 |
totalAmount |
必需:此订单的总金额(含税)。 |
shippingAddress |
可选:此订单中实体商品的送货地址。 |
items[] |
必需:属于此订单的商品的列表。 |
taxes[] |
必需:此订单所含税费的列表。此列表可能为空。 |
金额
将金额(以微单位表示)与货币代码相关联。
JSON 表示法 |
---|
{ "amountMicros": string, "currencyCode": string } |
字段 | |
---|---|
amountMicros |
|
currencyCode |
必需:ISO 4217 货币代码(由 3 个字母组成) |
地址
包含实际地址相关信息的结构。
JSON 表示法 |
---|
{ "addressLine": [ string ], "localityName": string, "administrativeAreaName": string, "postalCodeNumber": string, "countryCode": string } |
字段 | |
---|---|
addressLine[] |
可选:此字段用于保存非结构化地址文本。 |
localityName |
可选:这是一个模糊的术语,但通常是指地址中的城市/城镇部分。对于没有明确定义市行政区或者其无法很好地对应到此结构的地区(例如日本和中国),请将 localityName 留空并使用 addressLine。 示例:美国城市、意大利市、英国邮政区域。 |
administrativeAreaName |
可选:此国家/地区的顶级行政区。“示例:美国的州、IT 区、中国的省、日本的县。” |
postalCodeNumber |
可选:尽管名称为“postalCodeNumber”,但值通常都是字母数字。例如:“94043”“SW1W”“SW1W 9TQ”。 |
countryCode |
可选:客户地址的国家/地区代码,应为 ISO-3166-1 Alpha-2。 |
商品
订单中商品的相关信息。
JSON 表示法 |
---|
{
"description": string,
"merchant": string,
"quantity": string,
"totalPrice": {
object ( |
字段 | |
---|---|
description |
必需:所购商品的说明。 |
merchant |
必需:商品的卖家、音乐人或制造商。 |
quantity |
可选:此商品的订购数量。 如果整数数量不适用于产品(例如,按流量计费的产品可能有小数数量),则此字段将省略。 |
totalPrice |
必需:此商品的总价格。 |
googleProductName |
必需:商品的 Google 产品服务名称。 |
税费
适用于此订单的税费信息。
JSON 表示法 |
---|
{
"description": string,
"amount": {
object ( |
字段 | |
---|---|
description |
必需:税费说明。 |
amount |
必需:税费金额。 |
付款
付款的相关信息。
JSON 表示法 |
---|
{ "billingAddress": { object ( |
字段 | |
---|---|
billingAddress |
必需:此次付款的帐单邮寄地址。 |
amount |
必需:此次付款的金额。 |
refunds[] |
必需:对此付款进行的退款列表。此列表可能为空。 |
联合字段
|
|
cardDetails |
可选:针对信用卡和借记卡 FoP 的付款信息。 |
退款
付款退款的相关信息。
JSON 表示法 |
---|
{ "amount": { object ( |
字段 | |
---|---|
amount |
必需:退款的金额。 |
initiatedTimestamp |
必需:退款发起时间的时间戳。 |
PaymentCardDetails
信用卡和借记卡特有的付款详细信息。
JSON 表示法 |
---|
{
"authResult": enum ( |
字段 | |
---|---|
authResult |
必需:付款身份验证的结果。 |
AuthResult
付款身份验证结果。
枚举 | |
---|---|
UNKNOWN_RESULT |
切勿设置此默认值。 |
APPROVED |
已批准授权。 |
DENIED |
身份验证遭拒。 |
NOT_ATTEMPTED |
未尝试进行身份验证。 |
空
此类型没有任何字段。
此对象用于扩展,因为布尔值和枚举通常需要使用额外数据进行扩展。实现人员使用它来确定是否存在。此表示的枚举可能会扩展,以包含未来版本中的数据。
Empty
的 JSON 表示法是空 JSON 对象 {}
。
ErrorResponse
所有方法的错误响应对象。
JSON 表示法 |
---|
{ "responseHeader": { object ( |
字段 | |
---|---|
responseHeader |
必需:所有响应的通用标头。 |
errorDescription |
可选:提供此状态的说明,以便支持代表调试错误。请注意,此信息绝不会向用户显示。它可以包含用于调试的描述性非敏感文本。请注意,errorResponseCode 的某些值应在此字段中包含其他详细信息。警告:请勿在此消息中包含任何令牌,除非这些令牌被定义为公开。 |
paymentIntegratorErrorIdentifier |
可选:此标识符特定于集成商,由集成商生成。它仅用于调试目的,以识别此调用。这是集成商通过哪种标识符获知此次调用。 |
errorResponseResult |
可选:用于捕获所发生错误类型的代码。 |
ErrorResponseResult
错误代码
JSON 表示法 |
---|
{ // Union field |
字段 | |
---|---|
联合字段
|
|
invalidApiVersion |
在请求的 API 版本不受支持时使用。建议的 HTTP 代码:400 |
invalidPayloadSignature |
如果载荷的签名属于未知或无效密钥,使用此属性。建议的 HTTP 代码:401 |
invalidPayloadEncryption |
如果载荷的加密对象未知或无效密钥,使用此属性。建议的 HTTP 代码:400 |
requestTimestampOutOfRange |
如果 requestTimestamp 并非现在的 60 秒以内,使用此属性。建议的 HTTP 代码:400 |
invalidIdentifier |
如果请求中发送的标识符无效或未知,使用此属性。这可能包括 PIAID、captureRequestId、Google 付款令牌等。建议的 HTTP 代码:404 |
idempotencyViolation |
如果请求违反了其幂等性要求,使用此属性。建议的 HTTP 代码:412 |
invalidFieldValue |
如果请求包含的某个字段的值不在支持的值集中,使用此属性。建议的 HTTP 代码:400 |
missingRequiredField |
如果请求中未设置某个必填字段,使用此属性。建议的 HTTP 代码:400 |
preconditionViolation |
如果违反了操作限制(例如,退款申请金额超过交易的剩余金额),使用此属性。建议的 HTTP 代码:400 |
userActionInProgress |
如果因为请求会中断正在实质上充当系统锁定的进程内用户操作,而现在无法处理请求,则使用此属性。此代码不得用于指示因特定于实现的内部并发错误而导致的失败。建议的 HTTP 代码:423 |
invalidDecryptedRequest |
如果请求载荷可以解密,但无法解析生成的消息,使用此属性。建议的 HTTP 代码:400 |
forbidden |
禁止访问所请求的资源。建议 HTTP 代码:403 |
InvalidApiVersion
JSON 表示法 |
---|
{ "requestVersion": { object ( |
字段 | |
---|---|
requestVersion |
必需:请求中指定的版本无效。 |
expectedVersion |
必需:所需的版本。 |
InvalidPayloadSignature
此类型没有任何字段。
此消息目前有意为空。日后可能会添加新的字段。
InvalidPayloadEncryption
此类型没有任何字段。
此消息目前有意为空。日后可能会添加新的字段。
RequestTimestampOutOfRange
JSON 表示法 |
---|
{ "requestTimestamp": { object ( |
字段 | |
---|---|
requestTimestamp |
必需:请求中提供的时间戳 |
serverTimestampAtReceipt |
必需:接收时的服务器时间,用于比较 |
InvalidIdentifier
JSON 表示法 |
---|
{ "invalidIdentifierType": string } |
字段 | |
---|---|
invalidIdentifierType |
必需:无效的标识符类型,例如 PIAID、captureRequestId 等。 |
IdempotencyViolation
此类型没有任何字段。
此消息目前有意为空。日后可能会添加新的字段。
InvalidFieldValue
JSON 表示法 |
---|
{ "invalidFieldName": string } |
字段 | |
---|---|
invalidFieldName |
必需:被发现无效的字段的名称。 |
MissingRequiredField
JSON 表示法 |
---|
{ "missingFieldNames": [ string ] } |
字段 | |
---|---|
missingFieldNames[] |
必需:缺失字段的名称。 |
PreconditionViolation
此类型没有任何字段。
此消息目前有意为空。日后可能会添加新的字段。
UserActionInProgress
此类型没有任何字段。
此消息目前有意为空。日后可能会添加新的字段。
InvalidDecryptedRequest
此类型没有任何字段。
此消息目前有意为空。日后可能会添加新的字段。
禁止
此类型没有任何字段。
此消息目前有意为空。日后可能会添加新的字段。