- HTTP request
- Request body
- Response body
- AssociateAccountResponse
- AssociateAccountResult
- SuccessDetails
- AssociatedAccountIdentifier
- AssociatedAccountDetails
- AssociatedAccountNickname
- AccountAlias
- AccountType
- WirelessCarrierAccountType
- TransactionLimits
- TransactionLimit
- UserInformation
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
), an associationId
and a googlePaymentToken
(GPT). The payment processor should associate the associationId
and the googlePaymentToken
to the customer's account for authentication. The GPT is used to initiate payments. The associationId
is used during re-authentication calls to identify the account for authentication.
The combination of requestId
within the header and paymentIntegratorAccountId
is the idempotency key and uniquely identifies this association attempt.
If Google sends an associationId
or a googlePaymentToken
that the integrator has already seen during a different association attempt (different idempotency key), the expectation is this would throw an HTTP error.
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": 1
},
"requestId": "cmVxdWVzdDE",
"requestTimestamp": {
"epochMillis": "1481899949606"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD"
},
"googlePaymentToken": {
"issuerId": {
"value": "InvisiCashUSA"
},
"token": "ZXhhbXBsZSB1bmlxdWUgcGF5bWVudCB0b2tlbiB2YWx1ZQ"
},
"authenticationRequestId": "bnAxdWTydDX==",
"associationId": "LmddbXBsZSByZWZlcmVuY2UgdG9rZW4gdmFsdWU_",
"provideUserInformation": true
}
An example response looks like:
{
"responseHeader": {
"responseTimestamp": {
"epochMillis": "1481899949611"
}
},
"result": {
"success": {
"transactionLimits": {
"transactionMaxLimit": {
"limitAmount": {
"amountMicros": "100000000",
"currencyCode": "JPY"
}
}
},
"associatedAccountIdentifier": {
"accountId": "1234-5678-91"
},
"associatedAccountDetails": {
"accountNickname" : {
"partialAccountNickname": "***-91"
},
"accountAlias": {
"phoneNumber": {
"value": "+15555555555"
}
}
},
"userInformation": {
"name": "Example Customer",
"addressLine": ["123 Main St"],
"localityName": "Springfield",
"administrativeAreaName": "CO",
"postalCodeNumber": "80309",
"countryCode": "US"
}
}
}
}
HTTP request
POST https://www.integratorhost.example.com/integrator-base-path/carriers-v1/associateAccount
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. |
google |
REQUIRED: The token that Google will use to initiate purchases with the payment processor. |
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 |
|
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 |
|
AssociateAccountResponse
Response object for the associate account method.
JSON representation |
---|
{ "responseHeader": { object ( |
Fields | |
---|---|
response |
REQUIRED: Common header for all responses. |
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 |
---|
{ "transactionLimits": { object ( |
Fields | |
---|---|
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. |
Union field
|
|
associated |
Details about the account that was associated. |
AssociatedAccountIdentifier
JSON representation |
---|
{ "accountId": string } |
Fields | |
---|---|
account |
REQUIRED: The account ID the user has with the integrator. This is used for Google risk to understand account re-use and account relationships and Google customer operation agents to help customers diagnose issues. This value must be immutable for the life of the account. |
AssociatedAccountDetails
JSON representation |
---|
{ "accountNickname": { object ( |
Fields | |
---|---|
account |
Nickname by which the user knows this account for display purposes. |
account |
OPTIONAL: An additional account alias the user might use to identify their vendor account. These are used by 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). |
account |
OPTIONAL: Account type information that will be used to tailor display messages to users. For example, this could contain information about the payment plan the user has with the integrator for this account. |
AssociatedAccountNickname
JSON representation |
---|
{ // Union field |
Fields | |
---|---|
Union field
|
|
partial |
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. |
full |
String by which the user knows this account for display purposes. Unlike 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 |
Fields | |
---|---|
Union field account_alias . REQUIRED: An account alias the user has with the integrator. account_alias can be only one of the following: |
|
phone |
The phone number the user has on file with the integrator. |
email |
The email address the user has on file with the integrator. |
AccountType
JSON representation |
---|
{ // Union field |
Fields | |
---|---|
Union field
|
|
wireless |
|
WirelessCarrierAccountType
The account type the user has with a wireless carrier. This is used to tailor display messages to the users. For example, the payment dialog for a user with a prepaid plan may say "deduct from your carrier balance", rather than "bill to your carrier account."
JSON representation |
---|
{ // Union field |
Fields | |
---|---|
Union field
|
|
prepaid |
Indicates the user is on a prepaid payment plan with their wireless carrier (e.g. the user pays for the coming month). Payments made with this account will be deducted from the prepaid balance. |
postpaid |
Indicates the user is on a postpaid payment plan with their wireless carrier (e.g. the user pays for the prior month). Payments made with this account will accrue until the balance is paid off. |
enterprise |
Indicates the user is part of an enterprise wireless plan (e.g. the user is on a shared corporate phone plan). |
will |
Indicates the carrier will not provide this information because a user's payment plan is considered PII, or because the carrier is otherwise legally obligated not to share this information. |
control |
Indicates the user is on a control plan with their wireless carrier. This could be a payment plan where the user pays the same monthly fee, and calls or charges made against by the user are debited from this monthly fee. Once the monthly fee amount is exhausted, certain services are limited or disabled unless the user makes a mid-cycle payment to re-enable these services. |
TransactionLimits
Defines transaction limits for the enclosing entity.
JSON representation |
---|
{
"transactionMaxLimit": {
object ( |
Fields | |
---|---|
transaction |
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 |
Fields | |
---|---|
Union field
|
|
limit |
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. |
no |
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. |
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. |