Method: sendOtp

Requests the integrator send an OTP to the phone number.

If the integrator returns success, then Google expects an SMS sent to the phone number.

Google provides only an accountPhoneNumber when a user initially associates their account with Google. During reauthentication, Google provides the accountPhoneNumber and the associationId. If, during reauthentication, the phone number provided (identified by the accountPhoneNumber) does not match the phone number associated with the account (identified by the associationId) the integrator must return PHONE_NUMBER_NOT_ASSOCIATED_WITH_ACCOUNT.

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": "0123434-otp-abc",
    "requestTimestamp": {
      "epochMillis": "1502545413026"
    },
    "paymentIntegratorAccountId": "InvisiCashUSA_USD"
  },
  "accountPhoneNumber": {
    "value": "+918067218010"
  },
  "smsMatchingToken": "AB12345678C"
}

An example response looks like:


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

HTTP request

POST https://www.integratorhost.example.com/v2/sendOtp

Request body

The request body contains data with the following structure:

JSON representation 
{
  "requestHeader": {
    object (RequestHeader)
  },
  "accountPhoneNumber": {
    object (PhoneNumber)
  },
  "associationId": string,
  "smsMatchingToken": string
}
Fields
requestHeader

object (RequestHeader)

REQUIRED: Common header for all requests.
accountPhoneNumber

object (PhoneNumber)

REQUIRED: The account phone number.
associationId

string

OPTIONAL: This is the association identifier used to reference a user's account. If this is populated then it is expected that the integrator check that this account's phone number is the same phone number passed into accountPhoneNumber. This is important to ensure that Google and the integrator are verifying an OTP sent to the right account.

This is populated whenever Google is performing a re-authentication
smsMatchingToken

string

REQUIRED: This value is provided by Google and must be included in the SMS delivered to the user. This allows Google to auto-match the SMS on the device for Android O devices (see reference ). This will be 11 characters.

So for example, if the SMS normally looks like:

Here's the OTP you requested: <OTP>

And Google sends "0123456789A" for this field, then the SMS should look like:

0123456789A

Here's the OTP you requested: YYXXZZ

Alternatively it could look like:

Here's the OTP you requested: YYXXZZ

0123456789A

Response body

Response object for the sendOtp method.

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

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

object (ResponseHeader)

REQUIRED: Common header for all responses.
result

object (SendOtpResult)

REQUIRED: Result of this request

SendOtpResult

Result codes for send OTP request.

JSON representation 
{

  // Union field result can be only one of the following:
  "success": {
    object (Empty)
  },
  "phoneNumberNotAssociatedWithAccount": {
    object (Empty)
  },
  "unknownPhoneNumber": {
    object (Empty)
  },
  "messageUnableToBeSent": {
    object (Empty)
  },
  "notEligible": {
    object (Empty)
  },
  "otpLimitReached": {
    object (Empty)
  },
  "accountClosed": {
    object (Empty)
  },
  "accountClosedAccountTakenOver": {
    object (Empty)
  },
  "accountClosedFraud": {
    object (Empty)
  }
  // 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)

Integrator has sent the OTP.
phoneNumberNotAssociatedWithAccount

object (Empty)

Phone number isn't associated with the account identified by associationId.
unknownPhoneNumber

object (Empty)

Phone number isn't associated with any account. This is used when the associationId isn't set.
messageUnableToBeSent

object (Empty)

Integrator couldn't send the OTP for some reason. This is a transient error, and may result in this call being retried.
notEligible

object (Empty)

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

object (Empty)

User has requested or tried to verify too many OTPs.
accountClosed

object (Empty)

The user's account held with the integrator has been closed. This should only be used when the "associationId" is being used to identify this user.

Returning this value will cause the user's instrument to be closed with Google. The user will be forced to add a new instrument by going through the association flow again.
accountClosedAccountTakenOver

object (Empty)

The user's account with the integrator has been closed, suspected account take over. This should only be used when the "associationId" is being used to identify this user.

Returning this value will cause the user's instrument to be closed with Google. The user will be forced to add a new instrument by going through the association flow again.
accountClosedFraud

object (Empty)

The user's account held with the integrator has been closed because of fraud. This should only be used when the "associationId" is being used to identify this user.

Returning this value will cause the user's instrument to be closed with Google. The user will be forced to add a new instrument by going through the association flow again.