# Method: sendOtp

- [HTTP request](https://developers.google.com/standard-payments/payment-processor-service-api/v1/TopLevel/sendOtp#body.HTTP_TEMPLATE)
- [Request body](https://developers.google.com/standard-payments/payment-processor-service-api/v1/TopLevel/sendOtp#body.request_body)
  - [JSON representation](https://developers.google.com/standard-payments/payment-processor-service-api/v1/TopLevel/sendOtp#body.request_body.SCHEMA_REPRESENTATION)
- [Response body](https://developers.google.com/standard-payments/payment-processor-service-api/v1/TopLevel/sendOtp#body.response_body)
  - [JSON representation](https://developers.google.com/standard-payments/payment-processor-service-api/v1/TopLevel/sendOtp#body.SendOtpResponse.SCHEMA_REPRESENTATION)
- [OtpContext](https://developers.google.com/standard-payments/payment-processor-service-api/v1/TopLevel/sendOtp#OtpContext)
  - [JSON representation](https://developers.google.com/standard-payments/payment-processor-service-api/v1/TopLevel/sendOtp#OtpContext.SCHEMA_REPRESENTATION)
- [Empty](https://developers.google.com/standard-payments/payment-processor-service-api/v1/TopLevel/sendOtp#Empty)
- [SendOtpResultCode](https://developers.google.com/standard-payments/payment-processor-service-api/v1/TopLevel/sendOtp#SendOtpResultCode)

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 `https://developers.google.com/standard-payments/payment-processor-service-api/v1/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 (`https://developers.google.com/standard-payments/payment-processor-service-api/v1/RequestHeader`) }, "smsMatchingToken": string, "otpContext": { object (`https://developers.google.com/standard-payments/payment-processor-service-api/v1/TopLevel/sendOtp#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 (`https://developers.google.com/standard-payments/payment-processor-service-api/v1/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](https://developer.android.com/reference/android/telephony/SmsManager.html#createAppSpecificSmsToken(android.app.PendingIntent)) ). 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 (`https://developers.google.com/standard-payments/payment-processor-service-api/v1/TopLevel/sendOtp#OtpContext`)`` **OPTIONAL**: This is the context in which an OTP is being requested. > [!NOTE] > **Note:** This field will be made REQUIRED in Q3 of 2022. <br /> |
| 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 (`https://developers.google.com/standard-payments/payment-processor-service-api/v1/ResponseHeader`) }, "paymentIntegratorSendOtpId": string, "result": enum (`https://developers.google.com/standard-payments/payment-processor-service-api/v1/TopLevel/sendOtp#SendOtpResultCode`) } ``` |

| Fields ||
|---|---|
| `responseHeader` | ``object (`https://developers.google.com/standard-payments/payment-processor-service-api/v1/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 (`https://developers.google.com/standard-payments/payment-processor-service-api/v1/TopLevel/sendOtp#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 (`https://developers.google.com/standard-payments/payment-processor-service-api/v1/TopLevel/sendOtp#Empty`) }, "mandateCreation": { object (`https://developers.google.com/standard-payments/payment-processor-service-api/v1/TopLevel/sendOtp#Empty`) }, "associationWithMandateCreation": { object (`https://developers.google.com/standard-payments/payment-processor-service-api/v1/TopLevel/sendOtp#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 (`https://developers.google.com/standard-payments/payment-processor-service-api/v1/TopLevel/sendOtp#Empty`)`` OTP is being requested in the context of association/re-association. |
| `mandateCreation` | ``object (`https://developers.google.com/standard-payments/payment-processor-service-api/v1/TopLevel/sendOtp#Empty`)`` OTP is being requested in the context of mandate creation. |
| `associationWithMandateCreation` | ``object (`https://developers.google.com/standard-payments/payment-processor-service-api/v1/TopLevel/sendOtp#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. |