Method: getDisputeInquiryReport

获取一份报告，其中提供相关信息，帮助用户就潜在的付款争议与客户支持展开对话。

如果端点在处理请求时遇到错误，来自此端点的响应将是 ErrorResponse 类型。

如果此方法未返回 HTTP 200，对此查询的响应可能为空。如果可以使用包含明确说明的 ErrorResponse 来帮助攻击者了解其他集成商的付款集成商帐号标识符，则响应正文为空。在这些情况下，无论是签名密钥不匹配，未找到付款集成商标识符，或者加密密钥未知，此方法将返回正文为空的 HTTP 404。如果请求签名可以得到验证，则会在响应正文中返回有关错误的其他信息。

示例请求如下所示：


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 1,
      "revision": 0
    },
    "requestId": "HsKv5pvtQKTtz7rdcw1YqE",
    "requestTimestamp": "1519996751331"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA",
  "paymentLookupCriteria": {
    "googleTransactionReferenceNumberCriteria": {
      "googleTransactionReferenceNumber": "714545417102363157911822",
      "authorizationCode": "111111"
    }
  },
  "existingGoogleClaimId": "138431383281",
  "requestOriginator": {
    "organizationId": "ISSUER_256",
    "organizationDescription": "Community Bank of Some City",
    "agentId": "982749"
  }
}

示例响应如下所示：


{
  "responseHeader": {
    "responseTimestamp": "1519996752221"
  },
  "result": "SUCCESS",
  "googleClaimId": "138431383281",
  "report": {
    "customerAccount": {
      "customerEmail": "example@gmail.com",
      "customerName" : "Example Customer"
    },
    "order": {
      "timestamp": "1517992525972",
      "orderId": "SOP.8976-1234-1234-123456..99",
      "currencyCode": "USD",
      "subTotalAmount": "206990000",
      "totalAmount": "212990000",
      "shippingAddress": {
        "name": "Example Customer",
        "addressLine": ["123 Main St"],
        "localityName": "Springfield",
        "administrativeAreaName": "CO",
        "postalCodeNumber": "80309",
        "countryCode": "US"
      },
      "taxes": [
        {
          "description": "Colorado Sales Tax",
          "amount": "6000000"
        }
      ],
      "items": [
        {
          "description": "Super cool gizmo",
          "merchant": "HTC",
          "googleProductName": "Google Store",
          "quantity": "2",
          "totalPrice": "198000000"
        },
        {
          "description": "Gizmo charger",
          "merchant": "HTC",
          "googleProductName": "Google Store",
          "quantity": "1",
          "totalPrice": "8990000"
        }
      ]
    },
    "payment": {
      "billingAddress" : {
        "name": "Example Customer",
        "addressLine": ["123 Main St"],
        "localityName": "Springfield",
        "administrativeAreaName": "CO",
        "postalCodeNumber": "80309",
        "countryCode": "US"
      },
      "amount": "100000000",
      "refunds": [
        {
          "amount": "9250000",
          "initiatedTimestamp": "1518811245384"
        }
      ],
      "cardDetails": {
        "authResult": "APPROVED"
      }
    }
  }
}

HTTP 请求

POST https://vgw.googleapis.com/secure-serving/gsp/v1/getDisputeInquiryReport/:PIAID

请求正文

请求正文中包含结构如下的数据：

JSON 表示法 
{
  "requestHeader": {
    object (RequestHeader)
  },
  "paymentIntegratorAccountId": string,
  "paymentLookupCriteria": {
    object (PaymentLookupCriteria)
  },
  "existingGoogleClaimId": string,
  "requestOriginator": {
    object (RequestOriginator)
  }
}
字段
requestHeader

object (RequestHeader)

必需：所有请求的通用标头。
paymentIntegratorAccountId

string

必需：用于标识调用者的付款集成商帐号标识符，以及针对此互动的相关合同限制。
paymentLookupCriteria

object (PaymentLookupCriteria)

必需：指明针对此查询要查询的付款的条件。
existingGoogleClaimId

string

可选：上一次调用 getDisputeInquiryReport 时返回的字符串，由 Google 生成，用于唯一标识此客户异议声明。

