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. Thereafter, only associationId would be sent for all subsequent calls.

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,
      "minor": 0,
      "revision": 0
    },
    "requestId": "0123434-otp-abc",
    "requestTimestamp": "1502545413026"
  },
  "accountPhoneNumber": "+918067218010",
  "smsMatchingToken": "AB12345678C",
  "otpContext": {
    "association": {}
  }
}

An example response looks like:


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

HTTP request

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

Request body

The request body contains data with the following structure:

JSON representation 
{
  "requestHeader": {
    object (RequestHeader)
  },
  "smsMatchingToken": string,
  "otpContext": {
    object (OtpContext)
  },

  // Union field account_identifier can be only one of the following:
  "accountPhoneNumber": string,
  "associationId": string
  // End of list of possible types for union field account_identifier.
}
Fields
requestHeader

object (RequestHeader)

REQUIRED: Common header for all requests.
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

otpContext

object (OtpContext)

OPTIONAL: This is the context in which an OTP is being requested.

Union field account_identifier. REQUIRED: This is the identifier of the account for which an OTP needs to be sent. account_identifier can be only one of the following:
accountPhoneNumber

string

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).

This is populated when a user initially associates their account with Google and during reassociation.
associationId

string

This is the association identifier used to reference a user's account.

This is populated for all subsequent calls after initial association.

Response body

Response object for the sendOtp method.

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

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

OtpContext

Context in which an OTP is being requested.

JSON representation 
{

  // Union field otp_context can be only one of the following:
  "association": {
    object (Empty)
  },
  "mandateCreation": {
    object (Empty)
  },
  "associationWithMandateCreation": {
    object (Empty)
  }
  // End of list of possible types for union field otp_context.
}
Fields
Union field otp_context. REQUIRED: Context in which an OTP is being requested. otp_context can be only one of the following:
association

object (Empty)

OTP is being requested in the context of association/re-association.
mandateCreation

object (Empty)

OTP is being requested in the context of mandate creation.
associationWithMandateCreation

object (Empty)

OTP is being requested for association along with mandate creation.

Empty

This type has no fields.

This object is used for extensibility because booleans and enumerations often need to be extended with extra data. The implementer uses it to determine presence. The enumeration this represents may be extended to contain data in future versions.

The JSON representation for Empty is empty JSON object {}.

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.