Method: paycache.transactionValidations

The partner bank is asking Google to run any validations that are to be run before a transaction is approved or declined. For example, running user controls and evaluating a risk score for a card transaction that can be incorporated in the bank's decision to approve or deny the transaction. Payment integrators have flexibility in when exactly they call this API during the transaction flow, as long as they are able to incorporate the results in their final decisioning.


{
  "requestHeader": {
    "protocolVersion": {
      "major": 2
    },
    "requestId": "G1MQ0YERJ0Q7LPM",
    "requestTimestamp": {
      "epochMillis":1481899949606
    },
    "paymentIntegratorAccountId": "abcdef123456"
  },
  "googleAccountToken":"A1234567890",
  "amount": {
    "amountMicros":"5000000",
    "currencyCode":"USD"
  },
  "creditorName":"Google Store",
  "description":"Utilities bill",
  "transactionValidationsContext": {
    "card": {
      "googleInstrumentToken": "GoogleCardInstrumentToken1234",
      "merchantDetails": {
        "thirdPartyMerchantDetails": {
          "address": {
            "addressLine": ["1981 Landings Dr"],
            "localityName": "Mountain View",
            "administrativeAreaName": "CA",
            "postalCodeNumber": "94043",
            "countryCode": "US"
          }
        },
        "cardNetworkMerchantDetails": {
          "merchantName": "Google Store",
          "address": {
            "addressLine": ["1981 Landings Dr"],
            "localityName": "Mountain View",
            "administrativeAreaName": "CA",
            "postalCodeNumber": "94043",
            "countryCode": "US"
          },
          "merchantId" : "abc123",
          "merchantCategoryCode": "xyz456"
        }
      },
      "cardPosDetails": {
        "terminalIdentifier" : "tid",
        "cardholderPresence" : "CARDHOLDER_PRESENT",
        "cardPresence" : "CARD_PRESENT",
        "panEntryMode" : "CONTACTLESS_EMV",
        "terminalAttendance" : "TERMINAL_ATTENDED",
        "posCapabilities" : {
          "noDetails" : {},
          "pinInputCapability" : "NO_PIN_INPUT_DETAILS",
          "partialApprovalCapability" : "NO_PARTIAL_APPROVAL_DETAILS"
        },
        "cardFormFactor": "CARD"
      },
      "digitalWalletTokenDetails": {
        "digitalWalletTokenId": "abc123zyx"
      },
      "cardholderAuthenticationDetails": {
        "pinEntryDetails": {
          "pinNotPresent": {}
        },
        "signatureEntryDetails" : {
          "signatureNotPresent": {}
        },
        "addressVerificationDetails" : {
          "addressVerificationNotPerformed": {}
        },
        "ecommerceAuthenticationDetails" : {
          "noAuthentication" : {}
        }
      },
      "cardNetworkTransactionDetails": {
        "network" : "PULSE",
        "riskDetails" : {
          "transactionRiskScore" : 42,
          "merchantRiskScore" : 42
        },
        "acquirerDetails" : {},
        "cardSecurityCodeValidation" : {
          "securityCodeNotPresent" : {}
        }
      }
    }
  },
  "accountBalanceSummary": {
    "startOfDayLedgerBalance": {
      "amountMicros":"120000000",
      "currencyCode":"USD"
    },
    "currentLedgerBalance": {
      "amountMicros":"120000000",
      "currencyCode":"USD"
    },
    "availableBalance": {
      "amountMicros":"100000000",
      "currencyCode":"USD"
    }
  }
}

An example success response looks like:


{
  "responseHeader": {
    "responseTimestamp": {
      "epochMillis":1481899950236
    }
  },
  "result": {
    "success": {
      "riskResult": {
        "lowRisk": {}
      },
      "userControls": {
        "accepted": {}
      }
    }
  }
}

HTTP request

POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/paycache/transactionValidations

Request body

The request body contains data with the following structure:

JSON representation 
{
  "requestHeader": {
    object (RequestHeader)
  },
  "googleAccountToken": string,
  "amount": {
    object (Amount)
  },
  "creditorName": string,
  "description": string,
  "transactionValidationsContext": {
    object (TransactionsValidationsContext)
  },
  "accountBalanceSummary": {
    object (AccountBalanceSummary)
  }
}
Fields
requestHeader

object (RequestHeader)

REQUIRED: Common header for all requests.
googleAccountToken

string

REQUIRED: The unique ID for the account that will be debited. This ID is generated by Google and supplied to the bank during account creation.

UTF-8 encoded, 100 character max length, contains only characters "a-z", "A-Z", "0-9", ":", "-", and "_".
amount

object (Amount)

REQUIRED: The amount that will be debited.
creditorName

string

REQUIRED: The creditor's name for this debit.
description

string

REQUIRED: A description of the debit.
transactionValidationsContext

object (TransactionsValidationsContext)

REQUIRED: Specifies the type of transaction this is, and will contain any details unique to that transaction type.
accountBalanceSummary

object (AccountBalanceSummary)

