Method: associateAccountWithVendorGeneratedToken

Associates the customer's account with the payment processor to the Google instrument being added.

Account association happens after the integrator has authenticated the user. Association occurs through a server-to-server call that contains the requestId for the associated authentication flow (authenticationRequestId) and an associationId.The payment processor should associate the associationId to the customer's account. The associationId is used during re-authentication calls to identify the account for authentication.

If Google sends an associationId that the integrator has already seen during a different association, then it throws an error.

In the response, the payment processor generates a 'vendorPaymentToken' which is bound to the customer's account and is used for authorizing subsequent payments.

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

An example request looks like:


{
  "requestHeader": {
    "protocolVersion": {
      "major": 2
    },
    "requestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
    "requestTimestamp": {
      "epochMillis": "1502220196077"
    },
    "paymentIntegratorAccountId": "InvisiCashUSD"
  },
 "authenticationRequestId": "bnAxdWTydDX==",
 "associationId": "LmddbXBsZSByZWZlcmVuY2UgdG9rZW4gdmFsdWU_",
 "provideUserInformation": true
}

An example response looks like:


{
  "responseHeader": {
    "responseTimestamp": {
      "epochMillis": "1481900013178"
    }
  },
  "result": {
    "success": {
      "vendorPaymentToken": "ZXhhbXBsZSB1bmlxdWUgcGF5bWVudCB0b2tlbiB2YWx1ZQ",
      "tokenExpirationTime": {
        "epochMillis": "1481919332394"
      },
      "bankAccountIdentifier": {
        "singaporeBankAccount": {
          "sgFastBankAccount": {
            "localAccountNumber": "113A",
            "swiftBic": {
              "value": "COBADEFF478"
            }
          },
          "localBankIdentifier":{
            "localBankCode": "7171",
            "localBranchCode": "060"
          }
        }
      },
      "bankAccountDetails" : {
        "accountNumberSuffix": "1234",
        "bankAccountType": {
          "type": "SAVINGS"
        },
        "bankAccountMetadata": {
        }
      },
      "transactionLimits": {
        "transactionMaxLimit": {
          "noLimit": {}
        }
      },
      "userInformation": {
        "name": "Example Customer",
        "addressLine": ["70 Pasir Panjang Rd"],
        "localityName": "#03-71",
        "postalCodeNumber": "117371",
        "countryCode": "SG"
      }
    }
  }
}

HTTP request

POST https://www.integratorhost.example.com/integrator-base-path/v2/associateAccountWithVendorGeneratedToken

Request body

The request body contains data with the following structure:

JSON representation 
{
  "requestHeader": {
    object (RequestHeader)
  },
  "provideUserInformation": boolean,
  "associationId": string,

  // Union field account_verification can be only one of the following:
  "authenticationRequestId": string,
  "otpVerification": {
    object (OtpVerification)
  }
  // End of list of possible types for union field account_verification.
}
Fields
requestHeader

object (RequestHeader)

REQUIRED: Common header for all requests.
provideUserInformation

boolean

REQUIRED: True if we want the Integrator to provide the address associated with this account.
associationId

string

REQUIRED: The identifier of this association. This identifier is created by Google and is sent during re-authentication flows to identify which account should be authenticated.

This is a string that has a maximum length of 100 characters.

Union field account_verification.

account_verification can be only one of the following:
authenticationRequestId

string

OPTIONAL: requestId of the authentication request that preceded this call. This identifier was generated by Google during the authentication flow. This is only present if the user went through the Android app authentication, web authentication, or an asynchronous authentication method that uses authenticationResultNotification.
otpVerification

object (OtpVerification)

Data necessary to verify an OTP generated from sendOtp. This is only present if the user went through the sendOtp path.

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

object (ErrorResponse)

OtpVerification

Object that encapsulates the OTP verification response.

JSON representation 
{
  "sendOtpRequestId": string,
  "otp": string
}
Fields
sendOtpRequestId

string

REQUIRED: This is the requestId generated by Google during the sendOtp call which this request is associated with.
otp

string

REQUIRED: This is the OTP the user provided if this call was preceded by a sendOtp call

AssociateAccountWithVendorGeneratedTokenResponse

Response object for the banking-fop-v2.associateAccountWithVendorGeneratedToken method.

JSON representation 
{
  "responseHeader": {
    object (ResponseHeader)
  },
  "paymentIntegratorAssociateAccountId": string,
  "result": {
    object (AssociateAccountResult)
  }
}
Fields
responseHeader

object (ResponseHeader)

REQUIRED: Common header for all responses.
paymentIntegratorAssociateAccountId
(deprecated)

string

DEPRECATED: 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.
result

object (AssociateAccountResult)

REQUIRED: Result of this association.

AssociateAccountResult

JSON representation 
{

  // Union field result can be only one of the following:
  "success": {
    object (SuccessDetails)
  },
  "userAuthenticationFailed": {
    object (UserAuthenticationFailed)
  },
  "notEligible": {
    object (AccountNotEligible)
  },
  "otpNotMatched": {
    object (OtpNotMatched)
  },
  "otpAlreadyUsed": {
    object (OtpAlreadyUsed)
  },
  "otpLimitReached": {
    object (OtpLimitReached)
  }
  // End of list of possible types for union field result.
}
Fields

