- HTTP request
- Request body
- Response body
- TransactionsValidationsContext
- CardTransactionsValidationsContext
- AccountBalanceSummary
- TransactionValidationsResult
- TransactionValidationsSuccess
- GoogleRiskAssessment
- HighRisk
- UserControlsResult
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 ( |
Fields | |
---|---|
requestHeader |
REQUIRED: Common header for all requests. |
googleAccountToken |
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 |
REQUIRED: The amount that will be debited. |
creditorName |
REQUIRED: The creditor's name for this debit. |
description |
REQUIRED: A description of the debit. |
transactionValidationsContext |
REQUIRED: Specifies the type of transaction this is, and will contain any details unique to that transaction type. |
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 ( |
Fields | |
---|---|
responseHeader |
REQUIRED: Common header for all responses. |
result |
REQUIRED: Contains the result of the request. |
TransactionsValidationsContext
JSON representation | |
---|---|
{
"card": {
object ( |
Fields | |
---|---|
card |
Details about card transactions, in a validations context. |
CardTransactionsValidationsContext
JSON representation | |
---|---|
{ "googleInstrumentToken": string, "merchantDetails": { object ( |
Fields | |
---|---|
googleInstrumentToken |
REQUIRED: The UTF-8 encoded, 100 character max length, contains only characters "a-z", "A-Z", "0-9", ":", "-", and "_". |
merchantDetails |
REQUIRED: Additional info about the merchant in this transaction. |
cardPosDetails |
REQUIRED: POS-specific details about the transaction. |
digitalWalletTokenDetails |
OPTIONAL: Details about the digital wallet token used to make the transaction, if any. |
cardholderAuthenticationDetails |
REQUIRED: Details about the cardholder authentication performed during the transaction. |
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 ( |
Fields | |
---|---|
startOfDayLedgerBalance |
REQUIRED: The ledger balance at the start of the day. |
currentLedgerBalance |
REQUIRED: The current ledger balance. |
availableBalance |
REQUIRED: The current available balance. |
TransactionValidationsResult
Details corresponding to the result.
JSON representation | |
---|---|
{
"success": {
object ( |
Fields | |
---|---|
success |
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 ( |
Fields | |
---|---|
riskResult |
DEPRECATED: Google's evaluation of the risk of this transaction. |
userControls |
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 |
Fields | ||
---|---|---|
Union field risk_assessment . A set of risk assessments. risk_assessment can be only one of the following: |
||
lowRisk |
This action is low risk. |
|
highRisk |
This action is high risk. |
HighRisk
Details about a high risk assessment.
JSON representation | |
---|---|
{ // Union field |
Fields | ||
---|---|---|
Union field reason . Details about a high risk assessment. reason can be only one of the following: |
||
accountTakeoverSuspected |
Account Takeover suspected |
|
maliciousSoftwareSuspected |
Malware on device suspected |
UserControlsResult
Google's evaluation of the user's controls for this transaction.
JSON representation | |
---|---|
{ // Union field |
Fields | ||
---|---|---|
Union field
|
||
accepted |
There are no user controls preventing this transaction from going through. |
|
declined |
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. |