- HTTP request
- Request body
- Response body
- OtpVerification
- AssociateAccountWithVendorGeneratedTokenResponse
- AssociateAccountResult
- SuccessDetails
- Timestamp
- UserInformation
- UserAuthenticationFailed
- AccountNotEligible
- OtpNotMatched
- OtpAlreadyUsed
- OtpLimitReached
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 ( |
Fields | |
---|---|
request |
REQUIRED: Common header for all requests. |
provide |
REQUIRED: True if we want the Integrator to provide the address associated with this account. |
association |
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
|
|
authentication |
OPTIONAL: |
otp |
Data necessary to verify an OTP generated from |
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 | |
HTTP 4XX / 5XX Status |
|
OtpVerification
Object that encapsulates the OTP verification response.
JSON representation |
---|
{ "sendOtpRequestId": string, "otp": string } |
Fields | |
---|---|
send |
REQUIRED: This is the |
otp |
REQUIRED: This is the OTP the user provided if this call was preceded by a |
AssociateAccountWithVendorGeneratedTokenResponse
Response object for the banking-fop-v2.associateAccountWithVendorGeneratedToken method.
JSON representation |
---|
{ "responseHeader": { object ( |
Fields | |
---|---|
response |
REQUIRED: Common header for all responses. |
paymentIntegratorAssociateAccountId |
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 |
REQUIRED: Result of this association. |
AssociateAccountResult
JSON representation |
---|
{ // Union field |
Fields | |
---|---|
Union field
|
|
success |
The account association was successful. |
user |
Even though the account authentication bundle was returned, the user authentication failed. |
not |
User's account is not eligible for this service. |
otp |
OTP did not match what the integrator sent. |
otp |
OTP was already used. |
otp |
User has requested or tried to verify too many OTPs. |
SuccessDetails
JSON representation |
---|
{ "vendorPaymentToken": string, "tokenExpirationTime": { object ( |
Fields | |
---|---|
vendor |
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 This is a string that has a maximum length of 100 characters. |
token |
OPTIONAL: Timestamp when the token expires. Use |
accountDetails |
DEPRECATED: Details about the account that was associated during the call. |
accountId |
DEPRECATED: The account ID the user has with the integrator. |
transaction |
REQUIRED: Defines user scoped transaction limits. |
user |
REQUIRED: User information that the integrator knows and will share with Google about this customer. Used for risk information and address prepopulation. |
Union field
|
|
associated |
The account ID the user has with the integrator. |
bank |
The account ID the user has with a bank. |
Union field
|
|
associated |
Details about the account that was associated. |
bank |
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 | |
---|---|
epoch |
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 |
OPTIONAL: Customer's full name. |
address |
OPTIONAL: This holds unstructured Address text. |
locality |
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. |
administrative |
OPTIONAL: Top-level administrative subdivision of this country" Examples: US state, IT region, CN province, JP prefecture." |
postal |
OPTIONAL: Despite the name, postalCodeNumber values are frequently alphanumeric. Examples: "94043", "SW1W", "SW1W 9TQ". |
country |
OPTIONAL: Customer address country code, expected to be ISO-3166-1 Alpha-2. |
phone |
OPTIONAL: Customer's phone number. |
email |
OPTIONAL: Customer's email address. |
UserAuthenticationFailed
The user failed to authenticate with the integrator.
JSON representation |
---|
{
"rawResult": {
object ( |
Fields | |
---|---|
raw |
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 |
AccountNotEligible
User's account is not eligible for this service.
JSON representation |
---|
{
"rawResult": {
object ( |
Fields | |
---|---|
raw |
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 |
OtpNotMatched
OTP did not match what the integrator sent.
JSON representation |
---|
{
"rawResult": {
object ( |
Fields | |
---|---|
raw |
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 |
OtpAlreadyUsed
OTP was already used.
JSON representation |
---|
{
"rawResult": {
object ( |
Fields | |
---|---|
raw |
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 |
OtpLimitReached
User has requested or tried to verify too many OTPs.
JSON representation |
---|
{
"rawResult": {
object ( |
Fields | |
---|---|
raw |
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 |