diff --git a/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/Account.java b/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/Account.java index 21c1a48..4654287 100644 --- a/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/Account.java +++ b/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/Account.java @@ -6,23 +6,45 @@ import org.json.JSONObject; +/** + * The Account class is a wrapper for the Account module of the Chimoney API. + * + */ public class Account extends Base { + /** + * Constructs a new Account object with the specified Chimoney instance. + * + * @param chimoney the Chimoney instance associated with the account + */ public Account(Chimoney chimoney) { super(chimoney); } + /** + * Retrieves a list of transactions by issue ID. + * + * @param issueID the issueID of the transaction + * @return a list of transactions + * @throws Exception if an error occurs during the request + */ public List getTransactionsByIssueID(String issueID) throws Exception { - HttpResponse response = handlePOSTRequest("accounts/issue-id-transactions?issueID=" + issueID, - null); - JSONObject jo = parseJSONData(response); - - return jo.getJSONArray("data").toList(); + return getTransactionsByIssueID(issueID, null); } + /** + * Retrieves a list of transactions by issue ID and sub-account. + * + * @param issueID the issue ID of the transactions to retrieve + * @param subAccount the sub-account associated with the transactions + * @return a list of transactions as objects + * @throws Exception if an error occurs during the retrieval process + */ public List getTransactionsByIssueID(String issueID, String subAccount) throws Exception { JSONObject jsonParams = new JSONObject(); - jsonParams.put("subAccount", subAccount); + + if (subAccount != null) + jsonParams.put("subAccount", subAccount); HttpResponse response = handlePOSTRequest("accounts/issue-id-transactions?issueID=" + issueID, jsonParams); @@ -31,22 +53,42 @@ public List getTransactionsByIssueID(String issueID, String subAccount) return jo.getJSONArray("data").toList(); } + /** + * Retrieves the profile information for a user. + * Specify either userID or linkCode. If both are specified, userID will be + * used. + * + * @param userID the ID of the user + * @param linkCode the link code associated with the user + * @return a map containing the profile information + * @throws Exception if an error occurs during the API request + */ public Map getProfile(String userID, String linkCode) throws Exception { - JSONObject jsonParams = new JSONObject(); - jsonParams.put("userID", userID); - jsonParams.put("linkCode", linkCode); - - HttpResponse response = handlePOSTRequest("accounts/public-profile", jsonParams); - JSONObject jo = parseJSONData(response); - - return jo.getJSONObject("data").toMap(); + return getProfile(userID, linkCode, null); } - public Map getProfile(String subAccount, String userID, String linkCode) throws Exception { + /** + * Retrieves the profile information for a user and sub-account. + * Specify either userID or linkCode. If both are specified, userID will be + * used. + * + * @param userID the ID of the user + * @param linkCode the link code associated with the user + * @param subAccount the sub-account associated with the user + * @return a map containing the profile information + * @throws Exception if there is an error retrieving the profile + */ + public Map getProfile(String userID, String linkCode, String subAccount) throws Exception { JSONObject jsonParams = new JSONObject(); - jsonParams.put("subAccount", subAccount); - jsonParams.put("userID", userID); - jsonParams.put("linkCode", linkCode); + if (userID != null) + jsonParams.put("userID", userID); + else if (linkCode != null) + jsonParams.put("linkCode", linkCode); + else + throw new ChimoneyException("Either userID or linkCode must be specified."); + + if (subAccount != null) + jsonParams.put("subAccount", subAccount); HttpResponse response = handlePOSTRequest("accounts/public-profile", jsonParams); JSONObject jo = parseJSONData(response); @@ -54,13 +96,23 @@ public Map getProfile(String subAccount, String userID, String l return jo.getJSONObject("data").toMap(); } + /** + * Retrieves a list of transactions for this account. + * + * @return a list of transactions for this account + * @throws Exception if an error occurs while retrieving the transactions + */ public List getTransactionsByAccount() throws Exception { - HttpResponse response = handlePOSTRequest("accounts/transactions", null); - JSONObject jo = parseJSONData(response); - - return jo.getJSONArray("data").toList(); + return getTransactionsByAccount(null); } + /** + * Retrieves a list of transactions for a specific sub-account. + * + * @param subAccount the subAccount for which to retrieve transactions + * @return a list of transactions as objects + * @throws Exception if an error occurs during the request + */ public List getTransactionsByAccount(String subAccount) throws Exception { JSONObject jsonParams = new JSONObject(); jsonParams.put("subAccount", subAccount); @@ -71,16 +123,30 @@ public List getTransactionsByAccount(String subAccount) throws Exception return jo.getJSONArray("data").toList(); } + /** + * Retrieves a transaction from this account by the transaction ID. + * + * @param id The ID of the transaction to retrieve. + * @return A map containing the transaction data. + * @throws Exception If an error occurs while retrieving the transaction. + */ public Map getTransaction(String id) throws Exception { - HttpResponse response = handlePOSTRequest("accounts/transaction?id=" + id, null); - JSONObject jo = parseJSONData(response); - - return jo.getJSONObject("data").toMap(); + return getTransaction(id, null); } + /** + * Retrieves a transaction from this account by the transaction ID. + * + * @param id The ID of the transaction to retrieve. + * @param subAccount The sub-account associated with the transaction. + * @return A map containing the transaction data. + * @throws Exception If an error occurs while retrieving the transaction. + */ public Map getTransaction(String id, String subAccount) throws Exception { JSONObject jsonParams = new JSONObject(); - jsonParams.put("subAccount", subAccount); + + if (subAccount != null) + jsonParams.put("subAccount", subAccount); HttpResponse response = handlePOSTRequest("accounts/transaction?id=" + id, jsonParams); JSONObject jo = parseJSONData(response); @@ -88,36 +154,52 @@ public Map getTransaction(String id, String subAccount) throws E return jo.getJSONObject("data").toMap(); } + /** + * Transfers funds from this account to the specified receiver. + * + * @param receiver the ID of the recipient of the funds + * @param valueInUSD the amount to transfer in USD + * @return a map containing the details of the transfer + * @throws Exception if an error occurs during the transfer + */ public Map accountTransfer(String receiver, int valueInUSD) throws Exception { - JSONObject jsonParams = new JSONObject(); - jsonParams.put("receiver", receiver); - jsonParams.put("valueInUSD", valueInUSD); - - HttpResponse response = handlePOSTRequest("accounts/transfer", jsonParams); - JSONObject jo = parseJSONData(response); - - return jo.getJSONObject("data").toMap(); + return accountTransfer(receiver, valueInUSD, null, null); } - public Map accountTransfer(String receiver, int valueInUSD, String wallet) throws Exception { - JSONObject jsonParams = new JSONObject(); - jsonParams.put("receiver", receiver); - jsonParams.put("valueInUSD", valueInUSD); - jsonParams.put("wallet", wallet); - - HttpResponse response = handlePOSTRequest("accounts/transfer", jsonParams); - JSONObject jo = parseJSONData(response); - - return jo.getJSONObject("data").toMap(); + /** + * Transfers funds from this account to the specified receiver. + * + * @param receiver the ID of the recipient of the funds + * @param valueInUSD the amount to transfer in USD + * @param wallet the wallet type to use for the transfer + * @return a map containing the details of the transfer + * @throws Exception if an error occurs during the transfer + */ + public Map accountTransfer(String receiver, int valueInUSD, Wallet.Types wallet) throws Exception { + return accountTransfer(receiver, valueInUSD, wallet, null); } - public Map accountTransfer(String receiver, int valueInUSD, String wallet, String subAccount) + /** + * Transfers funds from this account to the specified receiver. + * + * @param receiver the ID of the recipient of the funds + * @param valueInUSD the amount to transfer in USD + * @param wallet the wallet type to use for the transfer + * @param subAccount the sub-account to use for the transfer + * @return a map containing the response data from the transfer operation + * @throws Exception if an error occurs during the transfer + */ + public Map accountTransfer(String receiver, int valueInUSD, Wallet.Types wallet, String subAccount) throws Exception { JSONObject jsonParams = new JSONObject(); jsonParams.put("receiver", receiver); jsonParams.put("valueInUSD", valueInUSD); - jsonParams.put("wallet", wallet); - jsonParams.put("subAccount", subAccount); + + if (wallet != null) + jsonParams.put("wallet", wallet.toString()); + + if (subAccount != null) + jsonParams.put("subAccount", subAccount); HttpResponse response = handlePOSTRequest("accounts/transfer", jsonParams); JSONObject jo = parseJSONData(response); @@ -125,18 +207,30 @@ public Map accountTransfer(String receiver, int valueInUSD, Stri return jo.getJSONObject("data").toMap(); } - public Map deleteUnpaidTransaction(String chiRef) - throws Exception { - HttpResponse response = handleDELETERequest("accounts/delete-unpaid-transaction?chiRef=" + chiRef); - JSONObject jo = parseJSONData(response); - - return jo.getJSONObject("data").toMap(); + /** + * Deletes an unpaid transaction with the specified chiRef. + * + * @param chiRef the reference of the transaction to be deleted + * @return a map containing the result of the deletion operation + * @throws Exception if an error occurs during the deletion process + */ + public Map deleteUnpaidTransaction(String chiRef) throws Exception { + return deleteUnpaidTransaction(chiRef, null); } + /** + * Deletes an unpaid transaction with the specified chiRef. + * + * @param chiRef the reference of the transaction to be deleted + * @param subAccount the subAccount associated with the transaction + * @return a map containing the data of the deleted transaction + * @throws Exception if an error occurs during the deletion process + */ public Map deleteUnpaidTransaction(String chiRef, String subAccount) throws Exception { + String ext = subAccount != null ? "&subAccount=" + subAccount : ""; HttpResponse response = handleDELETERequest( - "accounts/delete-unpaid-transaction?chiRef=" + chiRef + "&subAccount=" + subAccount); + "accounts/delete-unpaid-transaction?chiRef=" + chiRef + ext); JSONObject jo = parseJSONData(response); return jo.getJSONObject("data").toMap(); diff --git a/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/Base.java b/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/Base.java index 726882b..0628281 100644 --- a/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/Base.java +++ b/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/Base.java @@ -1,6 +1,5 @@ package io.chimoney.chimoney; -import java.io.IOException; import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; @@ -45,7 +44,8 @@ JSONObject parseJSONData(HttpResponse response) throws ChimoneyException JSONObject obj = new JSONObject(response.body()); if (obj.has("error")) { - throw new ChimoneyException(obj.getString("error")); + String msg = "Error code " + response.statusCode() + " - " + obj.getString("error"); + throw new ChimoneyException(msg); } return obj; diff --git a/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/Beneficiary.java b/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/Beneficiary.java index f64aba8..0a9c17c 100644 --- a/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/Beneficiary.java +++ b/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/Beneficiary.java @@ -5,11 +5,31 @@ import org.json.JSONObject; +/** + * The Beneficiary class is a wrapper for the Beneficiary module of the Chimoney + * API. + * + */ public class Beneficiary extends Base { + + /** + * Constructs a new Beneficiary object with the specified Chimoney instance. + * + * @param chimoney the Chimoney instance associated with the beneficiary + */ public Beneficiary(Chimoney chimoney) { super(chimoney); } + /** + * Creates a beneficiary with the given user ID and beneficiary data. + * + * @param ownerID The ID of the user/sub-account. + * @param beneficiaryData The data of the beneficiary. + * @return A map containing the beneficiary data. Check the Chimoney API + * documentation for more information. + * @throws Exception If an error occurs during the creation of the beneficiary. + */ public Map createBeneficiary(String ownerID, Map beneficiaryData) throws Exception { JSONObject paramsJson = new JSONObject(); paramsJson.put("owner", ownerID); diff --git a/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/Chimoney.java b/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/Chimoney.java index 4ecda0a..dbf88ad 100644 --- a/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/Chimoney.java +++ b/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/Chimoney.java @@ -3,7 +3,8 @@ import io.github.cdimascio.dotenv.Dotenv; /** - * Chimoney + * The Chimoney class represents a client for the Chimoney API. + * */ public class Chimoney { private final String PRODUCTION_BASE_URL = "https://api.chimoney.io/v0.2/"; @@ -12,16 +13,44 @@ public class Chimoney { private String API_KEY; private String baseURL; + /** + * Constructs a new Chimoney object with the API key from the .env file. + * + *

+ * Place the .env file in the root directory of your project (the directory that + * contains the top-level package directory). + *

+ * + */ public Chimoney() { this.baseURL = PRODUCTION_BASE_URL; this.API_KEY = Dotenv.load().get("CHIMONEY_API_KEY"); } + /** + * Constructs a new Chimoney object with the given API key. + * + * @param API_KEY The API key to use for requests. + */ public Chimoney(String API_KEY) { this.baseURL = PRODUCTION_BASE_URL; this.API_KEY = API_KEY; } + /** + * Constructs a new Chimoney object in sandbox mode with the API key from the + * .env file. + * + *

+ * Sandbox mode is a development environment. Check the Chimoney API + * documentation for more information. + *

+ *

+ * Place the .env file in the root directory of your project (the directory that + * contains the top-level package directory). + *

+ * + */ public static Chimoney withSandbox() { Chimoney chimoney = new Chimoney(); chimoney.baseURL = chimoney.SANDBOX_BASE_URL; @@ -29,6 +58,16 @@ public static Chimoney withSandbox() { return chimoney; } + /** + * Constructs a new Chimoney object in sandbox mode with the given API key. + * + *

+ * Sandbox mode is a development environment. Check the Chimoney API + * documentation for more information. + *

+ * + * @param API_KEY The API key to use for requests. + */ public static Chimoney withSandbox(String API_KEY) { Chimoney chimoney = new Chimoney(API_KEY); chimoney.baseURL = chimoney.SANDBOX_BASE_URL; @@ -36,6 +75,11 @@ public static Chimoney withSandbox(String API_KEY) { return chimoney; } + /** + * Returns the base URL of the API. + * + * @return the base URL as a String. + */ public String getBaseURL() { return this.baseURL; } diff --git a/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/ChimoneyException.java b/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/ChimoneyException.java index dac1729..1ac0ffe 100644 --- a/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/ChimoneyException.java +++ b/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/ChimoneyException.java @@ -1,12 +1,25 @@ package io.chimoney.chimoney; +/** + * This class represents an exception specific to the Chimoney application. + */ public class ChimoneyException extends Exception { private String msg; + /** + * Constructs a new ChimoneyException with the specified error message. + * + * @param msg the error message + */ ChimoneyException(String msg) { this.msg = msg; } + /** + * Returns a string representation of this ChimoneyException. + * + * @return the string representation of this ChimoneyException + */ public String toString() { return "ChimoneyException: " + msg; } diff --git a/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/Info.java b/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/Info.java index 9a1de1f..3c7c65f 100644 --- a/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/Info.java +++ b/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/Info.java @@ -7,11 +7,28 @@ import org.json.JSONArray; import org.json.JSONObject; +/** + * The Info class is a wrapper for the Info module of the Chimoney + * API. + * + */ public class Info extends Base { + + /** + * Constructs a new Info object with the specified Chimoney instance. + * + * @param chimoney the Chimoney instance associated with this Info object + */ public Info(Chimoney chimoney) { super(chimoney); } + /** + * Retrieves a list of countries that support airtime. + * + * @return A list of countries. + * @throws Exception If an error occurs while making the API request. + */ public List getAirtimeCountries() throws Exception { HttpResponse response = handleGETRequest("info/airtime-countries"); JSONObject jo = parseJSONData(response); @@ -19,14 +36,39 @@ public List getAirtimeCountries() throws Exception { return jo.getJSONArray("data").toList(); } + /** + * Retrieves the information of all assets. + * + * @return A map containing the assets information. + * @throws Exception If an error occurs while retrieving the assets information. + */ public Map getAssets() throws Exception { - HttpResponse response = handleGETRequest("info/assets"); + return getAssets(null); + } + + /** + * Retrieves the assets for a specific country. + * + * @param countryCode The country code for which to retrieve the assets. + * @return A map containing the assets information. + * @throws Exception If an error occurs while retrieving the assets. + */ + public Map getAssets(String countryCode) throws Exception { + String queryString = countryCode != null ? "?countryCode=" + countryCode : ""; + HttpResponse response = handleGETRequest("info/assets" + queryString); JSONObject jo = parseJSONData(response); return jo.getJSONObject("data").toMap(); } + /** + * Retrieves a list of supported banks and bank codes for a specific country. + * + * @param countryCode the country code for which to retrieve the banks + * @return a list of banks and bank codes + * @throws Exception if an error occurs during the API request or JSON parsing + */ public List getBanks(String countryCode) throws Exception { HttpResponse response = handleGETRequest("info/country-banks?countryCode=" + countryCode); JSONObject jo = parseJSONData(response); @@ -34,6 +76,14 @@ public List getBanks(String countryCode) throws Exception { return jo.getJSONArray("data").toList(); } + /** + * Retrieves a list of bank branches and branch codes based on the specified + * bank code. + * + * @param bankCode the code of the bank + * @return a list of bank branches and branch codes + * @throws Exception if an error occurs during the API request + */ public List getBankBranches(String bankCode) throws Exception { HttpResponse response = handleGETRequest("info/bank-branches?bankCode=" + bankCode); JSONObject jo = parseJSONData(response); @@ -41,6 +91,13 @@ public List getBankBranches(String bankCode) throws Exception { return jo.getJSONArray("data").toList(); } + /** + * Retrieves the exchange rates against the USD. + * + * @return A map containing the exchange rates. + * @throws Exception If an error occurs while making the API request or parsing + * the response. + */ public Map getExchangeRates() throws Exception { HttpResponse response = handleGETRequest("info/exchange-rates"); JSONObject jo = parseJSONData(response); @@ -48,6 +105,16 @@ public Map getExchangeRates() throws Exception { return jo.getJSONObject("data").toMap(); } + /** + * Converts the specified amount in the given currency to USD. + * + * @param currency The currency to convert from. Check the + * Chimoney API documentation for currency + * symbols. + * @param amountInOriginCurrency The amount in the origin currency to convert. + * @return A map containing the converted amount in USD. + * @throws Exception If an error occurs during the conversion process. + */ public Map convertToUSD(String currency, int amountInOriginCurrency) throws Exception { HttpResponse response = handleGETRequest( "info/local-amount-in-usd?originCurrency=" + currency + "&amountInOriginCurrency=" @@ -60,7 +127,8 @@ public Map convertToUSD(String currency, int amountInOriginCurre /** * Converts the specified amount in USD to the specified currency. * - * @param currency The destination currency to convert to. + * @param currency The destination currency to convert to. Check the Chimoney + * API documentation for currency symbols. * @param amountInUSD The amount in USD to convert. * @return A map containing the converted amount in the destination currency. * @throws Exception If an error occurs during the conversion process. @@ -73,6 +141,13 @@ public Map convertFromUSD(String currency, int amountInUSD) thro return jo.getJSONObject("data").toMap(); } + /** + * Retrieves a list of all supported mobile money codes. + * + * @return A list of mobile money codes. + * @throws Exception If an error occurs while making the HTTP request or parsing + * the JSON data. + */ public List getMobileMoneyCodes() throws Exception { HttpResponse response = handleGETRequest("info/mobile-money-codes"); JSONObject jo = parseJSONData(response); @@ -80,6 +155,21 @@ public List getMobileMoneyCodes() throws Exception { return jo.getJSONArray("data").toList(); } + /** + * Verifies the bank account number for a given country code, bank code, and + * account number. + * + *

+ * Use this function when you want to verify a single bank + * account number. Otherwise, use {@link #verifyBankAccountNumbers(Map)} + *

+ * + * @param countryCode The country code of the bank account. + * @param bankCode The bank code of the bank account. + * @param accountNumber The account number of the bank account. + * @return A list containing only the verified bank account number. + * @throws Exception If an error occurs during the verification process. + */ public List verifyBankAccountNumber(String countryCode, String bankCode, String accountNumber) throws Exception { JSONObject paramsJson = new JSONObject(); @@ -100,6 +190,29 @@ public List verifyBankAccountNumber(String countryCode, String bankCode, return jObj.getJSONArray("data").toList(); } + /** + * Verifies bank account numbers based on the provided map of country codes, + * bank codes, and account numbers. + * + *

+ * Use {@code Map.of()} to create the map. The keys of the map should be + * countryCode, bankCode and accountNumber. The values + * should be {@code String[]} of the same length. + *

+ * + *

+ * Use this function when you want to verify multiple bank account numbers. + * Otherwise, use {@link #verifyBankAccountNumber} + *

+ * + * @param map The map containing arrays of country codes, bank codes, and + * account numbers. + * @return A list of verified bank account numbers. + * @throws IllegalArgumentException If the arrays in the map are not of the same + * size. + * @throws Exception If an error occurs during the verification + * process. + */ public List verifyBankAccountNumbers(Map map) throws Exception { if ((map.get("countryCode").length != map.get("bankCode").length) diff --git a/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/Payments.java b/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/Payments.java index ca3082b..2329061 100644 --- a/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/Payments.java +++ b/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/Payments.java @@ -1,51 +1,83 @@ package io.chimoney.chimoney; import java.net.http.HttpResponse; -import java.util.List; import java.util.Map; import org.json.JSONException; import org.json.JSONObject; +/** + * The Payments class is a wrapper for the Payments module of the Chimoney + * API. + * + */ public class Payments extends Base { + + /** + * Represents the status of a payment. + * Possible values are: failed, expired, fraud. + */ enum Status { failed, expired, fraud } + /** + * Constructs a new Payments object with the specified Chimoney instance. + * + * @param chimoney the Chimoney instance associated with this Payments object + */ public Payments(Chimoney chimoney) { super(chimoney); } + /** + * Initiates a payment with the specified payer email and value in USD. + * + * @param payerEmail the email address of the payer + * @param valueInUSD the value of the payment in USD + * @return a map containing the payment details + * @throws Exception if an error occurs during payment initiation + */ public Map initiatePayment(String payerEmail, int valueInUSD) throws Exception { - JSONObject paramsJson = new JSONObject(); - paramsJson.put("payerEmail", payerEmail); - paramsJson.put("valueInUSD", valueInUSD); - - HttpResponse response = handlePOSTRequest("payment/initiate", paramsJson); - JSONObject jo = parseJSONData(response); - - return jo.getJSONObject("data").toMap(); + return initiatePayment(payerEmail, valueInUSD, null, null); } + /** + * Initiates a payment with the specified payer email, value in USD, and + * sub-account. + * + * @param payerEmail the email address of the payer + * @param valueInUSD the value of the payment in USD + * @param subAccount the sub-account for the payment + * @return a map containing the payment details + * @throws Exception if an error occurs during payment initiation + */ public Map initiatePayment(String payerEmail, int valueInUSD, String subAccount) throws Exception { - JSONObject paramsJson = new JSONObject(); - paramsJson.put("payerEmail", payerEmail); - paramsJson.put("valueInUSD", valueInUSD); - paramsJson.put("subAccount", subAccount); - - HttpResponse response = handlePOSTRequest("payment/initiate", paramsJson); - JSONObject jo = parseJSONData(response); - - return jo.getJSONObject("data").toMap(); + return initiatePayment(payerEmail, valueInUSD, subAccount, null); } + /** + * Initiates a payment with the given payer email, value in USD, sub-account, + * and metadata. + * + * @param payerEmail the email address of the payer + * @param valueInUSD the value of the payment in USD + * @param subAccount the sub-account for the payment + * @param meta the metadata associated with the payment + * @return a map containing the payment details + * @throws Exception if an error occurs during the payment initiation process + */ public Map initiatePayment(String payerEmail, int valueInUSD, String subAccount, Map meta) throws Exception { JSONObject paramsJson = new JSONObject(); paramsJson.put("payerEmail", payerEmail); paramsJson.put("valueInUSD", valueInUSD); - paramsJson.put("subAccount", subAccount); - paramsJson.put("meta", new JSONObject(meta)); + + if (subAccount != null) + paramsJson.put("subAccount", subAccount); + + if (meta != null) + paramsJson.put("meta", new JSONObject(meta)); HttpResponse response = handlePOSTRequest("payment/initiate", paramsJson); JSONObject jo = parseJSONData(response); @@ -53,40 +85,60 @@ public Map initiatePayment(String payerEmail, int valueInUSD, St return jo.getJSONObject("data").toMap(); } + /** + * Initiates a payment with the specified payer email, currency, and amount. + * + * @param payerEmail the email address of the payer + * @param currency the currency of the payment. Check the Chimoney API + * documentation for supported currencies. + * @param amount the amount of the payment + * @return a map containing the payment details + * @throws Exception if an error occurs during payment initiation + */ public Map initiatePayment(String payerEmail, String currency, int amount) throws Exception { - JSONObject paramsJson = new JSONObject(); - paramsJson.put("payerEmail", payerEmail); - paramsJson.put("currency", currency); - paramsJson.put("amount", amount); - - HttpResponse response = handlePOSTRequest("payment/initiate", paramsJson); - JSONObject jo = parseJSONData(response); - - return jo.getJSONObject("data").toMap(); + return initiatePayment(payerEmail, currency, amount, null, null); } + /** + * Initiates a payment with the specified payer email, currency, and amount. + * + * @param payerEmail the email address of the payer + * @param currency the currency of the payment. Check the Chimoney API + * documentation for supported currencies. + * @param amount the amount of the payment + * @param subAccount the sub-account for the payment + * @return a map containing the payment details + * @throws Exception if an error occurs during payment initiation + */ public Map initiatePayment(String payerEmail, String currency, int amount, String subAccount) throws Exception { - JSONObject paramsJson = new JSONObject(); - paramsJson.put("payerEmail", payerEmail); - paramsJson.put("currency", currency); - paramsJson.put("amount", amount); - paramsJson.put("subAccount", subAccount); - - HttpResponse response = handlePOSTRequest("payment/initiate", paramsJson); - JSONObject jo = parseJSONData(response); - - return jo.getJSONObject("data").toMap(); + return initiatePayment(payerEmail, currency, amount, subAccount, null); } + /** + * Initiates a payment with the specified payer email, currency, and amount. + * + * @param payerEmail the email address of the payer + * @param currency the currency of the payment. Check the Chimoney API + * documentation for supported currencies. + * @param amount the amount of the payment + * @param subAccount the sub-account for the payment + * @param meta the metadata associated with the payment + * @return a map containing the payment details + * @throws Exception if an error occurs during payment initiation + */ public Map initiatePayment(String payerEmail, String currency, int amount, String subAccount, Map meta) throws Exception { JSONObject paramsJson = new JSONObject(); paramsJson.put("payerEmail", payerEmail); paramsJson.put("currency", currency); paramsJson.put("amount", amount); - paramsJson.put("subAccount", subAccount); - paramsJson.put("meta", new JSONObject(meta)); + + if (subAccount != null) + paramsJson.put("subAccount", subAccount); + + if (meta != null) + paramsJson.put("meta", new JSONObject(meta)); HttpResponse response = handlePOSTRequest("payment/initiate", paramsJson); JSONObject jo = parseJSONData(response); @@ -94,20 +146,31 @@ public Map initiatePayment(String payerEmail, String currency, i return jo.getJSONObject("data").toMap(); } - public List verifyPayment(String id) throws Exception { - JSONObject paramsJson = new JSONObject(); - paramsJson.put("id", id); - - HttpResponse response = handlePOSTRequest("payment/verify", paramsJson); - JSONObject jo = parseJSONData(response); - - return jo.getJSONArray("data").toList(); + /** + * Verifies a payment with the specified ID. + * + * @param id the ID of the payment to verify + * @return a map containing the verified payment information + * @throws Exception if an error occurs during the verification process + */ + public Map verifyPayment(String id) throws Exception { + return verifyPayment(id, null); } + /** + * Verifies a payment with the given ID and sub-account. + * + * @param id the ID of the payment to verify + * @param subAccount the sub-account associated with the payment + * @return a map containing the verified payment information + * @throws Exception if an error occurs during the verification process + */ public Map verifyPayment(String id, String subAccount) throws Exception { JSONObject paramsJson = new JSONObject(); paramsJson.put("id", id); - paramsJson.put("subAccount", subAccount); + + if (subAccount != null) + paramsJson.put("subAccount", subAccount); HttpResponse response = handlePOSTRequest("payment/verify", paramsJson); JSONObject jo = parseJSONData(response); @@ -115,25 +178,29 @@ public Map verifyPayment(String id, String subAccount) throws Ex return jo.getJSONObject("data").toMap(); } + /** + * Simulates a card or other status change for a given issue ID, status, and + * sub-account. This method only works in staging. + * + * @param issueID the ID of the issue + * @param status the status of the payment + * @return a map containing the simulated payment data + * @throws Exception if an error occurs during the simulation + */ public Map simulatePayment(String issueID, Status status) throws Exception { - JSONObject paramsJson = new JSONObject(); - Map ret; - - paramsJson.put("issueID", issueID); - paramsJson.put("status", status.toString()); - - HttpResponse response = handlePOSTRequest("payment/simulate", paramsJson); - JSONObject jo = parseJSONData(response); - - try { - ret = jo.getJSONObject("data").toMap(); - } catch (JSONException e) { - ret = jo.toMap(); - } - - return ret; + return simulatePayment(issueID, status, null); } + /** + * Simulates a card or other status change for a given issue ID, status, and + * sub-account. This method only works in staging. + * + * @param issueID the ID of the issue + * @param status the status of the payment + * @param subAccount the sub-account for the payment + * @return a map containing the simulated payment data + * @throws Exception if an error occurs during the simulation + */ public Map simulatePayment(String issueID, Status status, String subAccount) throws Exception { JSONObject paramsJson = new JSONObject(); @@ -141,7 +208,9 @@ public Map simulatePayment(String issueID, Status status, String paramsJson.put("issueID", issueID); paramsJson.put("status", status.toString()); - paramsJson.put("subAccount", subAccount); + + if (subAccount != null) + paramsJson.put("subAccount", subAccount); HttpResponse response = handlePOSTRequest("payment/simulate", paramsJson); JSONObject jo = parseJSONData(response); diff --git a/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/Redeem.java b/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/Redeem.java index d2d8c17..751e1e9 100644 --- a/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/Redeem.java +++ b/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/Redeem.java @@ -6,45 +6,72 @@ import org.json.JSONArray; import org.json.JSONObject; +/** + * The Redeem class is a wrapper for the Redeem module of the Chimoney API. + * + */ public class Redeem extends Base { + + /** + * Constructs a new Redeem object with the specified Chimoney instance. + * + * @param chimoney the Chimoney instance associated with this Redeem object + */ public Redeem(Chimoney chimoney) { super(chimoney); } + /** + * Redeems airtime. + * + * @param chiRef The Chi reference + * @param phoneNumber The phone number to send the airtime to + * @param countryToSend The country to send the airtime to + * @return A map containing the response data + * @throws Exception If an error occurs during the redemption process + */ public Map airtime(String chiRef, String phoneNumber, String countryToSend) throws Exception { - JSONObject params = new JSONObject(); - params.put("chiRef", chiRef); - params.put("phoneNumber", phoneNumber); - params.put("countryToSend", countryToSend); - - HttpResponse response = handlePOSTRequest("redeem/airtime", params); - JSONObject jo = parseJSONData(response); - - return jo.getJSONObject("data").toMap(); + return airtime(chiRef, phoneNumber, countryToSend, null, null); } + /** + * Redeems airtime. + * + * @param chiRef The Chi reference + * @param phoneNumber The phone number to send the airtime to + * @param countryToSend The country to send the airtime to + * @param subAccount The sub-account to use + * @return A map containing the response data + * @throws Exception If an error occurs during the redemption process + */ public Map airtime(String chiRef, String phoneNumber, String countryToSend, String subAccount) throws Exception { - JSONObject params = new JSONObject(); - params.put("chiRef", chiRef); - params.put("phoneNumber", phoneNumber); - params.put("countryToSend", countryToSend); - params.put("subAccount", subAccount); - - HttpResponse response = handlePOSTRequest("redeem/airtime", params); - JSONObject jo = parseJSONData(response); - - return jo.getJSONObject("data").toMap(); + return airtime(chiRef, phoneNumber, countryToSend, subAccount, null); } + /** + * Redeem airtime transactions. + * + * @param chiRef The Chi reference + * @param phoneNumber The phone number to send the airtime to + * @param countryToSend The country to send the airtime to + * @param subAccount The sub-account to use + * @param meta Additional meta data + * @return A map containing the response data + * @throws Exception If an error occurs during the redemption process + */ public Map airtime(String chiRef, String phoneNumber, String countryToSend, String subAccount, Map meta) throws Exception { JSONObject params = new JSONObject(); params.put("chiRef", chiRef); params.put("phoneNumber", phoneNumber); params.put("countryToSend", countryToSend); - params.put("subAccount", subAccount); - params.put("meta", new JSONObject(meta)); + + if (subAccount != null) + params.put("subAccount", subAccount); + + if (meta != null) + params.put("meta", new JSONObject(meta)); HttpResponse response = handlePOSTRequest("redeem/airtime", params); JSONObject jo = parseJSONData(response); @@ -52,36 +79,55 @@ public Map airtime(String chiRef, String phoneNumber, String cou return jo.getJSONObject("data").toMap(); } + /** + * Redeem any transaction. + * + * @param chiRef the Chi reference + * @param redeemData the data required to redeem. Check the Chimoney API + * document for more information + * @return a map containing the response data + * @throws Exception if an error occurs during the redeem operation + */ public Map any(String chiRef, Map redeemData) throws Exception { - JSONObject params = new JSONObject(); - params.put("chiRef", chiRef); - params.put("redeemData", new JSONObject(redeemData)); - - HttpResponse response = handlePOSTRequest("redeem/any", params); - JSONObject jo = parseJSONData(response); - - return jo.getJSONObject("data").toMap(); + return any(chiRef, redeemData, null, null); } + /** + * Redeem any transaction. + * + * @param chiRef the Chi reference + * @param redeemData the data required to redeem. Check the Chimoney API + * document for more information + * @param subAccount the sub-account to use + * @return a map containing the response data + * @throws Exception if an error occurs during the redeem operation + */ public Map any(String chiRef, Map redeemData, String subAccount) throws Exception { - JSONObject params = new JSONObject(); - params.put("chiRef", chiRef); - params.put("subAccount", subAccount); - params.put("redeemData", new JSONObject(redeemData)); - - HttpResponse response = handlePOSTRequest("redeem/any", params); - JSONObject jo = parseJSONData(response); - - return jo.getJSONObject("data").toMap(); + return any(chiRef, redeemData, subAccount, null); } + /** + * Redeem any transaction. + * + * @param chiRef the Chi reference + * @param redeemData the data required to redeem. Check the Chimoney API + * document for more information + * @param subAccount the sub-account to use + * @param meta additional metadata + * @return a map containing the response data + * @throws Exception if an error occurs during the redeem operation + */ public Map any(String chiRef, Map redeemData, String subAccount, Map meta) throws Exception { JSONObject params = new JSONObject(); params.put("chiRef", chiRef); - params.put("subAccount", subAccount); params.put("redeemData", new JSONObject(redeemData)); - params.put("meta", new JSONObject(meta)); + + if (subAccount != null) + params.put("subAccount", subAccount); + + if (meta != null) + params.put("meta", new JSONObject(meta)); HttpResponse response = handlePOSTRequest("redeem/any", params); JSONObject jo = parseJSONData(response); @@ -89,37 +135,45 @@ public Map any(String chiRef, Map redeemData, St return jo.getJSONObject("data").toMap(); } + /** + * Redeem Chimoney. + * + * @param chimoneys An array of Chimoney key-value objects to be + * redeemed. Check the Chimoney API document for more + * information + * @return A map containing the response data from the redemption request + * @throws Exception If an error occurs during the redemption process + */ public Map chimoney(Map[] chimoneys) throws Exception { - JSONObject params = new JSONObject(); - JSONArray ja = new JSONArray(); - - for (Map chimoney : chimoneys) { - ja.put(new JSONObject(chimoney)); - } - params.put("chimoneys", ja); - - HttpResponse response = handlePOSTRequest("redeem/chimoney", params); - JSONObject jo = parseJSONData(response); - - return jo.getJSONObject("data").toMap(); + return chimoney(chimoneys, null, false); } + /** + * Redeem Chimoney. + * + * @param chimoneys An array of Chimoney key-value objects to be + * redeemed. Check the Chimoney API document for more + * information + * @param subAccount The sub-account to use + * @return A map containing the response data from the redemption request + * @throws Exception If an error occurs during the redemption process + */ public Map chimoney(Map[] chimoneys, String subAccount) throws Exception { - JSONObject params = new JSONObject(); - JSONArray ja = new JSONArray(); - - for (Map chimoney : chimoneys) { - ja.put(new JSONObject(chimoney)); - } - params.put("chimoneys", ja); - params.put("subAccount", subAccount); - - HttpResponse response = handlePOSTRequest("redeem/chimoney", params); - JSONObject jo = parseJSONData(response); - - return jo.getJSONObject("data").toMap(); + return chimoney(chimoneys, subAccount, false); } + /** + * Redeem Chimoney. + * + * @param chimoneys An array of Chimoney key-value objects to be + * redeemed. Check the Chimoney API document for more + * information + * @param subAccount The sub-account to use + * @param turnOffNotification A boolean value indicating whether to turn off + * notification + * @return A map containing the response data from the redemption request + * @throws Exception If an error occurs during the redemption process + */ public Map chimoney(Map[] chimoneys, String subAccount, boolean turnOffNotification) throws Exception { JSONObject params = new JSONObject(); @@ -129,8 +183,12 @@ public Map chimoney(Map[] chimoneys, String subA ja.put(new JSONObject(chimoney)); } params.put("chimoneys", ja); - params.put("subAccount", subAccount); - params.put("turnOffNotification", turnOffNotification); + + if (subAccount != null) + params.put("subAccount", subAccount); + + if (turnOffNotification) + params.put("turnOffNotification", turnOffNotification); HttpResponse response = handlePOSTRequest("redeem/chimoney", params); JSONObject jo = parseJSONData(response); @@ -138,24 +196,38 @@ public Map chimoney(Map[] chimoneys, String subA return jo.getJSONObject("data").toMap(); } + /** + * Redeem a gift card. + * + * @param chiRef The reference number of the gift card + * @param redeemOptions The options for redeeming the gift card. Check the + * Chimoney API documentation for more information + * @return A map containing the response data from the gift card redemption + * @throws Exception If an error occurs during the redemption process + */ public Map giftCard(String chiRef, Map redeemOptions) throws Exception { - JSONObject params = new JSONObject(); - params.put("chiRef", chiRef); - params.put("redeemOptions", new JSONObject(redeemOptions)); - - HttpResponse response = handlePOSTRequest("redeem/gift-card", params); - JSONObject jo = parseJSONData(response); - - return jo.getJSONObject("data").toMap(); + return giftCard(chiRef, redeemOptions, null); } + /** + * Redeem a gift card. + * + * @param chiRef The reference number of the gift card + * @param redeemOptions The options for redeeming the gift card. Check the + * Chimoney API documentation for more information + * @param subAccount The sub-account to use + * @return A map containing the response data from the gift card redemption + * @throws Exception If an error occurs during the redemption process + */ public Map giftCard(String chiRef, Map redeemOptions, String subAccount) throws Exception { JSONObject params = new JSONObject(); params.put("chiRef", chiRef); params.put("redeemOptions", new JSONObject(redeemOptions)); - params.put("subAccount", subAccount); + + if (subAccount != null) + params.put("subAccount", subAccount); HttpResponse response = handlePOSTRequest("redeem/gift-card", params); JSONObject jo = parseJSONData(response); @@ -163,24 +235,39 @@ public Map giftCard(String chiRef, Map redeemOpt return jo.getJSONObject("data").toMap(); } + /** + * Redeem mobile money. + * + * @param chiRef The Chi reference. + * @param redeemOptions The data for redeeming mobile money. Check the Chimoney + * API documentation for more information + * @param subAccount The sub-account to use + * @return A map containing the response data from the redemption process + * @throws Exception If an error occurs during the redemption process + */ public Map mobileMoney(String chiRef, Map redeemOptions) throws Exception { - JSONObject params = new JSONObject(); - params.put("chiRef", chiRef); - params.put("redeemOptions", new JSONObject(redeemOptions)); - - HttpResponse response = handlePOSTRequest("redeem/mobile-money", params); - JSONObject jo = parseJSONData(response); - - return jo.getJSONObject("data").toMap(); + return mobileMoney(chiRef, redeemOptions, null); } + /** + * Redeem mobile money. + * + * @param chiRef The Chi reference. + * @param redeemOptions The data for redeeming mobile money. Check the Chimoney + * API documentation for more information + * @param subAccount The sub-account to use + * @return A map containing the response data from the redemption process + * @throws Exception If an error occurs during the redemption process + */ public Map mobileMoney(String chiRef, Map redeemOptions, String subAccount) throws Exception { JSONObject params = new JSONObject(); params.put("chiRef", chiRef); params.put("redeemOptions", new JSONObject(redeemOptions)); - params.put("subAccount", subAccount); + + if (subAccount != null) + params.put("subAccount", subAccount); HttpResponse response = handlePOSTRequest("redeem/mobile-money", params); JSONObject jo = parseJSONData(response); diff --git a/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/SubAccount.java b/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/SubAccount.java index ab2ddc7..218c19c 100644 --- a/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/SubAccount.java +++ b/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/SubAccount.java @@ -6,53 +6,100 @@ import org.json.JSONObject; +/** + * The SubAccount class is a wrapper for the SubAccount module of the Chimoney + * API. + * + */ public class SubAccount extends Base { + + /** + * Constructs a new SubAccount object with the specified Chimoney instance. + * + * @param chimoney the Chimoney instance associated with this SubAccount object + */ SubAccount(Chimoney chimoney) { super(chimoney); } + /** + * Create a sub-account. + * + * @param name the name of the sub-account + * @return a map containing the data of the created sub-account + * @throws Exception if an error occurs during the creation process + */ public Map create(String name) throws Exception { - JSONObject params = new JSONObject(); - params.put("name", name); - - HttpResponse response = handlePOSTRequest("sub-account/create", params); - JSONObject jo = parseJSONData(response); - - return jo.getJSONObject("data").toMap(); + return create(name, null, null, null, null); } + /** + * Create a sub-account. + * + * @param name the name of the sub-account + * @param email the email address of user + * @return a map containing the data of the created sub-account + * @throws Exception if an error occurs during the creation process + */ public Map create(String name, String email) throws Exception { - JSONObject params = new JSONObject(); - params.put("name", name); - params.put("email", email); - - HttpResponse response = handlePOSTRequest("sub-account/create", params); - JSONObject jo = parseJSONData(response); + return create(name, email, null, null, null); + } - return jo.getJSONObject("data").toMap(); + /** + * Create a sub-account. + * + * @param name the name of the sub-account + * @param firstName the first name of user + * @param lastName the last name of user + * @return a map containing the data of the created sub-account + * @throws Exception if an error occurs during the creation process + */ + public Map create(String name, String firstName, String lastName) throws Exception { + return create(name, null, firstName, lastName, null); } + /** + * Create a sub-account. + * + * @param name the name of the sub-account + * @param email the email address of user + * @param firstName the first name of user + * @param lastName the last name of user + * @return a map containing the data of the created sub-account + * @throws Exception if an error occurs during the creation process + */ public Map create(String name, String email, String firstName, String lastName) throws Exception { - JSONObject params = new JSONObject(); - params.put("name", name); - params.put("email", email); - params.put("firstName", firstName); - params.put("lastName", lastName); - - HttpResponse response = handlePOSTRequest("sub-account/create", params); - JSONObject jo = parseJSONData(response); - - return jo.getJSONObject("data").toMap(); + return create(name, email, firstName, lastName, null); } + /** + * Create a sub-account. + * + * @param name the name of the sub-account + * @param email the email address of user + * @param firstName the first name of user + * @param lastName the last name of user + * @param phoneNumber the phone number of the sub-account starting with a + * + and country code + * @return a map containing the data of the created sub-account + * @throws Exception if an error occurs during the creation process + */ public Map create(String name, String email, String firstName, String lastName, String phoneNumber) throws Exception { JSONObject params = new JSONObject(); params.put("name", name); - params.put("email", email); - params.put("firstName", firstName); - params.put("lastName", lastName); - params.put("phoneNumber", phoneNumber); + + if (email != null) + params.put("email", email); + + if (firstName != null) + params.put("firstName", firstName); + + if (lastName != null) + params.put("lastName", lastName); + + if (phoneNumber != null) + params.put("phoneNumber", phoneNumber); HttpResponse response = handlePOSTRequest("sub-account/create", params); JSONObject jo = parseJSONData(response); @@ -60,39 +107,77 @@ public Map create(String name, String email, String firstName, S return jo.getJSONObject("data").toMap(); } + /** + * Update a sub-account. + * + * @param id The ID of the sub-account to update. + * @param meta The metadata to store any number of user information. + * Check the Chimoney API docmentation for more information + * @return A map containing the updated sub-account data + * @throws Exception If an error occurs during the update process + */ public Map update(String id, Map meta) throws Exception { - JSONObject params = new JSONObject(); - params.put("id", id); - params.put("meta", new JSONObject(meta)); - - HttpResponse response = handlePOSTRequest("sub-account/update", params); - JSONObject jo = parseJSONData(response); - - return jo.getJSONObject("data").toMap(); + return update(id, meta, null, null, null); } + /** + * Update a sub-account. + * + * @param id The ID of the sub-account to update. + * @param meta The metadata to store any number of user information. + * Check the Chimoney API docmentation for more information + * @param firstName The new first name for the sub-account + * @param lastName The new last name for the sub-account + * @return A map containing the updated sub-account data + * @throws Exception If an error occurs during the update process + */ public Map update(String id, Map meta, String firstName, String lastName) throws Exception { - JSONObject params = new JSONObject(); - params.put("id", id); - params.put("meta", new JSONObject(meta)); - params.put("firstName", firstName); - params.put("lastName", lastName); - - HttpResponse response = handlePOSTRequest("sub-account/update", params); - JSONObject jo = parseJSONData(response); + return update(id, meta, firstName, lastName, null); + } - return jo.getJSONObject("data").toMap(); + /** + * Update a sub-account. + * + * @param id The ID of the sub-account to update. + * @param meta The metadata to store any number of user information. + * Check the Chimoney API docmentation for more information + * @param phoneNumber The new phone number for the sub-account starting with a + * + and country code + * @return A map containing the updated sub-account data + * @throws Exception If an error occurs during the update process + */ + public Map update(String id, Map meta, String phoneNumber) throws Exception { + return update(id, meta, null, null, phoneNumber); } + /** + * Update a sub-account. + * + * @param id The ID of the sub-account to update. + * @param meta The metadata to store any number of user information. + * Check the Chimoney API docmentation for more information + * @param firstName The new first name for the sub-account + * @param lastName The new last name for the sub-account + * @param phoneNumber The new phone number for the sub-account starting with a + * + and country code + * @return A map containing the updated sub-account data + * @throws Exception If an error occurs during the update process + */ public Map update(String id, Map meta, String firstName, String lastName, String phoneNumber) throws Exception { JSONObject params = new JSONObject(); params.put("id", id); params.put("meta", new JSONObject(meta)); - params.put("firstName", firstName); - params.put("lastName", lastName); - params.put("phoneNumber", phoneNumber); + + if (firstName != null) + params.put("firstName", firstName); + + if (lastName != null) + params.put("lastName", lastName); + + if (phoneNumber != null) + params.put("phoneNumber", phoneNumber); HttpResponse response = handlePOSTRequest("sub-account/update", params); JSONObject jo = parseJSONData(response); @@ -100,6 +185,13 @@ public Map update(String id, Map meta, String fi return jo.getJSONObject("data").toMap(); } + /** + * Retrieves the details of a sub-account with the specified ID. + * + * @param id The ID of the sub-account. + * @return A map containing the details of the sub-account. + * @throws Exception If an error occurs while retrieving the details. + */ public Map getDetails(String id) throws Exception { HttpResponse response = handleGETRequest("sub-account/get?id=" + id); JSONObject jo = parseJSONData(response); @@ -107,6 +199,12 @@ public Map getDetails(String id) throws Exception { return jo.getJSONObject("data").toMap(); } + /** + * Retrieves a list of sub-accounts associated with this user. + * + * @return A list of sub-accounts. + * @throws Exception If an error occurs while retrieving the sub-accounts. + */ public List getUserSubAccounts() throws Exception { HttpResponse response = handleGETRequest("sub-account/list"); JSONObject jo = parseJSONData(response); @@ -114,6 +212,13 @@ public List getUserSubAccounts() throws Exception { return jo.getJSONArray("data").toList(); } + /** + * Deletes a sub-account with the specified ID. + * + * @param id The ID of the sub-account to delete. + * @return A map containing the data of the deleted sub-account. + * @throws Exception If an error occurs during the deletion process. + */ public Map delete(String id) throws Exception { HttpResponse response = handleDELETERequest("sub-account/delete?id=" + id); JSONObject jo = parseJSONData(response); diff --git a/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/Wallet.java b/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/Wallet.java index 38ea759..5318aec 100644 --- a/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/Wallet.java +++ b/SDK Submissions/Chimoney-Java/chimoney/src/main/java/io/chimoney/chimoney/Wallet.java @@ -7,48 +7,84 @@ import org.json.JSONObject; /** - * Wallet + * The Wallet class is a wrapper for the Wallet module of the Chimoney API. + * */ public class Wallet extends Base { + + /** + * Represents the types of wallets in Chimoney. + * Possible values are: chi, momo, and airtime. + */ enum Types { chi, momo, airtime } + /** + * Constructs a new Wallet object with the specified Chimoney instance. + * + * @param chimoney the Chimoney instance associated with this Wallet object + */ public Wallet(Chimoney chimoney) { super(chimoney); } + /** + * Retrieves a list of wallets associated with the user. + * + * @return a list of wallets + * @throws Exception if an error occurs during the retrieval process + */ public List listWallets() throws Exception { - HttpResponse response = handlePOSTRequest("wallets/list", null); - JSONObject jo = parseJSONData(response); - - return jo.getJSONArray("data").toList(); + return listWallets(null); } - public List getWallets(String subAccount) throws Exception { - JSONObject params = new JSONObject(); - params.put("subAccount", subAccount); - - HttpResponse response = handlePOSTRequest("wallets/list", params); + /** + * Retrieves a list of wallets associated with the user. + * + * @param subAccount the sub-account to retrieve wallets for + * @return a list of wallets + * @throws Exception if an error occurs during the retrieval process + */ + public List listWallets(String subAccount) throws Exception { + JSONObject paramsJson = null; + + if (subAccount != null) { + paramsJson = new JSONObject(); + paramsJson.put("subAccount", subAccount); + } + + HttpResponse response = handlePOSTRequest("wallets/list", paramsJson); JSONObject jo = parseJSONData(response); return jo.getJSONArray("data").toList(); } + /** + * Retrieves the wallet information for the specified wallet ID. + * + * @param walletID the ID of the wallet to retrieve + * @return a map containing the wallet information + * @throws Exception if an error occurs during the retrieval process + */ public Map getWallet(String walletID) throws Exception { - JSONObject params = new JSONObject(); - params.put("walletID", walletID); - - HttpResponse response = handlePOSTRequest("wallets/lookup", params); - JSONObject jo = parseJSONData(response); - - return jo.getJSONObject("data").toMap(); + return getWallet(walletID, null); } + /** + * Retrieves the wallet information for the specified wallet ID and sub-account. + * + * @param walletID the ID of the wallet to retrieve + * @param subAccount the sub-account associated with the wallet + * @return a map containing the wallet information + * @throws Exception if an error occurs during the retrieval process + */ public Map getWallet(String walletID, String subAccount) throws Exception { JSONObject params = new JSONObject(); params.put("walletID", walletID); - params.put("subAccount", subAccount); + + if (subAccount != null) + params.put("subAccount", subAccount); HttpResponse response = handlePOSTRequest("wallets/lookup", params); JSONObject jo = parseJSONData(response); @@ -56,36 +92,53 @@ public Map getWallet(String walletID, String subAccount) throws return jo.getJSONObject("data").toMap(); } + /** + * Transfers funds to a wallet. + * + * @param receiver the receiver's wallet address + * @param valueInUSD the value to transfer in USD + * @return a map containing the transferred funds details + * @throws Exception if an error occurs during the transfer + */ public Map transferToWallet(String receiver, int valueInUSD) throws Exception { - JSONObject params = new JSONObject(); - params.put("receiver", receiver); - params.put("valueInUSD", valueInUSD); - - HttpResponse response = handlePOSTRequest("wallets/transfer", params); - JSONObject jo = parseJSONData(response); - - return jo.getJSONObject("data").toMap(); + return transferToWallet(receiver, valueInUSD, null, null); } - public Map transferToWallet(String receiver, int valueInUSD, Types walletType) throws Exception { - JSONObject params = new JSONObject(); - params.put("receiver", receiver); - params.put("valueInUSD", valueInUSD); - params.put("wallet", walletType.toString()); - - HttpResponse response = handlePOSTRequest("wallets/transfer", params); - JSONObject jo = parseJSONData(response); - - return jo.getJSONObject("data").toMap(); + /** + * Transfers funds to a wallet. + * + * @param receiver the receiver's wallet address + * @param valueInUSD the value to transfer in USD + * @param subAccount the sub-account to transfer funds to + * @return a map containing the transferred funds details + * @throws Exception if an error occurs during the transfer + */ + public Map transferToWallet(String receiver, int valueInUSD, String subAccount) throws Exception { + return transferToWallet(receiver, valueInUSD, subAccount, null); } - public Map transferToWallet(String receiver, int valueInUSD, Types walletType, String subAccount) + /** + * Transfers funds to a wallet. + * + * @param receiver the receiver's wallet address + * @param valueInUSD the value to transfer in USD + * @param subAccount the sub-account to transfer funds to + * @param walletType the type of wallet. Leave blank except you fully understand + * the different wallet types + * @return a map containing the transferred funds details + * @throws Exception if an error occurs during the transfer + */ + public Map transferToWallet(String receiver, int valueInUSD, String subAccount, Types walletType) throws Exception { JSONObject params = new JSONObject(); params.put("receiver", receiver); params.put("valueInUSD", valueInUSD); - params.put("wallet", walletType.toString()); - params.put("subAccount", subAccount); + + if (walletType != null) + params.put("wallet", walletType.toString()); + + if (subAccount != null) + params.put("subAccount", subAccount); HttpResponse response = handlePOSTRequest("wallets/transfer", params); JSONObject jo = parseJSONData(response);