如果缺少此属性，系统会生成新的版权主张 ID。如果调用方可以提供之前调用 getDisputeInquiryReport 返回的 googleClaimId，如果该参数是同一客户争议的延续，

此处填充或生成的声明 ID 将在响应的 googleClaimId 字段中返回。

提供之前对 getDisputeInquiryReport 的调用未返回的 googleClaimId 是无效的。如果出现这种情况，系统会返回 HTTP 400 Bad Request。
requestOriginator

object (RequestOriginator)

必需：发起此请求的组织或组织子群组的相关信息。

响应正文

getDisputeInquiryReport 方法的响应载荷。

如果成功，响应正文将包含结构如下的数据：

JSON 表示法 
{
  "responseHeader": {
    object (ResponseHeader)
  },
  "result": enum (GetDisputeInquiryReportResultCode),
  "googleClaimId": string,
  "report": {
    object (PurchaseReport)
  }
}
字段
responseHeader

object (ResponseHeader)

必需：所有响应的通用标头。
result

enum (GetDisputeInquiryReportResultCode)

必需：此调用的结果。
googleClaimId

string

可选：Google 生成的字符串，用于唯一标识此客户异议。（当且仅当 result 为 SUCCESS 时存在。）

如果请求中填充了 existingGoogleClaimId，此值也相同。否则，将是新生成的值。日后，如果 getDisputeInquiryReport 请求属于同一客户争议，则可以提供此值。
report

object (PurchaseReport)

可选：与请求中指明的付款争议相关的详细信息。（当且仅当 result 为 SUCCESS 时存在。）

RequestHeader

发送到服务器的所有请求中定义的标头对象。

JSON 表示法 
{
  "requestId": string,
  "requestTimestamp": string,
  "userLocale": string,
  "protocolVersion": {
    object (Version)
  }
}
字段
requestId

string

必需：此请求的唯一标识符。

这是一个最大长度为 100 个字符的字符串，并且仅包含字符“a-z”“A-Z”“0-9”“:”“-”和“_”。
requestTimestamp

string (int64 format)

必需：此请求的时间戳，以自纪元以来的毫秒数表示。接收者应验证此时间戳是否为“现在”的 ± 60 秒。此请求时间戳在重试时不具有幂等性。
userLocale
(deprecated)

string

已弃用：由两个或三个字母组成的 ISO 639-2 Alpha 3 语言代码（可视需要后跟连字符和 ISO 3166-1 Alpha-2 国家/地区代码），例如“pt”“pt-BR”“fil”或“fil-PH”。使用此方法有助于驱动响应中的 userMessage 字段。
protocolVersion

object (Version)

必需：此请求的版本。

版本

Version 对象，是经典 a.b.c 版本结构的结构化形式。相同编号的主要版本保证兼容。请注意，次要和修订可能会频繁变动，恕不另行通知。集成商必须支持针对同一主要版本的所有请求。

JSON 表示法 
{
  "major": integer,
  "minor": integer,
  "revision": integer
}
字段
major

integer

必需：主要版本。此属性会被标记为不同版本的兼容性请求，但这并不保证兼容。
minor

integer

必需：次要版本。这表示修复了重大问题。
revision

integer

必需：次要版本。表示小的 bug 修复。

PaymentLookupCriteria

用于存放可唯一查找付款的条件的容器。必须填充一个（且只能一个）成员字段。

JSON 表示法 
{

  // Union field criteria can be only one of the following:
  "arnCriteria": {
    object (ArnCriteria)
  },
  "googleTransactionReferenceNumberCriteria": {
    object (GoogleTransactionReferenceNumberCriteria)
  }
  // End of list of possible types for union field criteria.
}
字段

联合字段 criteria。

criteria 只能是下列其中一项：
arnCriteria

object (ArnCriteria)

可选：根据收单机构参考编号 (ARN) 查找。
googleTransactionReferenceNumberCriteria

object (GoogleTransactionReferenceNumberCriteria)

可选：根据 Google 交易参考号进行查询。

ArnCriteria

基于收单机构参考编号 (ARN) 的付款查询条件。

JSON 表示法 
{
  "acquirerReferenceNumber": string,
  "authorizationCode": string
}
字段
acquirerReferenceNumber

