Method: getDisputeInquiryReport

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

If the echo is successful, the endpoint will return an HTTP 200 and the response will be of type EchoResponse.

If the endpoint encounters an error while processing the request, the endpoint will return HTTP 4xx or 5xx and the HTTP body will either be of type ErrorResponse or contain a generic error (e.g. a message similar to "There was an error. Please try again later.").

The generic error is used 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 a generic error. If the request signature could be verified, additional information regarding the error will be returned in an ErrorResponse.

An example request looks like:


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

An example response looks like:


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

POST https://vgw.googleapis.com/gsp/e-wallets-v1/getDisputeInquiryReport/:PIAID

Request body

The request body contains data with the following structure:

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

object (RequestHeader)

REQUIRED: Common header for all requests.
paymentIntegratorAccountId

string

REQUIRED: The payment integrator account identifier that identifies the caller and associated contractual constraints for this interaction.
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 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.

Possible response messages
HTTP 200 Status

object (GetDisputeInquiryReportResponse)
HTTP 4XX / 5XX Status

object (ErrorResponse)

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 Capture Request ID.

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 Capture Request ID

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 caller is an intermediary service provider that sources requests 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": enum (GetDisputeInquiryReportResultCode),
  "googleClaimId": string,
  "report": {
    object (PurchaseReport)
  }
}
Fields
responseHeader

object (ResponseHeader)

REQUIRED: Common header for all responses.
result

enum (GetDisputeInquiryReportResultCode)

REQUIRED: Result of this call.
googleClaimId

string

OPTIONAL: A Google-generated string that uniquely identifies this customer dispute. (Present if and only if result is SUCCESS.)

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)

OPTIONAL: Details relevant to the dispute of the payment identified in the request. (Present if and only if result is SUCCESS.)

GetDisputeInquiryReportResultCode

The result of the getDisputeInquiryReport method call.

Enums
UNKNOWN_RESULT Do not ever set this default value!
SUCCESS The payment was found and a report is provided.
PAYMENT_NOT_FOUND The requested payment was not found.
PAYMENT_TOO_OLD The requested payment was found, but a report was not provided due to the age of the payment.
ORDER_CANNOT_BE_RETURNED 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.
NO_ADDITIONAL_DETAILS The requested payment was found, but a report is not available.

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)

REQUIRED: Information regarding the order on which the payment was made.
payment

object (Payment)

OPTIONAL: 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. Not available for all order types.

CustomerAccount

Information about the customer's account

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

string

REQUIRED: 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": string,
  "orderId": string,
  "currencyCode": string,
  "subTotalAmount": string,
  "totalAmount": string,
  "shippingAddress": {
    object (Address)
  },
  "items": [
    {
      object (Item)
    }
  ],
  "taxes": [
    {
      object (Tax)
    }
  ]
}
Fields
timestamp

string (int64 format)

OPTIONAL: Timestamp of when the order was made, represented as milliseconds since epoch. Not available for all order types.
orderId

string

OPTIONAL: A string uniquely identifying this order. Not available for all order types.
currencyCode

string

OPTIONAL: ISO 4217 3-letter currency code for all amounts in this order. Not available for all order types.
subTotalAmount

string (Int64Value format)

OPTIONAL: Total amount of this order before tax, represented as micros of the currency specified in order.currencyCode. This is equal to SUM(items.totalPrice). Not available for all order types.
totalAmount

string (Int64Value format)

OPTIONAL: Total amount of this order including tax, represented as micros of the currency specified in order.currencyCode. This is equal to subTotalAmount + SUM(taxes.amount). Not available for all order types.
shippingAddress

object (Address)

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

object (Item)

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

object (Tax)

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

Item

Information about an item in the order.

JSON representation 
{
  "description": string,
  "merchant": string,
  "quantity": string,
  "totalPrice": string,
  "googleProductName": string
}
Fields
description

string

OPTIONAL: A description of the item that was purchased. Not available for all order types.
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

string (Int64Value format)

OPTIONAL: The total price of this item, represented as micros of the currency specified in order.currencyCode. If quantity is populated, this reflects the total price of the entire quantity. Not available for all order types.
googleProductName

string

REQUIRED: Name of Google product service for the item.

Tax

Information about a tax that applies to this order.

JSON representation 
{
  "description": string,
  "amount": string
}
Fields
description

string

REQUIRED: A description of the tax.
amount

string (Int64Value format)

REQUIRED: The amount of the tax, represented as micros of the currency specified in order.currencyCode.

Payment

Information about the payment.

JSON representation 
{
  "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.
}
Fields
billingAddress

object (Address)

REQUIRED: Billing address for this payment.
amount

string (Int64Value format)

REQUIRED: Amount of this payment, represented as micros of the currency specified in order.currencyCode. Note: This may not match the order.totalAmount if the order was paid by way of multiple payments.
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": string,
  "initiatedTimestamp": string
}
Fields
amount

string (Int64Value format)

REQUIRED: The amount refunded, a positive number of micros of the currency specified in order.currencyCode.
initiatedTimestamp

string (int64 format)

REQUIRED: Timestamp of when the refund was initiated, represented as milliseconds since epoch.

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.