Method: updateAssociatedAccount

Requests an update to an associated user account.

This method requires that a complete snapshot of the associated account information be provided, along with an update sequence timestamp. The update sequence timestamp is used to determine the most recent update. Updates with an update sequence timestamp older than the current Google record are dropped.

The update sequence timestamp should reflect the time the state of the account was read in milliseconds. The update sequence timestamp must be within +/- 1 min of the Google server time when the request is received, or the request will be rejected with response code 401.

Failed requests may be retried until a 401 response code is received. If a 401 response code is received, the client should refresh the updateSequenceTimestamp prior to retrying the request.

If the endpoint encounters an error while processing the request, the response from this endpoint will be of type ErrorResponse.

Responses to this query may be empty if this method does not return an HTTP 200. The response body is empty 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 an HTTP 404 with an empty body. If the request signature could be verified, additional information regarding the error will be returned in the response body.

An example request looks like:


{
  "requestHeader": {
    "protocolVersion": {
      "major": 2
    },
    "requestId": "8a986fe8-5a2c-45a4-a1bb-3bed6e651020",
    "requestTimestamp": {
      "epochMillis": "1482452962000"
    },
    "paymentIntegratorAccountId": "InvisiCashUSA_USD"
  },
  "googlePaymentToken": {
    "issuerId": {
      "value": "InvisiCashUSA"
    },
    "token": "xcoNWE23812Sflks9an01%s"
  },
  "updateSequenceTimestamp": {
    "epochMillis": "1482452962000"
  },
  "accountInfo": {
    "accountStatus": "ACCOUNT_AVAILABLE",
    "transactionLimits": {
      "transactionMaxLimit": {
        "limitAmount": {
          "amountMicros": "100000000",
          "currencyCode": "JPY"
        }
      }
    },
    "accountIds": {
      "partialAccountNickname": "(XXX) XXX-5555",
      "accountAlias": {
        "phoneNumber": {
          "value": "+15555555555"
        }
      }
    }
  }
}

An example response looks like:


{
  "responseHeader": {
    "responseTimestamp": {
      "epochMillis": "1482452962840"
    }
  },
  "result": {
    "success": {}
  }
}

HTTP request

POST https://vgw.googleapis.com/secure-serving/gsp/v2/updateAssociatedAccount/:PIAID

Request body

The request body contains data with the following structure:

JSON representation 
{
  "requestHeader": {
    object (RequestHeader)
  },
  "googlePaymentToken": {
    object (GooglePaymentToken)
  },
  "updateSequenceTimestampMillis": {
    object (Timestamp)
  },
  "updateSequenceTimestamp": {
    object (Timestamp)
  },

  // Union field account_update can be only one of the following:
  "accountInfo": {
    object (AccountInfo)
  },
  "accountClosureInfo": {
    object (AccountClosureInfo)
  }
  // End of list of possible types for union field account_update.
}
Fields
requestHeader

object (RequestHeader)

REQUIRED: Common header for all requests.
googlePaymentToken

object (GooglePaymentToken)

REQUIRED: This is the token that both companies will use to identify the account to be updated.
updateSequenceTimestampMillis

object (Timestamp)

DEPRECATED: A timestamp describing when this update request was sent. This timestamp is compared to the updateSequenceTimestamp of the current Google record. Updates with an updateSequenceTimestamp older than the current Google record are dropped.
updateSequenceTimestamp

object (Timestamp)

REQUIRED: A timestamp describing when this update request was sent. This timestamp is compared to the updateSequenceTimestamp of the current Google record. Updates with an updateSequenceTimestamp older than the current Google record are dropped.

Union field account_update.

account_update can be only one of the following:
accountInfo

object (AccountInfo)

A complete snapshot of the account information.
accountClosureInfo

object (AccountClosureInfo)

Information about the closure of a user account held with the integrator.

Returning this value will cause the user’s account to be closed with Google. Closed accounts may not be re-opened via UpdateAssociatedAccount. The user will be forced to add a new account by going through the association flow again.

Response body

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

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

object (ResponseHeader)

REQUIRED: Common header for all responses.
result

object (UpdateAssociatedAccountResult)

REQUIRED: Contains the result of the request.

GooglePaymentToken

Describes a GooglePaymentToken (GPT), including the token and the issuer of the backing user account.

JSON representation 
{
  "issuerId": {
    object (IssuerId)
  },
  "token": string
}
Fields
issuerId

object (IssuerId)

REQUIRED: The identifier of the issuer of the backing user account.
token

string

REQUIRED: This is the token that both companies will use to identify the account for purchases between each other.

IssuerId

A unique identifier for an issuer of user accounts.

JSON representation 
{
  "value": string
}
Fields
value

string

REQUIRED: The string value of the identifier. This unique identifier is defined by Google. Google will share a list with the identifiers for all external issuers available via the payment integrator.

AccountInfo

JSON representation 
{
  "accountStatus": enum (AccountStatus),
  "transactionLimits": {
    object (TransactionLimits)
  },
  "accountIds": {
    object (AccountIds)
  }
}
Fields
accountStatus