string

必需：用于唯一标识付款的收单机构参考编号 (ARN)。长度必须为 23 位数。
authorizationCode

string

必需：交易的授权代码。

GoogleTransactionReferenceNumberCriteria

基于 Google 生成的交易参考号的付款查询条件。

JSON 表示法 
{
  "googleTransactionReferenceNumber": string,
  "authorizationCode": string
}
字段
googleTransactionReferenceNumber

string

必需：Google 生成的交易参考号，用于唯一标识付款。
authorizationCode

string

必需：交易的授权代码。

RequestOriginator

发起此请求的组织或组织子群组（可选）的相关信息。这样，Google 就可以发现问题或滥用行为，并实施比 paymentIntegratorAccountId 更精细的控制措施。当调用方是来自多个外部客户端的中间服务提供商时，此 API 尤其有用。

JSON 表示法 
{
  "organizationId": string,
  "organizationDescription": string,
  "agentId": string
}
字段
organizationId

string

必需：发起此请求的公司、组织或组织群组的标识符。在此 paymentIntegratorAccountId 中必须是唯一的。
organizationDescription

string

必需：便于用户阅读的组织名称或说明，便于 Google 员工与该组织集成商之间的沟通。
agentId

string

可选：该组织中特定代理（员工）的唯一标识符（由 organizationId 标识，发起此请求）。在此 organizationId 中必须是唯一的。

GetDisputeInquiryReportResultCode

getDisputeInquiryReport 方法调用的结果。

枚举
UNKNOWN_RESULT 切勿设置此默认值！
SUCCESS 找到付款并提供了报告。
PAYMENT_NOT_FOUND 未找到所请求的付款。
PAYMENT_TOO_OLD 找到了所请求的付款，但由于付款时间的关系，未能提供报告。
ORDER_CANNOT_BE_RETURNED 所请求的付款属于某个已存在的订单，但无法退款。原因包括：我们应所有者的要求移除了相应命令。
NO_ADDITIONAL_DETAILS 找到了所请求的付款，但是无法提供报告。

PurchaseReport

包含与所请求付款相关的购买详情的报告。

JSON 表示法 
{
  "customerAccount": {
    object (CustomerAccount)
  },
  "order": {
    object (Order)
  },
  "payment": {
    object (Payment)
  }
}
字段
customerAccount

object (CustomerAccount)

必需：与客户及其帐号相关的信息。
order

object (Order)

必需：与付款所针对的订单相关的信息。
payment

object (Payment)

可选：与付款相关的信息。注意：可以针对一个订单进行多笔付款，但其中仅包含原始请求中识别出的付款的相关信息。并不适用于所有订单类型。

CustomerAccount

客户账号的相关信息

JSON 表示法 
{
  "customerEmail": string,
  "customerName": string
}
字段
customerEmail

string

必需：与客户的 Google 帐号相关联的电子邮件地址。
customerName

string

必需：客户的名称。

下单

订单的相关信息。

JSON 表示法 
{
  "timestamp": string,
  "orderId": string,
  "currencyCode": string,
  "subTotalAmount": string,
  "totalAmount": string,
  "shippingAddress": {
    object (Address)
  },
  "items": [
    {
      object (Item)
    }
  ],
  "taxes": [
    {
      object (Tax)
    }
  ]
}
字段
timestamp

string (int64 format)

可选：下单时的时间戳（以从公元纪年开始计算的毫秒数表示）。并不适用于所有订单类型。
orderId

string

可选：唯一标识此订单的字符串。并不适用于所有订单类型。
currencyCode

string

可选：此订单中所有金额的 ISO 4217 货币代码（由 3 个字母组成）。并不适用于所有订单类型。
subTotalAmount

string (Int64Value format)

可选：此订单的税前总金额，以 order.currencyCode 中所指定货币的微单位表示。等于 SUM(items.totalPrice)。并不适用于所有订单类型。
totalAmount

string (Int64Value format)

可选：此订单的总金额（含税），以 order.currencyCode 中所指定货币的微单位表示。等于 subTotalAmount + SUM(taxes.amount)。并不适用于所有订单类型。
shippingAddress

