BATM-6033 Add API allowing to approve/override a deposit transaction (#…

…913)

gradle.properties

@@ -1,6 +1,6 @@
 # buildscript - project id
 projectGroup=com.generalbytes.batm.public
-projectVersion=1.6.0
+projectVersion=1.6.1
 
 # buildscript - common dependency versions
 bitrafaelVersion=1.0.44

server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/IDepositPreparation.java

@@ -0,0 +1,63 @@
+/*************************************************************************************
+ * Copyright (C) 2014-2024 GENERAL BYTES s.r.o. All rights reserved.
+ *
+ * This software may be distributed and modified under the terms of the GNU
+ * General Public License version 2 (GPL2) as published by the Free Software
+ * Foundation and appearing in the file GPL2.TXT included in the packaging of
+ * this file. Please note that GPL2 Section 2[b] requires that all works based
+ * on this software must also be made publicly available under the terms of
+ * the GPL2 ("Copyleft").
+ *
+ * Contact information
+ * -------------------
+ *
+ * GENERAL BYTES s.r.o.
+ * Web      :  http://www.generalbytes.com
+ *
+ ************************************************************************************/
+
+package com.generalbytes.batm.server.extensions;
+
+import java.math.BigDecimal;
+
+/**
+ * Represents a deposit preparation made by a customer before the deposit is submitted by the customer.
+ */
+public interface IDepositPreparation {
+
+    /**
+     * Serial number of the GB Safe where the deposit was made.
+     */
+    String getSafeSerialNumber();
+
+    /**
+     * Deposit code used to identify the deposit. Equals to the RID of the order transaction.
+     */
+    String getDepositCode();
+
+    /**
+     * Local transaction ID of the expected deposit transaction. Generated by GB Safe when preparing deposit.
+     */
+    String getLocalTransactionId();
+
+    /**
+     * Amount of cash deposited. Can be overridden by an extension.
+     */
+    BigDecimal getCashAmount();
+
+    /**
+     * Fiat currency of the cash deposited.
+     */
+    String getCashCurrency();
+
+    /**
+     * Identity of the customer who made the deposit.
+     */
+    IIdentity getIdentity();
+
+    /**
+     * Error message in case of error.
+     */
+    String getErrorMessage();
+
+}

server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/IDepositRequest.java

@@ -0,0 +1,67 @@
+/*************************************************************************************
+ * Copyright (C) 2014-2024 GENERAL BYTES s.r.o. All rights reserved.
+ *
+ * This software may be distributed and modified under the terms of the GNU
+ * General Public License version 2 (GPL2) as published by the Free Software
+ * Foundation and appearing in the file GPL2.TXT included in the packaging of
+ * this file. Please note that GPL2 Section 2[b] requires that all works based
+ * on this software must also be made publicly available under the terms of
+ * the GPL2 ("Copyleft").
+ *
+ * Contact information
+ * -------------------
+ *
+ * GENERAL BYTES s.r.o.
+ * Web      :  http://www.generalbytes.com
+ *
+ ************************************************************************************/
+package com.generalbytes.batm.server.extensions;
+
+import java.math.BigDecimal;
+
+/**
+ * Represents a deposit request submitted by a customer.
+ */
+public interface IDepositRequest {
+
+    /**
+     * Serial number of the GB Safe where the deposit was made.
+     */
+    String getSafeSerialNumber();
+
+    /**
+     * Deposit code used to identify the deposit. Equals to the RID of the order transaction.
+     */
+    String getDepositCode();
+
+    /**
+     * Local transaction ID of the deposit transaction. Generated by GB Safe when preparing deposit.
+     */
+    String getLocalTransactionId();
+
+    /**
+     * Remote transaction ID of the deposit transaction.
+     */
+    String getRemoteTransactionId();
+
+    /**
+     * Amount of cash deposited. Can be overridden by an extension.
+     */
+    BigDecimal getCashAmount();
+
+    /**
+     * Fiat currency of the cash deposited.
+     */
+    String getCashCurrency();
+
+    /**
+     * Identity of the customer who made the deposit.
+     */
+    IIdentity getIdentity();
+
+    /**
+     * Error message in case of error.
+     */
+    String getErrorMessage();
+
+}

server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/ITransactionListener.java

@@ -107,7 +107,67 @@ default Map<String,String> onTransactionUpdated(ITransactionDetails transactionD
     default void receiptSent(IReceiptDetails receiptDetails) {
     }
 
+    /**
+     * Callback method that is called by server when a deposit transaction is created on server
+     * Returned value is a map of keys and values that will be stored in the database and available for later use in ticket template
+     *
+     * @param depositDetails {@link IDepositDetails}
+     * @return map containing custom data related to the deposit
+     */
     default Map<String, String> onDepositCreated(IDepositDetails depositDetails) {
         return null;
     }
+
+    /**
+     * Allows to approve or deny deposit preparation. Called after person inserts deposit code but before inserting money into GB Safe.
+     * When returned {@code false}, provided error message via {@link IDepositPreparation#getErrorMessage()} is displayed to user.
+     *
+     * @return result of the approval
+     */
+    default boolean isDepositPreparationApproved(IDepositPreparation preparation) {
+        return true;
+    }
+
+    /**
+     * Allows the operator to override following values in {@link IDepositPreparation}.
+     * <ul>
+     *     <li>cashAmount</li> - cannot be higher than the provided amount, if yes will be reduced back to the provided amount
+     *     <li>errorMessage</li>
+     * </ul>
+     * The method is called right before {@link ITransactionListener#isDepositPreparationApproved(IDepositPreparation)},
+     * this allows to override values in preparation before the approval check.
+     *
+     * @param preparation The deposit preparation data
+     * @return {@link IDepositPreparation} that may contain modified data from an extension
+     */
+    default IDepositPreparation overrideDepositPreparation(IDepositPreparation preparation) {
+        return preparation;
+    }
+
+    /**
+     * Allows to approve or deny a deposit request. Called by server before a deposit transaction is created.
+     * When returned {@code false}, provided error message via {@link IDepositRequest#getErrorMessage()} is displayed to user
+     * and the transaction will be created in an ERROR status.
+     *
+     * @return result of the approval
+     */
+    default boolean isTransactionApproved(IDepositRequest depositRequest) {
+        return true;
+    }
+
+    /**
+     * Allows the operator to override following values in {@link IDepositRequest}.
+     * <ul>
+     *     <li>cashAmount</li> - cannot be higher than the provided amount, if yes will be reduced back to the provided amount
+     *     <li>errorMessage</li>
+     * </ul>
+     * This method is called for both BUY and SELL transactions.
+     *
+     * @param request The transaction request initialized by server
+     * @return {@link ITransactionRequest} that may contain modified transaction request.
+     */
+    default IDepositRequest overrideTransactionRequest(IDepositRequest request) {
+        return request;
+    }
+
 }

server_extensions_api/src/main/java/com/generalbytes/batm/server/extensions/ITransactionRequest.java

@@ -29,6 +29,8 @@ public interface ITransactionRequest {
     int TYPE_BUY_CRYPTO = 0;
     int TYPE_SELL_CRYPTO = 1;
     int TYPE_WITHDRAW_CASH = 2;
+    int TYPE_CASHBACK = 3;
+    int TYPE_ORDER_CRYPTO = 4;
 
     /**
      * Server time of the transaction