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 echo is successful, the endpoint will return an HTTP 200 and the response will be of type EchoResponse.

If the endpoint encounters an error while processing the request, the endpoint will return HTTP 4xx or 5xx and the HTTP body will either be of type ErrorResponse or contain a generic error (e.g. a message similar to "There was an error. Please try again later.").

The generic error is used 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 a generic error. If the request signature could be verified, additional information regarding the error will be returned in an ErrorResponse.

An example request looks like:


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1
    },
    "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/gsp/carriers-v1/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

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

object (ErrorResponse)

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.

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.

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.

UpdateAssociatedAccountResponse

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.

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.