Method: eventNotification

Notify Google that an event has happened on a transaction. There are nine event types. See examples below

Calling this method has no financial impact on the transaction. It informs Google's risk engine that this transaction was authorized to make more informed choices in the future about this account and instrument.

Responses to this method will return SUCCESS when the request properly sent to Google's risk engine.

An example event request for a refund looks like:


{
  "requestHeader": {
    "protocolVersion": {
      "major": 2
    },
    "requestId": "ZWNobyB0cmFuc2FjdGlvbg",
    "merchantId": "merchant:1234567890",
    "requestTimestamp": "1481899949606"
  },
  "transactionId": "kdf9sdfjm3s0F3",
  "eventType": {
    "refunded": {
      "currencyCode": "USD",
      "refundedAmount": "2000",
      "reasonCode": "OUT_OF_STOCK",
      "rawResult": {
        "scope": "VISA",
        "rawCode": "48"
      }
    }
  },
  "eventTimestamp": "1481899949394"
}

An example event success response looks like:


{
  "responseHeader": {
    "responseTimestamp": "1481900013178"
  },
  "result": "SUCCESS"
}

An example event failure response for an invalid transactionId looks like:


{
  "responseHeader": {
    "responseTimestamp": "1481900013178"
  },
  "errorResponseCode": "INVALID_IDENTIFIER",
  "errorDescription": "Order not found"
}

See ErrorResponse for all possible error response codes. Please note that not all response codes are used by the service.

Event type examples

authorizationSucceeded: A transaction has been authorized.


{
  "currencyCode": "USD",
  "authorizedAmount": "990000"
}

authorizationDeclined: A transaction authorization has been declined. 


{
  "reasonCode": "INSUFFICIENT_FUNDS",
  "rawResult": {
    "scope": "VISA",
    "rawCode": "43"
  }
}

authorizationCancelled: A previously successful authorization on a transaction has been cancelled. 


{
  "reasonCode": "ACCIDENTAL_PURCHASE",
  "rawResult": {
    "scope": "VISA",
    "rawCode": "47"
  }
}

priorAuthorizationCaptured: A payment has been captured for a previously authorized transaction. The currency code should be the same as the previously authorized amount. 


{
  "currencyCode": "USD",
  "capturedAmount": "750000"
}

chargebackInquiryRequested: A chargeback inquiry request has been made for a transaction. 


{
  "currencyCode": "USD",
  "chargebackAmount": "750000",
  "reasonCode": "SUSPICIOUS",
  "rawResult": {
    "scope": "VISA",
    "rawCode": "34"
  }
}

chargebackFiled: A transaction has had a chargeback filed. The chargeback can be a partial amount of the full amount authorized. The currency code should be the same as the previously authorized amount. 


{
  "currencyCode": "USD",
  "chargebackAmount": "48000",
  "reasonCode": "NOT_DELIVERED",
  "rawResult": {
    "scope": "VISA",
    "rawCode": "23"
  }
}

chargebackReversed: A transaction has had a chargeback reversed. 


{
  "reversedChargebackRequestId": "MDFA093gfkvasee32",
  "currencyCode": "USD",
  "reversedChargebackAmount": "48000",
  "initiator": "MERCHANT"
}

refunded: a transaction has had a refund. The refund can be a partial amount of the full amount authorized. The currency code should be the same as the previously authorized amount.


{
  "currencyCode": "USD",
  "refundedAmount": "2000",
  "reasonCode": "OUT_OF_STOCK",
  "rawResult": {
    "scope": "VISA",
    "rawCode": "48"
  }
}

refundReversed: A transaction has had a refund reversed.


{
  "reversedRefundRequestId": "MDFA093gfkvasee32"
}

HTTP request

POST https://vgw.googleapis.com/gsp/facilitated-transaction-event-v2/eventNotification/:PIAID

Request body

The request body contains data with the following structure:

JSON representation 
{
  "requestHeader": {
    object (RequestHeader)
  },
  "transactionId": string,
  "eventType": {
    object (EventType)
  },
  "eventTimestamp": string
}
Fields
requestHeader

object (RequestHeader)

Common header for all Facilitated Transactio Event requests.
transactionId

string

A string ID uniquely identifying the transaction in the merchant's system.
eventType

object (EventType)

The event that happened on the transaction.
eventTimestamp

string (int64 format)

Timestamp of this event as known by the vendor. It is represented as milliseconds since epoch.

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 (EventNotificationResponse)
HTTP 4XX / 5XX Status

