Method: requestProactiveRefund

  • The Request Proactive Refund API enables payment integrators to request Google to proactively refund transactions, potentially avoiding chargeback disputes.

  • Integrators provide payment details, alert reason, and fraud classification, while Google responds indicating whether the transaction was/should be refunded or not.

  • Possible API responses include: NotRefunded (with a reason), Refunded (by Google), or AcquirerShouldRefund.

  • The API utilizes various data structures like PaymentLookupCriteria, Amount, and FraudClassification for detailed information exchange.

  • This API streamlines proactive refund management, minimizing potential losses and improving customer experience.

Request that a transaction (possibly) be proactively refunded because a chargeback dispute is about to be filed against it.

HTTP request

POST https://vgw.googleapis.com/gsp/chargeback-alert-v1/requestProactiveRefund/:PIAID

Request body

The request body contains data with the following structure:

JSON representation 
{
  "requestHeader": {
    object (RequestHeader)
  },
  "paymentIntegratorAccountId": string,
  "paymentLookupCriteria": {
    object (PaymentLookupCriteria)
  },
  "requestOriginator": {
    object (RequestOriginator)
  },
  "amount": {
    object (Amount)
  },
  "fraudClassification": {
    object (FraudClassification)
  },
  "reasonCode": enum (PaymentDisputeReasonCode),
  "rawResult": {
    object (RawResult)
  },
  "refundIssuer": enum (RefundIssuer)
}
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.
requestOriginator

object (RequestOriginator)

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

object (Amount)

REQUIRED: The requested refund amount.
fraudClassification

object (FraudClassification)

REQUIRED: Whether the vendor considers the original transaction to be fraudulent.
reasonCode

enum (PaymentDisputeReasonCode)

REQUIRED: The reason for the chargeback alert.
rawResult

object (RawResult)

OPTIONAL: Raw result of this chargeback alert. Used to help inform Google's risk engine and analytics. In chargeback code–mapping situations, data is sometimes lost. The integrator can choose to give Google a raw code. For example, a credit card gateway (the integrator) may use this field to communicate to Google the exact chargeback code that was received from the VISA network. In that case, the scope would be "visa" and the rawCode would be whatever the VISA network returned (example: "10.4").
refundIssuer

enum (RefundIssuer)

REQUIRED: Which party is responsible for issuing a refund.

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 (RequestProactiveRefundResponse)
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)
  }
  // End of list of possible types for union field criteria.
}
Fields
Union field criteria. REQUIRED: The criteria for finding the payments. Exactly one member must be set. criteria can be only one of the following:
arnCriteria

object (ArnCriteria)

Lookup based on Acquirer Reference Number (ARN).
googleTransactionReferenceNumberCriteria

object (GoogleTransactionReferenceNumberCriteria)

Lookup based on the Google Transaction Reference Number.

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-24 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.

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

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

FraudClassification

Container for whether or not the vendor considers the original transaction fraudulent. One (and only one) member field must be present.

JSON representation 
{

  // Union field classification can be only one of the following:
  "fraudulent": {
    object (Fraudulent)
  },
  "notFraudulent": {
    object (NotFraudulent)
  }
  // End of list of possible types for union field classification.
}
Fields
Union field classification. REQUIRED: Exactly one of these fields must be set. classification can be only one of the following:
fraudulent

object (Fraudulent)

The original transaction was fraudulent.
notFraudulent

object (NotFraudulent)

The original transaction was not fraudulent.

Fraudulent

Details for a transaction that was fraudulent.

JSON representation 
{
  "fraudType": enum (FraudType)
}
Fields
fraudType

enum (FraudType)

REQUIRED: The type of Fraud.

FraudType

The type of fraud that may have occurred.

Enums
UNKNOWN_TYPE Do not ever set this default value!
FRAUDULENT_USE Use was not authorized.
COUNTERFEIT Account owner did not knowingly participate in a transaction.
LOST The instrument was reported as lost by the account holder at the time of the transaction.
STOLEN The instrument was reported as comprimised by the account holder at the time of the transaction.
ACCOUNT_TAKEOVER The transaction was not authorized by the account holder.
FRAUDULENT_APPLICATION The user did not apply for this account or provided false details.
CARD_NOT_RECEIVED A card was reported as not received by the cardholder at the time of the transaction.
OTHER Unrecognized or unmapped type.
SCAM The cardholder was manipulated by a fraudster to provide payment in good-faith, to an account the cardholder believes belongs to a legitimate payee.
MERCHANT_FRAUD The cardholder was deliberately misled by the merchant.