REQUIRED: An up-to-date summary of the customer's account balance.

Response body

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

Response object for the paycache.transactionValidations method.

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

object (ResponseHeader)

REQUIRED: Common header for all responses.
result

object (TransactionValidationsResult)

REQUIRED: Contains the result of the request.

TransactionsValidationsContext

JSON representation 
{
  "card": {
    object (CardTransactionsValidationsContext)
  }
}
Fields
card

object (CardTransactionsValidationsContext)

Details about card transactions, in a validations context.

CardTransactionsValidationsContext

JSON representation 
{
  "googleInstrumentToken": string,
  "merchantDetails": {
    object (MerchantDetails)
  },
  "cardPosDetails": {
    object (CardPosDetails)
  },
  "digitalWalletTokenDetails": {
    object (DigitalWalletTokenDetails)
  },
  "cardholderAuthenticationDetails": {
    object (CardholderAuthenticationDetails)
  },
  "cardNetworkTransactionDetails": {
    object (CardNetworkTransactionDetails)
  }
}
Fields
googleInstrumentToken

string

REQUIRED: The googleInstrumentToken for the card on which the debit is to be made. This value was given to the payment integrator when issueCard was called to create the card.

UTF-8 encoded, 100 character max length, contains only characters "a-z", "A-Z", "0-9", ":", "-", and "_".
merchantDetails

object (MerchantDetails)

REQUIRED: Additional info about the merchant in this transaction.
cardPosDetails

object (CardPosDetails)

REQUIRED: POS-specific details about the transaction.
digitalWalletTokenDetails

object (DigitalWalletTokenDetails)

OPTIONAL: Details about the digital wallet token used to make the transaction, if any.
cardholderAuthenticationDetails

object (CardholderAuthenticationDetails)

REQUIRED: Details about the cardholder authentication performed during the transaction.
cardNetworkTransactionDetails

object (CardNetworkTransactionDetails)

REQUIRED: Card network-specific details about the transaction.

AccountBalanceSummary

DEPRECATED: Deprecated due to the balance amounts not containing timestamps.

This will be removed before the final version of this spec. Please use 'AccountBalances' instead.

JSON representation 
{
  "startOfDayLedgerBalance": {
    object (Amount)
  },
  "currentLedgerBalance": {
    object (Amount)
  },
  "availableBalance": {
    object (Amount)
  }
}
Fields
startOfDayLedgerBalance

object (Amount)

REQUIRED: The ledger balance at the start of the day.
currentLedgerBalance

object (Amount)

REQUIRED: The current ledger balance.
availableBalance

object (Amount)

REQUIRED: The current available balance.

TransactionValidationsResult

Details corresponding to the result.

JSON representation 
{
  "success": {
    object (TransactionValidationsSuccess)
  }
}
Fields
success

object (TransactionValidationsSuccess)

Contains the result of evaluating all validations.

TransactionValidationsSuccess

This message contains the result of successfully evaluating all validations for the given transaction, despite what the actual outcomes of those validations are. For individual validation outcomes, see the fields of this message.

JSON representation 
{
  "riskResult": {
    object (GoogleRiskAssessment)
  },
  "userControls": {
    object (UserControlsResult)
  }
}
Fields
riskResult
(deprecated)

object (GoogleRiskAssessment)

DEPRECATED: Google's evaluation of the risk of this transaction.
userControls

object (UserControlsResult)

REQUIRED: Google's evaluation of the user's controls for this transaction.

GoogleRiskAssessment

Details about Google's risk assessment of this action.

JSON representation 
{

  // Union field risk_assessment can be only one of the following:
  "lowRisk": {
    object (Empty)
  },
  "highRisk": {
    object (HighRisk)
  }
  // End of list of possible types for union field risk_assessment.
}
Fields
Union field risk_assessment. A set of risk assessments. risk_assessment can be only one of the following:
lowRisk

object (Empty)

This action is low risk.
highRisk

object (HighRisk)

This action is high risk.

HighRisk

Details about a high risk assessment.

JSON representation 
{

  // Union field reason can be only one of the following:
  "accountTakeoverSuspected": {
    object (Empty)
  },
  "maliciousSoftwareSuspected": {
    object (Empty)
  }
  // End of list of possible types for union field reason.
}
Fields
Union field reason. Details about a high risk assessment. reason can be only one of the following:
accountTakeoverSuspected

object (Empty)

Account Takeover suspected
maliciousSoftwareSuspected

object (Empty)

Malware on device suspected

UserControlsResult

Google's evaluation of the user's controls for this transaction.

JSON representation 
{

  // Union field outcome can be only one of the following:
  "accepted": {
    object (Empty)
  },
  "declined": {
    object (Empty)
  }
  // End of list of possible types for union field outcome.
}
Fields

Union field outcome.

outcome can be only one of the following:
accepted

object (Empty)

There are no user controls preventing this transaction from going through.
declined

object (Empty)

There are currently user controls that prevent this transaction from going through and the bank should decline the transaction, assuming that this response is received within SLA.