object (ErrorResponse)

RequestHeader

Header object that is defined on all requests sent to the Facilitated Transaction Event Service.

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

  // Union field identifier can be only one of the following:
  "merchantId": string,
  "gatewayId": string
  // End of list of possible types for union field identifier.
}
Fields
requestId

string

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

string (int64 format)

Timestamp of this request represented as milliseconds since epoch. The receiver should verify that this timestamp is ± 60s of 'now'. This request timestamp is not idempotent upon retries.
protocolVersion

object (Version)

The version of this request.
Union field identifier. The id that represents the caller in Google's systems. Note that this will match the caller id in the URL. identifier can be only one of the following:
merchantId

string
gatewayId

string

Version

Version object which represents the major version of the API.

JSON representation 
{
  "major": integer
}
Fields
major

integer

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

EventType

JSON representation 
{

  // Union field event can be only one of the following:
  "authorizationSucceeded": {
    object (AuthorizationSucceeded)
  },
  "authorizationDeclined": {
    object (AuthorizationDeclined)
  },
  "authorizationCancelled": {
    object (AuthorizationCancelled)
  },
  "priorAuthorizationCaptured": {
    object (PriorAuthorizationCaptured)
  },
  "chargebackInquiryRequested": {
    object (ChargebackInquiryRequested)
  },
  "chargebackFiled": {
    object (ChargebackFiled)
  },
  "chargebackReversed": {
    object (ChargebackReversed)
  },
  "refunded": {
    object (Refunded)
  },
  "refundReversed": {
    object (RefundReversed)
  }
  // End of list of possible types for union field event.
}
Fields

Union field event.

event can be only one of the following:
authorizationSucceeded

object (AuthorizationSucceeded)
authorizationDeclined

object (AuthorizationDeclined)
authorizationCancelled

object (AuthorizationCancelled)
priorAuthorizationCaptured

object (PriorAuthorizationCaptured)
chargebackInquiryRequested

object (ChargebackInquiryRequested)
chargebackFiled

object (ChargebackFiled)
chargebackReversed

object (ChargebackReversed)
refunded

object (Refunded)
refundReversed

object (RefundReversed)

AuthorizationSucceeded

Event object for the authorizationSucceeded event type.

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

string

REQUIRED: ISO 4217 3-letter currency code.
authorizedAmount

string (Int64Value format)

REQUIRED: The amount of the purchase, in micros of the currency unit.

AuthorizationDeclined

Event object for the authorizationDeclined event type.

JSON representation 
{
  "reasonCode": enum (DeclineReasonCode),
  "rawResult": {
    object (RawResult)
  }
}
Fields
reasonCode

enum (DeclineReasonCode)

REQUIRED: The reason the auth was declined
rawResult

object (RawResult)

OPTIONAL: Raw result of this decline. Used to help inform Google's risk engine and analytics. In decline code–mapping situations, data is sometimes lost. The merchant can choose to give Google a raw code. For example, a credit card gateway (the merchant) may use this field to communicate to Google the exact decline 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.

DeclineReasonCode

Enums
DECLINE_REASON_CODE_UNSPECIFIED Do not ever set this default value!
CVC_DECLINE The CVC did not match the account.
INPUT_ERROR The was an input error from customer. Includes but not limited to CVN mismatch, invalid card number, invalid PIN, invalid length of card.
INSUFFICIENT_FUNDS Not enough funds for this charge.
SUSPICIOUS Issuer suspects the legitimacy of the instrument/transaction. Includes but not limited to cases where cardholder does not recognize, call back, account on hold.
ACCOUNT_CLOSED The account on the transaction is closed.
ACCOUNT_EXPIRED The account on the transaction is expired.
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.
FRAUD Confirmed fraud notification from issuer. Includes but not limited to unauthorized transactions, instrument compromised, blocked card, etc.
UNCLEAR No or unclear reason from the vendor is given. This should be used when the reason is unknown.

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.

AuthorizationCancelled

Event object for the authorizationCancelled event type.

JSON representation 
{
  "reasonCode": enum (CancelReasonCode),
  "rawResult": {
    object (RawResult)
  }
}
Fields
reasonCode

enum (CancelReasonCode)

REQUIRED: The reason the auth was cancelled
rawResult

object (RawResult)

OPTIONAL: Raw result of this cancel. Used to help inform Google's risk engine and analytics. In cancel code–mapping situations, data is sometimes lost. The merchant can choose to give Google a raw code. For example, a credit card gateway (the merchant) may use this field to communicate to Google the exact cancel 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.

