Method: getDisputeInquiryReport

Get a report that provides information to facilitate a customer support conversation with a user regarding a potential dispute of a payment.

Responses to this query may be empty if this method does not return an HTTP 200.

If the endpoint encounters an error while processing the request, the response from this endpoint will be of type ErrorResponse.

Responses to this query may be empty if this method does not return an HTTP 200. The response body is empty in situations where an ErrorResponse with a clear description could be used to help an attacker understand the payment integrator account identifier of other integrators. In these situations, where either the signing key doesn't match, the payment integrator identifier was not found, or the encryption key was unknown, this method will return an HTTP 404 with an empty body. If the request signature could be verified, additional information regarding the error will be returned in the response body.

An example request looks like:


{
  "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"
  }
}

An example response looks like:


{
  "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 request

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

Request body

The request body contains data with the following structure:

JSON representation 
{
  "requestHeader": {
    object (RequestHeader)
  },
  "paymentLookupCriteria": {
    object (PaymentLookupCriteria)
  },
  "existingGoogleClaimId": string,
  "requestOriginator": {
    object (RequestOriginator)
  }
}
Fields
requestHeader

object (RequestHeader)

REQUIRED: Common header for all requests.
paymentLookupCriteria

object (PaymentLookupCriteria)

REQUIRED: Criteria indicating the payment that is to be looked up for this inquiry.
existingGoogleClaimId

string

OPTIONAL: A Google-generated string returned by a previous call to getDisputeInquiryReport that uniquely identifies this customer dispute claim.

If this is not present, a new claim ID will be generated. The caller may provide a googleClaimId that was returned by a previous call to getDisputeInquiryReport if it is a continuation of the same customer dispute.

The claim ID that is populated here or generated will be returned in the response's googleClaimId field.

It is not valid to provide a googleClaimId that wasn't returned by a previous call to getDisputeInquiryReport. If this occurs, HTTP 400 Bad Request will be returned.
requestOriginator

object (RequestOriginator)

REQUIRED: Information about the organization or organizational sub-group that originated this request.

Response body

This method supports multiple return types. For additional information about what 4XX or 5XX HTTP status code to return with an ErrorResponse, consult the ErrorResponse object and HTTP status codes documentation.

This method supports multiple return types. For additional information about what 4XX or 5XX HTTP status code to return with an ErrorResponse, consult the ErrorResponse object and HTTP status codes documentation.

If successful, the response body contains data with the following structure:

Possible response messages
HTTP 200 Status

object (GetDisputeInquiryReportResponse)
HTTP 4XX / 5XX Status

object (ErrorResponse)

RequestHeader

Header object that is defined on all requests sent to the server.

JSON representation 
{
  "requestId": string,
  "requestTimestamp": {
    object (Timestamp)
  },
  "protocolVersion": {
    object (Version)
  },
  "paymentIntegratorAccountId": string
}
Fields
requestId

string

REQUIRED: Unique identifier of this request.

This is a string that has a max length of 100 characters, and contains only the characters "a-z", "A-Z", "0-9", ":", "-", and "_".
requestTimestamp

object (Timestamp)

REQUIRED: Timestamp of this request. The receiver must verify that this timestamp is ± 60s of 'now', and reject the request if it is not. This request timestamp is not idempotent upon retries.
protocolVersion

object (Version)

REQUIRED: The version of this request.
paymentIntegratorAccountId

string

REQUIRED: Identifies a unique account with contractual constraints.

Timestamp

A timestamp object representing a point on the ISO timeline in milliseconds since the Unix epoch.

JSON representation 
{
  "epochMillis": string
}
Fields
epochMillis

string (Int64Value format)

Milliseconds since the Unix epoch

Version

Version object contains the major version of the API. Versions of the same major version are guaranteed to be compatible. The integrator must support all requests for the same major version.

JSON representation 
{
  "major": integer
}
Fields
major

integer

REQUIRED: Major version. This is marked for compatibility requests with different versions are not guaranteed to be compatible.

PaymentLookupCriteria

Container for criteria that can uniquely lookup a payment. One (and only one) member field must be populated.

JSON representation 
{

  // 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.
}
Fields

Union field criteria.

criteria can be only one of the following:
arnCriteria

object (ArnCriteria)

OPTIONAL: Lookup based on Acquirer Reference Number (ARN).
googleTransactionReferenceNumberCriteria

object (GoogleTransactionReferenceNumberCriteria)

OPTIONAL: Lookup based on the Google Transaction Reference Number.
captureRequestCriteria

object (CaptureRequestCriteria)

OPTIONAL: Lookup based on the original capture request.

ArnCriteria

Payment lookup criteria based on Acquirer Reference Number (ARN).

JSON representation 
{
  "acquirerReferenceNumber": string,
  "authorizationCode": string
}
Fields
acquirerReferenceNumber

string

REQUIRED: The Acquirer Reference Number (ARN) that uniquely identifies the payment. Must be 23 digits long.
authorizationCode

string

REQUIRED: The Authorization Code for the transaction.

GoogleTransactionReferenceNumberCriteria

Payment lookup criteria based on the Google-generated Transaction Reference Number.

JSON representation 
{
  "googleTransactionReferenceNumber": string,
  "authorizationCode": string
}
Fields
googleTransactionReferenceNumber

string

REQUIRED: The Google-generated Transaction Reference Number that uniquely identifies the payment.
authorizationCode

string

REQUIRED: The Authorization Code for the transaction.

CaptureRequestCriteria

Payment lookup criteria based on the original capture request.

JSON representation 
{
  "captureRequestId": string
}
Fields
captureRequestId

string

REQUIRED: A unique identifier for this transaction. This is the requestId generated by Google during the capture call which is being looked up.

RequestOriginator

Information about the organization or organizational sub-group, and optionally the employee, from which this request originated. This allows Google to identify issues or abuse and implement controls at a finer-grained level than the paymentIntegratorAccountId. It is especially valuable when the called is an intermediary service provider that sources request from multiple external clients.

JSON representation 
{
  "organizationId": string,
  "organizationDescription": string,
  "agentId": string
}
Fields
organizationId

string

REQUIRED: An identifier of the company, organization, or organizational group from which this request originated. Must be unique within this paymentIntegratorAccountId.
organizationDescription

string

REQUIRED: A human-readable name or description of the organization that can be used to ease communication between employees of Google and the integrator regarding that organization.
agentId

string

OPTIONAL: A unique identifier for the specific agent (employee) of the organization identified by organizationId from whom this request originated. Must be unique within this organizationId.

GetDisputeInquiryReportResponse

Response payload for the getDisputeInquiryReport method.

JSON representation 
{
  "responseHeader": {
    object (ResponseHeader)
  },
  "result": {
    object (GetDisputeInquiryReportResult)
  }
}
Fields
responseHeader

object (ResponseHeader)

REQUIRED: Common header for all responses.
result

object (GetDisputeInquiryReportResult)

REQUIRED: Result of this call.

ResponseHeader

Header object that is defined on all responses sent from the server.

JSON representation 
{
  "responseTimestamp": {
    object (Timestamp)
  }
}
Fields
responseTimestamp

object (Timestamp)

REQUIRED: Timestamp of this response. The receiver must verify that this timestamp is ± 60s of 'now', and reject the response if it is not.

GetDisputeInquiryReportResult

JSON representation 
{

  // Union field result can be only one of the following:
  "success": {
    object (SuccessDetails)
  },
  "paymentNotFound": {
    object (Empty)
  },
  "paymentTooOld": {
    object (Empty)
  },
  "orderCannotBeReturned": {
    object (Empty)
  },
  "noAdditionalDetails": {
    object (Empty)
  }
  // End of list of possible types for union field result.
}
Fields

Union field result.

result can be only one of the following:
success

object (SuccessDetails)

The payment was found and a report is provided.
paymentNotFound

object (Empty)

The requested payment was not found.
paymentTooOld

object (Empty)

The requested payment was found, but a report was not provided due to the age of the payment.
orderCannotBeReturned

object (Empty)

The requested payment belongs to an order that exists, but cannot be returned. Reasons include cases where the order was removed at the request of its owner.

noAdditionalDetails

object (Empty)

The requested payment was found, but a report is not available.

SuccessDetails

JSON representation 
{
  "googleClaimId": string,
  "report": {
    object (PurchaseReport)
  }
}
Fields
googleClaimId

string

REQUIRED: A Google-generated string that uniquely identifies this customer dispute.

If existingGoogleClaimId was populated in the request, this will be the same value. Otherwise, it will be a newly generated value. This value can be provided in future getDisputeInquiryReport requests if they are part of the same customer dispute.
report

object (PurchaseReport)

REQUIRED: Details relevant to the dispute of the payment identified in the request.

PurchaseReport

A report containing relevant details of the purchase associated with the requested payment.

JSON representation 
{
  "customerAccount": {
    object (CustomerAccount)
  },
  "order": {
    object (Order)
  },
  "payment": {
    object (Payment)
  }
}
Fields
customerAccount

object (CustomerAccount)

REQUIRED: Information regarding the customer and their account.
order

object (Order)

OPTIONAL: Information regarding the order on which the payment was made. Not available for all purchase reports.
payment

object (Payment)

REQUIRED: Information regarding the payment. Note: Multiple payments are possible on a single order, but this will only contain info for the payment that was identified in the original request.

CustomerAccount

Information about the customer's account.

JSON representation 
{
  "customerEmail": string,
  "customerName": string
}
Fields
customerEmail

string

OPTIONAL: The email address associated with the customer's Google account.
customerName

string

REQUIRED: The customer's name.

Order

Information about the order.

JSON representation 
{
  "timestamp": {
    object (Timestamp)
  },
  "orderId": string,
  "subTotalAmount": {
    object (Amount)
  },
  "totalAmount": {
    object (Amount)
  },
  "shippingAddress": {
    object (Address)
  },
  "items": [
    {
      object (Item)
    }
  ],
  "taxes": [
    {
      object (Tax)
    }
  ]
}
Fields
timestamp

object (Timestamp)

REQUIRED: Timestamp of when the order was made.
orderId

string

REQUIRED: A string uniquely identifying this order.
subTotalAmount

object (Amount)

REQUIRED: Total amount of this order before tax.
totalAmount

object (Amount)

REQUIRED: Total amount of this order including tax.
shippingAddress

object (Address)

OPTIONAL: Shipping address for the physical items in this order.
items[]

object (Item)

REQUIRED: List of items that were part of this order.
taxes[]

object (Tax)

REQUIRED: List of taxes that were part of this order. This list may be empty.

Amount

Associates an amount in micros with a currency code.

JSON representation 
{
  "amountMicros": string,
  "currencyCode": string
}
Fields
amountMicros

string (Int64Value format)

REQUIRED: An amount in micros.
currencyCode

string

REQUIRED: ISO 4217 3-letter currency code

Address

Structure holding information about a physical address.

JSON representation 
{
  "addressLine": [
    string
  ],
  "localityName": string,
  "administrativeAreaName": string,
  "postalCodeNumber": string,
  "countryCode": string
}
Fields
addressLine[]

string

OPTIONAL: This holds unstructured Address text.
localityName

string

OPTIONAL: This is something of a fuzzy term, but it generally refers to the city/town portion of an address. In regions of the world where localities are not well defined or do not fit into this structure well (for example, Japan and China), leave localityName empty and use addressLine.

Examples: US city, IT comune, UK post town.
administrativeAreaName

string

OPTIONAL: Top-level administrative subdivision of this country" Examples: US state, IT region, CN province, JP prefecture."
postalCodeNumber

string

OPTIONAL: Despite the name, postalCodeNumber values are frequently alphanumeric. Examples: "94043", "SW1W", "SW1W 9TQ".
countryCode

string

OPTIONAL: Customer address country code, expected to be ISO-3166-1 Alpha-2.

Item

Information about an item in the order.

JSON representation 
{
  "description": string,
  "merchant": string,
  "quantity": string,
  "totalPrice": {
    object (Amount)
  },
  "googleProductName": string
}
Fields
description

string

REQUIRED: A description of the item that was purchased.
merchant

string

REQUIRED: The seller, artist, or maker of the item.
quantity

string (Int64Value format)

OPTIONAL: The quantity that were ordered of this item.

This field will be omitted if integer quantities are not applicable to the product (metered products may have fractional quantities for example).
totalPrice

object (Amount)

REQUIRED: The total price of this item.
googleProductName

string

REQUIRED: Name of the Google product service for the item.

Tax

Information about a tax that applies to this order.

JSON representation 
{
  "description": string,
  "amount": {
    object (Amount)
  }
}
Fields
description

string

REQUIRED: A description of the tax.
amount

object (Amount)

REQUIRED: The amount of the tax.

Payment

Information about the payment.

JSON representation 
{
  "billingAddress": {
    object (Address)
  },
  "amount": {
    object (Amount)
  },
  "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.
}
Fields
billingAddress

object (Address)

REQUIRED: Billing address for this payment.
amount

object (Amount)

REQUIRED: Amount of this payment.
refunds[]

object (Refund)

REQUIRED: List of refunds made to this payment. This list may be empty.

Union field fopDetails.

fopDetails can be only one of the following:
cardDetails

object (PaymentCardDetails)

OPTIONAL: Payment details specific to credit & debit card FoPs.

Refund

Information about a refund made on a payment.

JSON representation 
{
  "amount": {
    object (Amount)
  },
  "initiatedTimestamp": {
    object (Timestamp)
  }
}
Fields
amount

object (Amount)

REQUIRED: The amount refunded.
initiatedTimestamp

object (Timestamp)

REQUIRED: Timestamp of when the refund was initiated.

PaymentCardDetails

Payment details specific to credit & debit cards.

JSON representation 
{
  "authResult": enum (AuthResult)
}
Fields
authResult

enum (AuthResult)

REQUIRED: Result of payment auth.

AuthResult

Payment auth results.

Enums
UNKNOWN_RESULT Do not ever set this default value.
APPROVED Auth approved.
DENIED Auth denied.
NOT_ATTEMPTED Auth not attempted.

Empty

This type has no fields.

This object is used for extensibility because booleans and enumerations often need to be extended with extra data. The implementer uses it to determine presence. The enumeration this represents may be extended to contain data in future versions.

The JSON representation for Empty is empty JSON object {}.

ErrorResponse

Error Response object for all methods.

JSON representation 
{
  "responseHeader": {
    object (ResponseHeader)
  },
  "errorDescription": string,
  "paymentIntegratorErrorIdentifier": string,
  "errorResponseResult": {
    object (ErrorResponseResult)
  }
}
Fields
responseHeader

object (ResponseHeader)

REQUIRED: Common header for all responses.
errorDescription

string

OPTIONAL: Provide a description of this status for support reps to debug errors. Note that this is never shown to users. It can contain descriptive, non-sensitive text used for debugging. Note that some values for errorResponseCode should be accompanied by additional detail in this field. Warning: Do not include any tokens in this message unless they are defined as public.
paymentIntegratorErrorIdentifier

string

OPTIONAL: This identifier is specific to the integrator and is generated by the integrator. It is used for debugging purposes only in order to identify this call. This is the identifier that the integrator knows this call by.
errorResponseResult

object (ErrorResponseResult)

OPTIONAL: A code that captures the type of error that occurred.

ErrorResponseResult

Error Codes

JSON representation 
{

  // Union field result can be only one of the following:
  "invalidApiVersion": {
    object (InvalidApiVersion)
  },
  "invalidPayloadSignature": {
    object (InvalidPayloadSignature)
  },
  "invalidPayloadEncryption": {
    object (InvalidPayloadEncryption)
  },
  "requestTimestampOutOfRange": {
    object (RequestTimestampOutOfRange)
  },
  "invalidIdentifier": {
    object (InvalidIdentifier)
  },
  "idempotencyViolation": {
    object (IdempotencyViolation)
  },
  "invalidFieldValue": {
    object (InvalidFieldValue)
  },
  "missingRequiredField": {
    object (MissingRequiredField)
  },
  "preconditionViolation": {
    object (PreconditionViolation)
  },
  "userActionInProgress": {
    object (UserActionInProgress)
  },
  "invalidDecryptedRequest": {
    object (InvalidDecryptedRequest)
  },
  "forbidden": {
    object (Forbidden)
  }
  // End of list of possible types for union field result.
}
Fields

Union field result.

result can be only one of the following:
invalidApiVersion

object (InvalidApiVersion)

Used if the request's API version is unsupported. Advised HTTP Code: 400
invalidPayloadSignature

object (InvalidPayloadSignature)

Used if the signature of the payload is to an unknown or inactive key. Advised HTTP Code: 401
invalidPayloadEncryption

object (InvalidPayloadEncryption)

Used if the encryption of the payload is to an unknown or inactive key. Advised HTTP Code: 400
requestTimestampOutOfRange

object (RequestTimestampOutOfRange)

Used if the requestTimestamp is not ± 60s of now. Advised HTTP Code: 400
invalidIdentifier

object (InvalidIdentifier)

Used if an identifier sent in the request was invalid or unknown. This may include PIAID, captureRequestId, Google Payment Token, etc. Advised HTTP Code: 404
idempotencyViolation

object (IdempotencyViolation)

Used if the request violates the idempotency requirements for the request. Advised HTTP Code: 412
invalidFieldValue

object (InvalidFieldValue)

Used if the request contains a value for a field that isn't in the set of supported values. Advised HTTP Code: 400
missingRequiredField

object (MissingRequiredField)

Used if a field that is required is unset in the request. Advised HTTP Code: 400
preconditionViolation

object (PreconditionViolation)

Used if a constraint on the operation is violated (e.g. when a request for a refund amount exceeds the amount remaining on the transaction). Advised HTTP Code: 400
userActionInProgress

object (UserActionInProgress)

Used if the request cannot be processed at this time because it would interrupt an in-process user action which effectively acts as a system lock. This code must not be used to indicate failures due to implementation-specific internal concurrency errors. Advised HTTP Code: 423
invalidDecryptedRequest

object (InvalidDecryptedRequest)

Used if the request payload could be decrypted, but the resulting message could not be parsed. Advised HTTP Code: 400
forbidden

object (Forbidden)

Access to the requested resource is forbidden. Advised Http Code: 403

InvalidApiVersion

JSON representation 
{
  "requestVersion": {
    object (Version)
  },
  "expectedVersion": {
    object (Version)
  }
}
Fields
requestVersion

object (Version)

REQUIRED: The invalid version that was specified on the request.
expectedVersion

object (Version)

REQUIRED: The expected version.

InvalidPayloadSignature

This type has no fields.

This message is intentionally empty right now. New fields could be added in the future.

InvalidPayloadEncryption

This type has no fields.

This message is intentionally empty right now. New fields could be added in the future.

RequestTimestampOutOfRange

JSON representation 
{
  "requestTimestamp": {
    object (Timestamp)
  },
  "serverTimestampAtReceipt": {
    object (Timestamp)
  }
}
Fields
requestTimestamp

object (Timestamp)

REQUIRED: The timestamp provided in the request
serverTimestampAtReceipt

object (Timestamp)

REQUIRED: The server time at receipt, used for comparison

InvalidIdentifier

JSON representation 
{
  "invalidIdentifierType": string
}
Fields
invalidIdentifierType

string

REQUIRED: The type of identifier that was invalid, e.g. PIAID, captureRequestId, etc.

IdempotencyViolation

This type has no fields.

This message is intentionally empty right now. New fields could be added in the future.

InvalidFieldValue

JSON representation 
{
  "invalidFieldName": string
}
Fields
invalidFieldName

string

REQUIRED: The name of the field that was found to be invalid.

MissingRequiredField

JSON representation 
{
  "missingFieldNames": [
    string
  ]
}
Fields
missingFieldNames[]

string

REQUIRED: The names of the missing fields.

PreconditionViolation

This type has no fields.

This message is intentionally empty right now. New fields could be added in the future.

UserActionInProgress

This type has no fields.

This message is intentionally empty right now. New fields could be added in the future.

InvalidDecryptedRequest

This type has no fields.

This message is intentionally empty right now. New fields could be added in the future.

Forbidden

This type has no fields.

This message is intentionally empty right now. New fields could be added in the future.