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.

An example request looks like:


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "0123434-otp-abc",
    "requestTimestamp": "1502545413026"
  },
  "accountPhoneNumber": "+918067218010",
  "smsMatchingToken": "AB12345678C"
}

An example response looks like:


{
  "responseHeader": {
    "responseTimestamp": "1502545413098"
  },
  "paymentIntegratorSendOtpId": "99==ABC EF",
  "result": "SUCCESS"
}

HTTP request

POST https://www.integratordomain.com/v1/sendOtp

Request body

The request body contains data with the following structure:

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

object (RequestHeader)

REQUIRED: Common header for all requests.

accountPhoneNumber

string

REQUIRED: This is a E.164 formatted phone number. Examples include +14035551111 and +918067218000. This will always lead with a + and include only numbers afterwards (no dashes).

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

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

Response object for the sendOtp method.

JSON representation
{
  "responseHeader": {
    object (ResponseHeader)
  },
  "paymentIntegratorSendOtpId": string,
  "result": enum (SendOtpResultCode)
}
Fields
responseHeader

object (ResponseHeader)

REQUIRED: Common header for all responses.

paymentIntegratorSendOtpId

string

OPTIONAL: Identifier the integrator knows this send OTP request as. This is integrator generated.

result

enum (SendOtpResultCode)

REQUIRED: Result of this request

SendOtpResultCode

Result codes for send OTP request.

Enums
UNKNOWN_RESULT Do not ever set this default value!
SUCCESS Integrator has sent the OTP.
PHONE_NUMBER_NOT_ASSOCIATED_WITH_ACCOUNT Phone number isn't associated with the account identified by associationId.
UNKNOWN_PHONE_NUMBER Phone number isn't associated with any account. This is used when the associationId isn't set.
MESSAGE_UNABLE_TO_BE_SENT Integrator couldn't send the OTP for some reason. This is a transient error, and may result in this call being retried.
INVALID_PHONE_NUMBER The phone number format was incorrect.
NOT_ELIGIBLE User's account is not eligible for this service.
OTP_LIMIT_REACHED User has requested or tried to verify too many OTPs.
ACCOUNT_CLOSED

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.

ACCOUNT_CLOSED_ACCOUNT_TAKEN_OVER

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.

ACCOUNT_CLOSED_FRAUD

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.