CancelReasonCode

Enums
CANCEL_REASON_CODE_UNSPECIFIED Do not ever set this default value!
ACCIDENTAL_PURCHASE The customer made an unintended purchase.
FAMILY_FRAUD Issuer reports this as related with family members placing unauthorized transactions.
FRAUD Confirmed fraud notification from issuer. Includes but not limited to unauthorized transactions, instrument compromised, blocked card, etc.
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.
REMORSE The customer changed their mind.
UNCLEAR No or unclear reason from the vendor is given. This should be used when the reason is unknown.

PriorAuthorizationCaptured

Event object for the priorAuthorizationCaptured event type.

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

string

REQUIRED: ISO 4217 3-letter currency code.
capturedAmount

string (Int64Value format)

REQUIRED: The amount captured, in micros of the currency unit.

ChargebackInquiryRequested

Event object for the chargebackInquiryRequested event type.

JSON representation 
{
  "currencyCode": string,
  "chargebackAmount": string,
  "reasonCode": enum (PaymentDisputeReasonCode),
  "rawResult": {
    object (RawResult)
  }
}
Fields
currencyCode

string

REQUIRED: ISO 4217 3-letter currency code.
chargebackAmount

string (Int64Value format)

REQUIRED: The amount of the chargeback, in micros of the currency unit.
reasonCode

enum (PaymentDisputeReasonCode)

REQUIRED: The reason for the chargeback inquiry request
rawResult

object (RawResult)

OPTIONAL: Raw result of this chargeback inquiry request. Used to help inform Google's risk engine and analytics. In chargeback inquiry request code–mapping situations, data is sometimes lost. The merchant can choose to give Google a raw code. For example, a credit card gateway (the merchant) 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.

PaymentDisputeReasonCode

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.

ChargebackFiled

Event object for the chargebackFiled event type.

JSON representation 
{
  "currencyCode": string,
  "chargebackAmount": string,
  "reasonCode": enum (PaymentDisputeReasonCode),
  "rawResult": {
    object (RawResult)
  }
}
Fields
currencyCode

string

REQUIRED: ISO 4217 3-letter currency code.
chargebackAmount

string (Int64Value format)

REQUIRED: The amount of the chargeback, in micros of the currency unit.
reasonCode

enum (PaymentDisputeReasonCode)

REQUIRED: The reason for the chargeback
rawResult

object (RawResult)

OPTIONAL: Raw result of this chargeback. Used to help inform Google's risk engine and analytics. In chargeback code–mapping situations, data is sometimes lost. The merchant can choose to give Google a raw code. For example, a credit card gateway (the merchant) 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.

ChargebackReversed

Event object for the chargebackReversed event type.

JSON representation 
{
  "reversedChargebackRequestId": string,
  "currencyCode": string,
  "reversedChargebackAmount": string,
  "initiator": enum (ChargebackInitiator)
}
Fields
reversedChargebackRequestId

string

REQUIRED: The requestId from the requestHeader for the chargeback that is being reversed.
currencyCode

string

REQUIRED: ISO 4217 3-letter currency code.
reversedChargebackAmount

string (Int64Value format)

REQUIRED: The amount of the reversed chargeback, in micros of the currency unit.
initiator

enum (ChargebackInitiator)

REQUIRED: Who initiated the chargeback.

ChargebackInitiator

Enums
CHARGEBACK_INITIATOR_UNSPECIFIED Do not ever set this default value!
MERCHANT The initiator of the chargeback reversal was the merchant.
USER The initiator of the chargeback reversal was the user.
UNCLEAR The initiator of the chargeback reversal is undetermined.

Refunded

Event object for the refunded event type.

JSON representation 
{
  "currencyCode": string,
  "refundedAmount": string,
  "reasonCode": enum (RefundReasonCode),
  "rawResult": {
    object (RawResult)
  }
}
Fields
currencyCode

string

REQUIRED: ISO 4217 3-letter currency code.
refundedAmount

string (Int64Value format)

REQUIRED: The amount of the refund, a positive number of micros of the currency unit.
reasonCode

enum (RefundReasonCode)

REQUIRED: The reason the refund was made
rawResult

object (RawResult)

OPTIONAL: Raw result of this refund. Used to help inform Google's risk engine and analytics. In refund code–mapping situations, data is sometimes lost. The merchant can choose to give Google a raw code. For example, a credit card gateway (the merchant) may use this field to communicate to Google the exact refund 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.

