001/* 002 * Copyright 2020 Vonage 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016package com.vonage.client.verify; 017 018 019import com.vonage.client.*; 020 021import java.util.Locale; 022 023/** 024 * A client for talking to the Vonage Verify API. The standard way to obtain an instance of this class is to use {@link 025 * VonageClient#getVerifyClient()}. 026 * <p> 027 * Send a verification request with a call to {@link #verify}, confirm the code entered by the user with {@link #check}, 028 * and search in-progress or completed verification requests with {@link #search} 029 * <p> 030 * More information on method parameters can be found at Vonage website: 031 * <a href="https://developer.nexmo.com/verify/overview">https://developer.nexmo.com/verify/overview</a> 032 */ 033public class VerifyClient extends AbstractClient { 034 035 private CheckEndpoint check; 036 private VerifyEndpoint verify; 037 private SearchEndpoint search; 038 private ControlEndpoint control; 039 private Psd2Endpoint psd2; 040 041 /** 042 * Constructor. 043 * 044 * @param httpWrapper (required) shared HTTP wrapper object used for making REST calls. 045 */ 046 public VerifyClient(HttpWrapper httpWrapper) { 047 super(httpWrapper); 048 049 this.check = new CheckEndpoint(httpWrapper); 050 this.search = new SearchEndpoint(httpWrapper); 051 this.verify = new VerifyEndpoint(httpWrapper); 052 this.control = new ControlEndpoint(httpWrapper); 053 this.psd2 = new Psd2Endpoint(httpWrapper); 054 } 055 056 /** 057 * Send a verification request to a phone number. 058 * 059 * @param number (required) The recipient's phone number in <a href="https://en.wikipedia.org/wiki/E.164">E.164</a> 060 * format. 061 * @param brand (required) The name of the company or app to be verified for. Must not be longer than 18 062 * characters. 063 * 064 * @return a VerifyResponse representing the response received from the Verify API call. 065 * 066 * @throws VonageClientException if there was a problem with the Vonage request or response objects. 067 * @throws VonageResponseParseException if the response from the API could not be parsed. 068 */ 069 public VerifyResponse verify(final String number, final String brand) throws VonageResponseParseException, VonageClientException { 070 return this.verify.verify(number, brand); 071 } 072 073 /** 074 * Send a verification request to a phone number with a pin verification workflow 075 * 076 * @param number (required) The recipient's phone number in <a href="https://en.wikipedia.org/wiki/E.164">E.164</a> 077 * format. 078 * @param brand (required) The name of the company or app to be verified for. Must not be longer than 18 079 * characters. 080 * @param workflow <a href="https://developer.nexmo.com/verify/guides/workflows-and-events">workflow</a> 081 * to use for sending verification pin 082 * 083 * @return a VerifyResponse representing the response received from the Verify API call. 084 * 085 * @throws VonageClientException if there was a problem with the Vonage request or response objects. 086 * @throws VonageResponseParseException if the response from the API could not be parsed. 087 * @since 5.5.0 088 */ 089 public VerifyResponse verify(final String number, final String brand, VerifyRequest.Workflow workflow) 090 throws VonageResponseParseException, VonageClientException { 091 return this.verify.verify(number, brand, workflow); 092 } 093 094 095 096 /** 097 * Send a verification request to a phone number. 098 * 099 * @param number (required) The recipient's phone number in <a href="https://en.wikipedia.org/wiki/E.164">E.164</a> 100 * format. 101 * @param brand (required) The name of the company or app to be verified for. Must not be longer than 18 102 * characters. 103 * @param from (optional The Vonage number to use as the sender for the verification SMS message and calls, in 104 * <a href="https://en.wikipedia.org/wiki/E.164">E.164</a> format. 105 * 106 * @return a VerifyResponse representing the response received from the Verify API call. 107 * 108 * @throws VonageClientException if there was a problem with the Vonage request or response objects. 109 * @throws VonageResponseParseException if the response from the API could not be parsed. 110 */ 111 public VerifyResponse verify(final String number, 112 final String brand, 113 final String from) throws VonageClientException, VonageResponseParseException { 114 return this.verify.verify(number, brand, from); 115 } 116 117 /** 118 * Send a verification request to a phone number. 119 * 120 * @param number (required) The recipient's phone number in <a href="https://en.wikipedia.org/wiki/E.164">E.164</a> 121 * format. 122 * @param brand (required) The name of the company or app to be verified for. Must not be longer than 18 123 * characters. 124 * @param from (optional The Vonage number to use as the sender for the verification SMS message and calls, in 125 * <a href="https://en.wikipedia.org/wiki/E.164">E.164</a> format. 126 * @param length (optional) The length of the verification code to be sent to the user. Must be either 4 or 6. Use 127 * -1 to use the default value. 128 * @param locale (optional) Override the default locale used for verification. By default the locale is determined 129 * from the country code included in {@code number} 130 * 131 * @return a VerifyResponse representing the response received from the Verify API call. 132 * 133 * @throws VonageClientException if there was a problem with the Vonage request or response objects. 134 * @throws VonageResponseParseException if the response from the API could not be parsed. 135 */ 136 public VerifyResponse verify(final String number, 137 final String brand, 138 final String from, 139 final int length, 140 final Locale locale) throws VonageClientException, VonageResponseParseException { 141 return this.verify.verify(number, brand, from, length, locale); 142 } 143 144 /** 145 * Send a verification request to a phone number. 146 * 147 * @param number (required) The recipient's phone number in <a href="https://en.wikipedia.org/wiki/E.164">E.164</a> 148 * format. 149 * @param brand (required) The name of the company or app to be verified for. Must not be longer than 18 150 * characters. 151 * @param from (optional The Vonage number to use as the sender for the verification SMS message and calls, in 152 * <a href="https://en.wikipedia.org/wiki/E.164">E.164</a> format. 153 * @param length (optional) The length of the verification code to be sent to the user. Must be either 4 or 6. Use 154 * -1 to use the default value. 155 * @param locale (optional) Override the default locale used for verification. By default the locale is determined 156 * from the country code included in {@code number} 157 * @param type (optional) If provided, restrict the verification to the specified network type. Contact 158 * support@nexmo.com to enable this feature. 159 * 160 * @return a VerifyResponse representing the response received from the Verify API call. 161 * 162 * @throws VonageClientException if there was a problem with the Vonage request or response objects. 163 * @throws VonageResponseParseException if the response from the API could not be parsed. 164 */ 165 public VerifyResponse verify(final String number, 166 final String brand, 167 final String from, 168 final int length, 169 final Locale locale, 170 final VerifyRequest.LineType type) throws VonageClientException { 171 return this.verify.verify(number, brand, from, length, locale, type); 172 } 173 174 /** 175 * Send a verification request to a phone number. 176 * 177 * @param request validation request for the 2FA verification. 178 * @return a VerifyResponse representing the response received from the Verify API call. 179 * 180 * @throws VonageClientException if there was a problem with the Vonage request or response objects. 181 * @throws VonageResponseParseException if the response from the API could not be parsed. 182 * 183 */ 184 public VerifyResponse verify(VerifyRequest request) throws VonageClientException, VonageResponseParseException { 185 return this.verify.verify(request); 186 } 187 188 /** 189 * Validate a code provided by a user in response to a call from {@link #verify}. 190 * 191 * @param requestId (required) The requestId returned by the {@code verify} call. 192 * @param code (required) The code entered by the user. 193 * 194 * @return a CheckResponse representing the response received from the API call. 195 * 196 * @throws VonageClientException if there was a problem with the Vonage request or response objects. 197 * @throws VonageResponseParseException if the response from the API could not be parsed. 198 */ 199 public CheckResponse check(final String requestId, final String code) throws VonageClientException, VonageResponseParseException { 200 return this.check.check(requestId, code); 201 } 202 203 /** 204 * Validate a code provided by a user in response to a call from {@link #verify}. 205 * 206 * @param requestId (required) The requestId returned by the {@code verify} call. 207 * @param code (required) The code entered by the user. 208 * @param ipAddress (optional) The IP address obtained from the HTTP request made when the user entered their code. 209 * 210 * @return a CheckResponse representing the response received from the API call. 211 * 212 * @throws VonageClientException if there was a problem with the Vonage request or response objects. 213 * @throws VonageResponseParseException if the response from the API could not be parsed. 214 */ 215 public CheckResponse check(final String requestId, 216 final String code, 217 final String ipAddress) throws VonageClientException, VonageResponseParseException { 218 return this.check.check(requestId, code, ipAddress); 219 } 220 221 /** 222 * Search for a previous verification request. 223 * 224 * @param requestId The requestId of a single Verify request to be looked up. 225 * 226 * @return A SearchVerifyResponse containing the details of the Verify request that was looked up, or {@code null} 227 * if no record was found. 228 * 229 * @throws VonageClientException if there was a problem with the Vonage request or response objects. 230 * @throws VonageResponseParseException if the response from the API could not be parsed. 231 */ 232 public SearchVerifyResponse search(String requestId) throws VonageClientException, VonageResponseParseException { 233 return this.search.search(requestId); 234 } 235 236 /** 237 * Search for a previous verification request. 238 * 239 * @param requestIds The requestIds of Verify requests to be looked up. 240 * 241 * @return An array SearchVerifyResponse for each record that was found. 242 * 243 * @throws VonageClientException if there was a problem with the Vonage request or response objects. 244 * @throws VonageResponseParseException if the response from the API could not be parsed. 245 */ 246 public SearchVerifyResponse search(String... requestIds) throws VonageClientException, VonageResponseParseException { 247 return this.search.search(requestIds); 248 } 249 250 /** 251 * Advance a current verification request to the next stage in the process. 252 * 253 * @param requestId The requestId of the ongoing verification request. 254 * 255 * @return A {@link ControlResponse} representing the response from the API. 256 * 257 * @throws VonageClientException if there was a problem with the Vonage request or response objects. 258 * @throws VonageResponseParseException if the response from the API could not be parsed. 259 */ 260 public ControlResponse advanceVerification(String requestId) throws VonageClientException, VonageResponseParseException { 261 return this.control.execute(new ControlRequest(requestId, VerifyControlCommand.TRIGGER_NEXT_EVENT)); 262 } 263 264 /** 265 * Cancel a current verification request. 266 * 267 * @param requestId The requestId of the ongoing verification request. 268 * 269 * @return A {@link ControlResponse} representing the response from the API. 270 * 271 * @throws VonageClientException if there was a problem with the Vonage request or response objects. 272 * @throws VonageResponseParseException if the response from the API could not be parsed. 273 */ 274 public ControlResponse cancelVerification(String requestId) throws VonageClientException, VonageResponseParseException { 275 return this.control.execute(new ControlRequest(requestId, VerifyControlCommand.CANCEL)); 276 } 277 278 /** 279 * Send a PSD2 compliant payment token to a user for payment authorization 280 * 281 * @param number Telephone number to verify, in <a href="https://en.wikipedia.org/wiki/E.164">E.164</a> format 282 * @param amount payment amount 283 * @param payee name of the person the payment is for. Name will be included in the message 284 * 285 * @return A {@link VerifyResponse} representing the response from the API. 286 * 287 * @throws VonageClientException if there was a problem with the Vonage request or response objects. 288 * @throws VonageResponseParseException if the response from the API could not be parsed. 289 * 290 * @since 5.5.0 291 */ 292 public VerifyResponse psd2Verify(String number, Double amount, String payee) throws VonageClientException, VonageResponseParseException { 293 return this.psd2.psd2Verify(number, amount, payee); 294 } 295 296 /** 297 * Send a PSD2 compliant payment token to a user for payment authorization with a pin verification workflow 298 * 299 * @param number telephone number to verify, in <a href="https://en.wikipedia.org/wiki/E.164">E.164</a> format 300 * @param amount payment amount 301 * @param payee name of the person the payment is for. Name will be included in the message 302 * @param workflow <a href="https://developer.nexmo.com/verify/guides/workflows-and-events">workflow</a> 303 * to use for sending verification pin 304 * 305 * @return A {@link VerifyResponse} representing the response from the API. 306 * 307 * @throws VonageClientException if there was a problem with the Vonage request or response objects. 308 * @throws VonageResponseParseException if the response from the API could not be parsed. 309 * 310 * @since 5.5.0 311 */ 312 public VerifyResponse psd2Verify(String number, Double amount, String payee, Psd2Request.Workflow workflow) 313 throws VonageClientException, VonageResponseParseException { 314 return this.psd2.psd2Verify(number, amount, payee, workflow); 315 } 316 317 /** 318 * Send a PSD2 verification request to a phone number with optional parameters 319 * 320 * @param psd2Request request to to send PSD2 verification to a phone. 321 * 322 * @return A VerifyResponse representing the response from the API. 323 * 324 * @throws VonageClientException if there was a problem with the Vonage request or response objects. 325 * @throws VonageResponseParseException if the response from the API could not be parsed. 326 * 327 * @since 5.5.0 328 */ 329 public VerifyResponse psd2Verify(Psd2Request psd2Request) throws VonageClientException, VonageResponseParseException { 330 return this.psd2.psd2Verify(psd2Request); 331 } 332 333 334}