enum (AccountStatus)

REQUIRED: The status of the user’s account with the integrator.
transactionLimits

object (TransactionLimits)

REQUIRED: Defines user scoped transaction limits.
accountIds

object (AccountIds)

REQUIRED: Defines a nickname for the user account.

AccountStatus

Enums
ACCOUNT_STATUS_UNSPECIFIED Do not ever set this default value!
ACCOUNT_AVAILABLE The user’s account held with the integrator is available for transactions.
ACCOUNT_ON_HOLD The account is on hold.

TransactionLimits

Defines transaction limits for the enclosing entity.

JSON representation 
{
  "transactionMaxLimit": {
    object (TransactionLimit)
  }
}
Fields
transactionMaxLimit

object (TransactionLimit)

REQUIRED: Defines the value and currency of a maximum per transaction limit for the enclosing type, or states that no maximum per transaction limit exists.

TransactionLimit

Defines a transaction limit amount or the absence of a limit.

JSON representation 
{

  // Union field transaction_limit can be only one of the following:
  "limitAmount": {
    object (Amount)
  },
  "noLimit": {
    object (Empty)
  }
  // End of list of possible types for union field transaction_limit.
}
Fields

Union field transaction_limit.

transaction_limit can be only one of the following:
limitAmount

object (Amount)

The value of the allowable transaction. This is used to determine whether or not the user should be given this integrator as an option to process a specific transaction.
noLimit

object (Empty)

Indicates that there is no transaction limit. This is used to determine whether or not the user should be given this integrator as an option to process a specific transaction.

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

AccountIds

JSON representation 
{
  "accountAlias": {
    object (AccountAlias)
  },

  // Union field account_name can be only one of the following:
  "partialAccountNickname": string,
  "fullAccountNickname": string
  // End of list of possible types for union field account_name.
}
Fields
accountAlias

object (AccountAlias)

OPTIONAL: An additional account alias the user associates with their vendor account. These are used for Google risk to understand account re-use and account relationships and Google customer operation agents to help customers diagnose issues. These aliases should be user recognizable (for example the user knows this alias because it appears on their statement or appears on the website after they log into the account).

Union field account_name.

account_name can be only one of the following:
partialAccountNickname

string

String by which the user knows this account for display purposes. This is a suffix of the account nickname. For example last four digits of a phone number. Google will indicate in the user interface that this is only a suffix of the nickname.

This value will be displayed in UIs like the purchase flow to allow the user to distinguish between payment methods.
fullAccountNickname

string

String by which the user knows this account for display purposes. Unlike partialAccountNickname this is the full account nickname. For example 56565-56501 for a phone number or sally@sample-email.com for an email identity.

This value will be displayed in UIs like the purchase flow to allow the user to distinguish between payment methods.

AccountAlias

Defines the type and value of an alias that a user associates with their vendor account.

JSON representation 
{

  // Union field account_alias can be only one of the following:
  "phoneNumber": {
    object (PhoneNumber)
  },
  "emailAddress": string
  // End of list of possible types for union field account_alias.
}
Fields
Union field account_alias. REQUIRED: An account alias the user has with the integrator. account_alias can be only one of the following:
phoneNumber

object (PhoneNumber)

The phone number the user has on file with the integrator.
emailAddress

string

The email address the user has on file with the integrator.

PhoneNumber

An E.164 formatted phone number. Examples include +14035551111 and +918067218000. This will always lead with a + and include only numbers afterwards (no dashes).

JSON representation 
{
  "value": string
}
Fields
value

string

REQUIRED: This is a E.164 formatted phone number. Examples include +14035551111 and +918067218000. This will always lead with a + and include only numbers afterwards (no dashes).

AccountClosureInfo

JSON representation 
{

  // Union field closure_reason can be only one of the following:
  "accountTakenOver": {
    object (Empty)
  },
  "fraud": {
    object (Empty)
  },
  "closedByUser": {
    object (Empty)
  }
  // End of list of possible types for union field closure_reason.
}
Fields

Union field closure_reason.

closure_reason can be only one of the following:
accountTakenOver

object (Empty)

The user’s account held with the integrator has been closed. The integrator suspects the user's account has been taken over.
fraud

object (Empty)

The user’s account held with the integrator has been closed because of fraud.
closedByUser

object (Empty)

The account was closed at the request of the user.

UpdateAssociatedAccountResult

JSON representation 
{

  // Union field result can be only one of the following:
  "success": {
    object (Empty)
  },
  "missingAccountAliasType": {
    object (MissingAccountAliasType)
  }
  // End of list of possible types for union field result.
}
Fields

Union field result.

result can be only one of the following:
success

object (Empty)

The 'UpdateAssociatedAccountRequest' was received successfully by Google. The account will be updated.
missingAccountAliasType

object (MissingAccountAliasType)

A required AccountAlias type is missing

MissingAccountAliasType

JSON representation 
{
  "missingAccountAliasType": string
}
Fields
missingAccountAliasType

string

REQUIRED: If a required AccountAlias type was not provided, the field name corresponding to that type will be given here.