RefundReasonCode

Enums
REFUND_REASON_CODE_UNSPECIFIED Do not ever set this default value!
ACCIDENTAL_PURCHASE The customer made an unintended purchase.
DEFECTIVE The item did not perform as intended.
DISCONTINUED The item is no longer available.
DUPLICATE_PAYMENT Multiple payments were made for the same transaction.
FAMILY_FRAUD Issuer reports this as related with family members placing unauthorized transactions.
FOUND_BETTER_PRICE The customer found a lower price from a different vendor.
FRAUD Confirmed fraud notification from issuer. Includes but not limited to unauthorized transactions, instrument compromised, blocked card, etc.
MISSING_PARTS The item did not arrive with all required pieces.
NO_PAYMENT No payment was captured.
NOT_AS_DESCRIBED The customer complained that the service/good received is not as described.
NOT_DELIVERED The customer complained that the service/goods were not delivered.
NOT_RECEIVED The customer did not recive the item.
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.
OUT_OF_STOCK The item is not currently in stock.
REMORSE The customer changed their mind.
TOO_LONG_TO_DELIVER The the shipping time was too long.
UNCLEAR No or unclear reason from the vendor is given. This should be used when the reason is unknown.
UNDELIVERABLE The item could not be delivered to the customer
WRONG_SIZE The customer order the incorrect size.

RefundReversed

Event object for the refundReversed event type.

JSON representation 
{
  "reversedRefundRequestId": string
}
Fields
reversedRefundRequestId

string

REQUIRED: The requestId from the requestHeader for the refund that is being reversed.

EventNotificationResponse

Response object for the eventNotification method.

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

object (ResponseHeader)

Common header for all Facilitated Transaction Event responses.
result

enum (EventNotificationResultCode)

Result of the call.

ResponseHeader

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

JSON representation 
{
  "responseTimestamp": string
}
Fields
responseTimestamp

string (int64 format)

REQUIRED: Timestamp of this response represented as milliseconds since epoch. The receiver should verify that this timestamp is ± 60s of 'now'.

EventNotificationResultCode

Result codes for the event method.

Enums
EVENT_NOTIFICATION_RESULT_CODE_UNSPECIFIED Do not ever set this default value!
SUCCESS The request was successfully received.

ErrorResponse

Error Response object for all methods.

JSON representation 
{
  "responseHeader": {
    object (ResponseHeader)
  },
  "errorResponseCode": enum (ErrorResponseCode),
  "errorDescription": string,
  "paymentIntegratorErrorIdentifier": string
}
Fields
responseHeader

object (ResponseHeader)

REQUIRED: Common header for all responses.
errorResponseCode

enum (ErrorResponseCode)

OPTIONAL: A code that captures the type of error that occurred.
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. For example, INVALID_IDENTIFIER should be accompanied by information in this field as to which type of identifier was invalid. 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.

ErrorResponseCode

Error Codes

Enums
UNKNOWN_ERROR_RESPONSE_CODE Do not ever set this default value!
INVALID_API_VERSION Used if the request's API version is unsupported. Advised HTTP Code: 400
INVALID_PAYLOAD_SIGNATURE Used if the signature of the payload is to an unknown or inactive key. Advised HTTP Code: 401
INVALID_PAYLOAD_ENCRYPTION Used if the encryption of the payload is to an unknown or inactive key. Advised HTTP Code: 400
REQUEST_TIMESTAMP_OUT_OF_RANGE Used if the requestTimestamp is not ± 60s of now. Advised HTTP Code: 400
INVALID_IDENTIFIER Used if an identifier sent in the request was invalid or unknown. This may include PIAID, captureRequestId, Google Payment Token, etc. The type of the invalid identifier should be specified in the errorDescription. Advised HTTP Code: 404
IDEMPOTENCY_VIOLATION Used if the request violates the idempotency requirements for the request. Advised HTTP Code: 412
INVALID_FIELD_VALUE Used if the request contains a value for a field that isn't in the set of supported values. Advised HTTP Code: 400
MISSING_REQUIRED_FIELD Used if a field that is required is unset in the request. Advised HTTP Code: 400
PRECONDITION_VIOLATION 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
USER_ACTION_IN_PROGRESS 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
INVALID_DECRYPTED_REQUEST Used if the request payload could be decrypted, but the resulting message could not be parsed. Advised HTTP Code: 400
FORBIDDEN Access to the requested resource is foribidden. Advised HTTP Code: 403