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

可选:Google 生成的之前调用 getDisputeInquiryReport 的字符串,用来唯一标识此客户异议声明。

如果此 ID 不存在,系统会生成新的版权主张 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 时才会显示)。

PaymentLookupCriteria

用于对付款进行唯一标识的容器。必须填充一个(且只有一个)成员字段。

JSON 表示法
{

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

联合字段 criteria

criteria 只能是下列其中一项:

arnCriteria

object (ArnCriteria)

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

googleTransactionReferenceNumberCriteria

object (GoogleTransactionReferenceNumberCriteria)

可选:根据 Google 交易参考号查找。

captureRequestCriteria

object (CaptureRequestCriteria)

可选:根据拍摄请求 ID 查找。

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

必需:交易的授权代码。

捕获请求条件

基于原始捕获请求的付款查询条件。

JSON 表示法
{
  "captureRequestId": string
}
字段
captureRequestId

string

必需:此交易的唯一标识符。这是 Google 在查询 capture 调用期间生成的 requestId

请求来源

与发起该请求的组织或组织子群组以及(可选)员工有关的信息。这样,Google 就可以发现问题或滥用行为,并采用比 paymentIntegratorAccountId 更精细的控制级别。当调用方是从多个外部客户端请求请求的中间服务提供商时,这尤其有用。

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 发现所请求的付款,但无法提供报告。

购买报告

一份报告,其中含有与相应要求关联的购买交易的相关详细信息。

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

object (CustomerAccount)

必需:客户及其帐号的相关信息。

order

object (Order)

必需:与付款订单相关的信息。

payment

object (Payment)

可选:与付款相关的信息。注意:您可以针对一笔订单进行多次付款,但这只包含原始请求中识别的付款信息。只适用于部分订单类型。

客户帐号

客户帐号的相关信息

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)

OPTIONAL:此订单的总金额(包括税费),以 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

OPTIONAL:尽管名称为 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)

REQUIRED:退款金额,即 order.currencyCode 中指定的币种(正数)微单位

initiatedTimestamp

string (int64 format)

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

PaymentCard 详细信息

信用卡和借记卡专用的付款明细。

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

enum (AuthResult)

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

身份验证结果

付款身份验证结果。

枚举
UNKNOWN_RESULT 切勿设置此默认值!
APPROVED 身份验证已获批准。
DENIED 身份验证遭拒。
NOT_ATTEMPTED 未尝试身份验证。