001/*
002 *   Copyright 2024 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
018import com.fasterxml.jackson.annotation.JsonValue;
019import java.util.Locale;
020import java.util.Map;
021
022/**
023 * Describes a PSD2 verify request.
024 *
025 * @since 5.5.0
026 */
027public class Psd2Request extends BaseRequest {
028    private final Double amount;
029    private final String payee;
030    private final Workflow workflow;
031
032    private Psd2Request(Builder builder) {
033        super(builder.number, builder.length, builder.locale, builder.country, builder.pinExpiry, builder.nextEventWait);
034        if ((payee = builder.payee) == null || payee.isEmpty() || payee.length() > 18) {
035            throw new IllegalArgumentException("Payee is required and cannot exceed 18 characters.");
036        }
037        workflow = builder.workflow;
038        amount = builder.amount;
039    }
040
041    /**
042     * @return The decimal amount of the payment to be confirmed, in Euros.
043     */
044    public Double getAmount() {
045        return amount;
046    }
047
048    /**
049     * @return An alphanumeric string to indicate to the user the name of the recipient that they are confirming a payment to.
050     */
051    public String getPayee() {
052        return payee;
053    }
054
055    /**
056     * @return The predefined sequence of SMS and TTS (Text To Speech) actions to use
057     * in order to convey the PIN to your user.
058     */
059    public Workflow getWorkflow() {
060        return workflow;
061    }
062
063    /**
064     * Enumeration representing different verification workflows. See the
065     * <a href="https://developer.nexmo.com/verify/guides/workflows-and-events">Workflow and Events documentation</a>
066     * for more details.
067     */
068    public enum Workflow {
069        /**
070         * The default workflow.
071         */
072        SMS_TTS_TTS(1),
073        SMS_SMS_TTS(2),
074        TTS_TTS(3),
075        SMS_SMS(4),
076        SMS_TTS(5),
077        SMS(6),
078        TTS(7);
079
080        private final int id;
081
082        Workflow(int id) {
083            this.id = id;
084        }
085
086        @JsonValue
087        public int getId() {
088            return id;
089        }
090    }
091
092    /**
093     * Entry point for constructing an instance of this class.
094     *
095     * @return A new Builder.
096     * @since 7.9.0
097     */
098    public static Builder builder() {
099        return new Builder();
100    }
101
102    /**
103     * Entry point for constructing an instance of this class, with the required parameters.
104     *
105     * @param number The recipient's phone number in <a href="https://en.wikipedia.org/wiki/E.164">E.164</a>
106     *               format.
107     * @param amount The decimal amount of the payment to be confirmed, in Euros.
108     * @param payee  An alphanumeric string to indicate to the user the name of the recipient that they
109     *               are confirming a payment to.
110     * @return A new Builder to start building.
111     */
112    public static Builder builder(String number, Double amount, String payee) {
113        return new Builder(number, amount, payee);
114    }
115
116    @Override
117    public String toString() {
118        return "Psd2Request{" +
119                super.toString() +
120                ", amount=" + amount +
121                ", payee='" + payee + '\'' +
122                ", workflow=" + workflow +
123                '}';
124    }
125
126    @Override
127    public Map<String, String> makeParams() {
128        Map<String, String> params = super.makeParams();
129        params.put("payee", payee);
130        params.put("amount", Double.toString(amount));
131        if (workflow != null) {
132            params.put("workflow_id", Integer.toString(workflow.id));
133        }
134        return params;
135    }
136
137    public static class Builder {
138        private Double amount;
139        private String payee, number, country;
140        private Workflow workflow;
141        private Locale locale;
142        private Integer length,  pinExpiry, nextEventWait;
143
144        /**
145         * @param number The recipient's phone number in <a href="https://en.wikipedia.org/wiki/E.164">E.164</a>
146         *               format.
147         * @param amount The decimal amount of the payment to be confirmed, in Euros.
148         * @param payee  An alphanumeric string to indicate to the user the name of the recipient that they
149         *               are confirming a payment to.
150         */
151        public Builder(String number, Double amount, String payee) {
152            this.number = number;
153            this.payee = payee;
154            this.amount = amount;
155        }
156
157        private Builder() {
158        }
159
160        /**
161         * (REQUIRED)
162         * @param payee Username of the payment recipient.
163         *
164         * @return This builder.
165         *
166         * @since 7.9.0
167         */
168        public Builder payee(String payee) {
169            this.payee = payee;
170            return this;
171        }
172
173        /**
174         * (REQUIRED)
175         * @param number The recipient's phone number in E.164 format.
176         *
177         * @return This builder.
178         *
179         * @since 7.9.0
180         */
181        public Builder number(String number) {
182            this.number = number;
183            return this;
184        }
185
186        /**
187         * (REQUIRED)
188         * @param amount The decimal amount of the payment to be confirmed, in Euros.
189         *
190         * @return This builder.
191         *
192         * @since 7.9.0
193         */
194        public Builder amount(double amount) {
195            this.amount = amount;
196            return this;
197        }
198
199        /**
200         * @param workflow Selects the predefined sequence of SMS and TTS (Text To Speech) actions to use
201         *                 in order to convey the PIN to your user. For example, an id of 1 identifies the
202         *                 workflow SMS - TTS - TTS. For a list of all workflows and their associated ids,
203         *                 please visit the
204         *                 <a href="https://developer.nexmo.com/verify/guides/workflows-and-events">developer portal.</a>
205         * @return This builder.
206         */
207        public Builder workflow(Workflow workflow){
208            this.workflow = workflow;
209            return this;
210        }
211
212        /**
213         * @param locale (optional) Override the default locale used for verification. By default the locale is determined
214         *        from the country code included in {@code number}
215         * @return This builder.
216         */
217        public Builder locale(Locale locale) {
218            this.locale = locale;
219            return this;
220        }
221
222        /**
223         * @param length (optional) The length of the verification code to be sent to the user. Must be either 4 or 6. Use
224         *               -1 to use the default value.
225         * @return This builder.
226         */
227        public Builder length(Integer length) {
228            this.length = length;
229            return this;
230        }
231
232        /**
233         * @param pinExpiry (optional) the PIN validity time from generation, in seconds. Default is 300 seconds
234         * @return This builder.
235         */
236        public Builder pinExpiry(Integer pinExpiry) {
237            this.pinExpiry = pinExpiry;
238            return this;
239        }
240
241        /**
242         * @param nextEventWait (optional) the wait time between attempts to deliver the PIN. A number between 600-900.
243         * @return This builder.
244         */
245        public Builder nextEventWait(Integer nextEventWait) {
246            this.nextEventWait = nextEventWait;
247            return this;
248        }
249
250        /**
251         * The country for the destination phone number.
252         * <p>
253         * If you wish to used localised number formats or you are not sure if number is correctly formatted, set this to a
254         * two-character country code. For example, GB, US. Verify will work out the international phone number for you.
255         * </p>
256         *
257         * @param country  a String containing a 2-character country code
258         * @return This builder.
259         */
260        public Builder country(String country) {
261            this.country = country;
262            return this;
263        }
264
265        public Psd2Request build() {
266            return new Psd2Request(this);
267        }
268
269    }
270}