object (Address)

可选：此订单中实体商品的送货地址。
items[]

object (Item)

必需：属于此订单的商品的列表。
taxes[]

object (Tax)

必需：属于此订单的商品的列表。此列表可能为空。

地址

包含地址相关信息的结构。

JSON 表示法 
{
  "name": string,
  "addressLine": [
    string
  ],
  "localityName": string,
  "administrativeAreaName": string,
  "postalCodeNumber": string,
  "countryCode": string
}
字段
name

string

可选：客户的全名。
addressLine[]

string

可选：此字段用于保存非结构化地址文本。
localityName

string

可选：这是一个模糊的术语，但通常是指地址中的城市/城镇部分。对于没有明确定义市行政区或者其无法很好地对应到此结构的地区（例如日本和中国），请将 localityName 留空并使用 addressLine。

示例：美国城市、意大利市、英国邮政区域。
administrativeAreaName

string

可选：此国家/地区的顶级行政区。“示例：美国的州、IT 区、中国的省、日本的县。”
postalCodeNumber

string

可选：尽管名称为“postalCodeNumber”，但值通常都是字母数字。例如：“94043”“SW1W”“SW1W 9TQ”。
countryCode

string

可选：客户地址的国家/地区代码，应为 ISO-3166-1 Alpha-2。

商品

订单中商品的相关信息。

JSON 表示法 
{
  "description": string,
  "merchant": string,
  "quantity": string,
  "totalPrice": string,
  "googleProductName": string
}
字段
description

string

可选：对所购商品的说明。并不适用于所有订单类型。
merchant

string

必需：商品的卖家、音乐人或制造商。
quantity

string (Int64Value format)

可选：此商品的订购数量。

如果整数数量不适用于产品（例如，按流量计费的产品可能有小数数量），则此字段将省略。
totalPrice

string (Int64Value format)

可选：此商品的总价格，以 order.currencyCode 中所指定货币的微单位表示。如果填充了 quantity，则表示整个数量的总价格。并不适用于所有订单类型。
googleProductName

string

必需：商品的 Google 产品服务名称。

税费

适用于此订单的税费信息。

JSON 表示法 
{
  "description": string,
  "amount": string
}
字段
description

string

必需：税费说明。
amount

string (Int64Value format)

必需：税费金额，以 order.currencyCode 中所指定货币的微单位表示。

付款

付款的相关信息。

JSON 表示法 
{
  "billingAddress": {
    object (Address)
  },
  "amount": string,
  "refunds": [
    {
      object (Refund)
    }
  ],

  // Union field fopDetails can be only one of the following:
  "cardDetails": {
    object (PaymentCardDetails)
  }
  // End of list of possible types for union field fopDetails.
}
字段
billingAddress

object (Address)

必需：此次付款的帐单邮寄地址。
amount

string (Int64Value format)

必需：此付款的金额，以 order.currencyCode 中所指定货币的微单位表示。注意：如果订单为多次付款，则此值可能与 order.totalAmount 不一致。
refunds[]

object (Refund)

必需：对此付款进行的退款列表。此列表可能为空。

联合字段 fopDetails。

fopDetails 只能是下列其中一项：
cardDetails

object (PaymentCardDetails)

可选：针对信用卡和借记卡 FoP 的付款信息。

退款

付款退款的相关信息。

JSON 表示法 
{
  "amount": string,
  "initiatedTimestamp": string
}
字段
amount

string (Int64Value format)

必需：退款金额，即 order.currencyCode 中指定的货币的微单位（正数）。
initiatedTimestamp

string (int64 format)

必需：退款发起的时间戳（以从公元纪年开始计算的毫秒数表示）。

PaymentCardDetails

信用卡和借记卡特有的付款详细信息。

JSON 表示法 
{
  "authResult": enum (AuthResult)
}
字段
authResult

enum (AuthResult)

必需：付款身份验证的结果。

AuthResult

付款身份验证结果。

枚举
UNKNOWN_RESULT 切勿设置此默认值！
APPROVED 已批准授权。
DENIED 身份验证遭拒。
NOT_ATTEMPTED 未尝试进行身份验证。