NotFraudulent

This type has no fields.

Details for a transaction that was not fraudulent.

PaymentDisputeReasonCode

Reason code for disputed transaction.

Enums
UNKNOWN_REASON Do not ever set this default value!
FRAUD Fraudulent transaction.
FAMILIAR_FRAUD Fraudulent transaction made by a family member, friend, or member of the household.
SUSPICIOUS Suspicious transaction.
CHARGE_NOT_RECOGNIZED The user does not recognize the charge on their bill.
CREDIT_NOT_PROCESSED The user was told they would get a refund but they never got it.
DUPLICATE_PAYMENT The user was charged twice for the same purchase.
SUBSCRIPTION_CANCELED The user canceled a subscription but was still charged.
INPUT_ERROR User input error.
INSUFFICIENT_FUNDS User didn't have sufficient funds.
NOT_DELIVERED Item was never delivered.
DEFECTIVE_OR_NOT_AS_DESCRIBED Merchandise was defective or not as described.
INCORRECT_MERCHANDISE The user received the wrong merchandise.
UNWANTED_MERCHANDISE The user was charged for and received merchandise they did not order.
UNCLEAR Missing or unclear signal. This should be used when the reason is unknown.
OTHER Other reasons that are not relevant as risk is concerned. Should be used if the reason is known but does not fit in a currently defined reason.
TRANSACTION_AMOUNT_DIFFER The amount that was charged to the user was not the amount they expected.
PAID_BY_OTHER_MEANS The user was charged for a transaction that they had already paid for by some other means, such as a different instrument.
LATE_PRESENTMENT The transaction was not submitted in time for processing.

RawResult

Raw result object.

JSON representation 
{
  "scope": string,
  "rawCode": string
}
Fields
scope

string

OPTIONAL: Scope of the rawCode, can be empty.
rawCode

string

REQUIRED: Raw code from the integrator or subsystems within it.

RefundIssuer

Which party is responsible for issuing a refund.

Enums
UNKNOWN_TYPE Do not ever set this default value!
MERCHANT The Merchant (Google) is responsible for issuing the refund.
ACQUIRER The Acquirer is responsible for initiating the refund.

RequestProactiveRefundResponse

Response payload for the requestProactiveRefund method.

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

object (ResponseHeader)

REQUIRED: Common header for all responses.
result

object (Result)

REQUIRED: The result of the proactive refund request.

Result

A container for the response details. Exactly one member field must be populated.

JSON representation 
{

  // Union field result can be only one of the following:
  "notRefunded": {
    object (NotRefunded)
  },
  "refunded": {
    object (Refunded)
  },
  "acquirerShouldRefund": {
    object (AcquirerShouldRefund)
  }
  // End of list of possible types for union field result.
}
Fields
Union field result. REQUIRED: The type of result. Exactly one of the values must be set. result can be only one of the following:
notRefunded

object (NotRefunded)

The transaction was not and should not be refunded.
refunded

object (Refunded)

Google refunded the transaction.
acquirerShouldRefund

object (AcquirerShouldRefund)

The acquirer should refund the transaction.

NotRefunded

Details of why the transaction was not refunded.

JSON representation 
{
  "decisionReason": enum (DecisionReason)
}
Fields
decisionReason

enum (DecisionReason)

REQUIRED: The reason why the transaction was not and should not be refunded.

DecisionReason

The reason for the decision not to refund the transaction.

Enums
UNKNOWN_REASON Do not ever set this default value!
PREVIOUSLY_REFUNDED The transaction was previously refunded.
PREVIOUSLY_CHARGED_BACK The transaction was previously charged back.
REQUEST_EXCEEDS_TRANSACTION_AMOUNT The requested refund amount exceeds the original transaction amount by more than the allowed amount.
OTHER Some other reason not covered by the other values.

Refunded

Google refunded the transaction.

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

object (Amount)

REQUIRED: The amount refunded. This may differ from the requested amount if, for example, the amount requested exceeded that of the original transaction.

AcquirerShouldRefund

The acquirer should refund the transaction.

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

object (Amount)

REQUIRED: The amount that should refunded. This may differ from the requested amount if, for example, the amount requested exceeded that of the original transaction.