Union field result.

result can be only one of the following:
success

object (SuccessDetails)

The account association was successful.
userAuthenticationFailed

object (UserAuthenticationFailed)

Even though the account authentication bundle was returned, the user authentication failed.
notEligible

object (AccountNotEligible)

User's account is not eligible for this service.
otpNotMatched

object (OtpNotMatched)

OTP did not match what the integrator sent.
otpAlreadyUsed

object (OtpAlreadyUsed)

OTP was already used.
otpLimitReached

object (OtpLimitReached)

User has requested or tried to verify too many OTPs.

SuccessDetails

JSON representation 
{
  "vendorPaymentToken": string,
  "tokenExpirationTime": {
    object (Timestamp)
  },
  "accountDetails": {
    object (AssociatedAccountDetails)
  },
  "accountId": {
    object (AssociatedAccountIdentifier)
  },
  "transactionLimits": {
    object (TransactionLimits)
  },
  "userInformation": {
    object (UserInformation)
  },

  // Union field account_identifier can be only one of the following:
  "associatedAccountIdentifier": {
    object (AssociatedAccountIdentifier)
  },
  "bankAccountIdentifier": {
    object (BankAccountIdentifier)
  }
  // End of list of possible types for union field account_identifier.

  // Union field account_detail can be only one of the following:
  "associatedAccountDetails": {
    object (AssociatedAccountDetails)
  },
  "bankAccountDetails": {
    object (MaskedBankAccountDetails)
  }
  // End of list of possible types for union field account_detail.
}
Fields
vendorPaymentToken

string

REQUIRED: This is the token that both companies will use to identify the bank account that is associated during this method. This identifies the payer bank account in transferFunds calls.

This is a string that has a maximum length of 100 characters.
tokenExpirationTime

object (Timestamp)

OPTIONAL: Timestamp when the token expires. Use 0 to signal the token does not expire.
accountDetails
(deprecated)

object (AssociatedAccountDetails)

DEPRECATED: Details about the account that was associated during the call.
accountId
(deprecated)

object (AssociatedAccountIdentifier)

DEPRECATED: The account ID the user has with the integrator.
transactionLimits

object (TransactionLimits)

REQUIRED: Defines user scoped transaction limits.
userInformation

object (UserInformation)

REQUIRED: User information that the integrator knows and will share with Google about this customer. Used for risk information and address prepopulation.

Union field account_identifier.

account_identifier can be only one of the following:
associatedAccountIdentifier

object (AssociatedAccountIdentifier)

The account ID the user has with the integrator.
bankAccountIdentifier

object (BankAccountIdentifier)

The account ID the user has with a bank.

Union field account_detail.

account_detail can be only one of the following:
associatedAccountDetails

object (AssociatedAccountDetails)

Details about the account that was associated.
bankAccountDetails

object (MaskedBankAccountDetails)

Details about the bank account that was associated.

Timestamp

A timestamp object representing a point on the ISO timeline in milliseconds since the Unix epoch.

JSON representation 
{
  "epochMillis": string
}
Fields
epochMillis

string (Int64Value format)

Milliseconds since the Unix epoch

UserInformation

Structure holding information about a user.

JSON representation 
{
  "name": string,
  "addressLine": [
    string
  ],
  "localityName": string,
  "administrativeAreaName": string,
  "postalCodeNumber": string,
  "countryCode": string,
  "phone": string,
  "emailAddress": string
}
Fields
name

string

OPTIONAL: Customer's full name.
addressLine[]

string

OPTIONAL: This holds unstructured Address text.
localityName

string

OPTIONAL: This is something of a fuzzy term, but it generally refers to the city/town portion of an address. In regions of the world where localities are not well defined or do not fit into this structure well (for example, Japan and China), leave localityName empty and use addressLine.

Examples: US city, IT comune, UK post town.
administrativeAreaName

string

OPTIONAL: Top-level administrative subdivision of this country" Examples: US state, IT region, CN province, JP prefecture."
postalCodeNumber

string

OPTIONAL: Despite the name, postalCodeNumber values are frequently alphanumeric. Examples: "94043", "SW1W", "SW1W 9TQ".
countryCode

string

OPTIONAL: Customer address country code, expected to be ISO-3166-1 Alpha-2.
phone

string

OPTIONAL: Customer's phone number.
emailAddress

string

OPTIONAL: Customer's email address.

UserAuthenticationFailed

The user failed to authenticate with the integrator.

JSON representation 
{
  "rawResult": {
    object (RawResult)
  }
}
Fields
rawResult

object (RawResult)

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

AccountNotEligible

User's account is not eligible for this service.

JSON representation 
{
  "rawResult": {
    object (RawResult)
  }
}
Fields
rawResult

object (RawResult)

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

OtpNotMatched

OTP did not match what the integrator sent.

JSON representation 
{
  "rawResult": {
    object (RawResult)
  }
}
Fields
rawResult

object (RawResult)

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

OtpAlreadyUsed

OTP was already used.

JSON representation 
{
  "rawResult": {
    object (RawResult)
  }
}
Fields
rawResult

object (RawResult)

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

OtpLimitReached

User has requested or tried to verify too many OTPs.

JSON representation 
{
  "rawResult": {
    object (RawResult)
  }
}
Fields
rawResult

object (RawResult)

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