[feature] Recipients integration

src/main/java/com/mangopay/MangoPayApi.java

@@ -58,6 +58,7 @@ public MangoPayApi() {
         setVirtualAccountApi(new VirtualAccountApiImpl(this));
         setConversionsApi(new ConversionsApiImpl(this, gsonBuilder));
         setIdentityVerificationApi(new IdentityVerificationApiImpl(this));
+        setRecipientApi(new RecipientApiImpl(this));
 
         // register custom serializers/deserializers for objects that are used in multiple APIs
         gsonBuilder.registerTypeAdapter(CardInfoType.class, new CardInfoTypeSerializer());
@@ -228,6 +229,11 @@ public MangoPayApi() {
      */
     private IdentityVerificationApi identityVerificationApi;
 
+    /**
+     * Provides Recipients methods
+     */
+    private RecipientApi recipientApi;
+
     private Gson gson;
 
     /**
@@ -491,4 +497,12 @@ public IdentityVerificationApi getIdentityVerificationApi() {
     public void setIdentityVerificationApi(IdentityVerificationApi identityVerificationApi) {
         this.identityVerificationApi = identityVerificationApi;
     }
+
+    public RecipientApi getRecipientApi() {
+        return recipientApi;
+    }
+
+    public void setRecipientApi(RecipientApi recipientApi) {
+        this.recipientApi = recipientApi;
+    }
 }

src/main/java/com/mangopay/core/APIs/ApiBase.java

@@ -245,17 +245,23 @@ protected MangoPayApi getRoot() {
         put("get_conversion_quote", new String[]{"/conversions/quote/%s", RequestType.GET.toString()});
         put("create_quoted_conversion", new String[]{"/conversions/quoted-conversion", RequestType.POST.toString()});
 
-        // virtual account URLs
         put("virtual_account_create", new String[]{"/wallets/%s/virtual-accounts", RequestType.POST.toString()});
         put("virtual_account_deactivate", new String[]{"/wallets/%s/virtual-accounts/%s", RequestType.PUT.toString()});
         put("virtual_account_get", new String[]{"/wallets/%s/virtual-accounts/%s", RequestType.GET.toString()});
         put("virtual_account_get_all", new String[]{"/wallets/%s/virtual-accounts", RequestType.GET.toString()});
         put("virtual_account_get_availabilities", new String[]{"/virtual-accounts/availability", RequestType.GET.toString()});
 
-        // identity verification
         put("identify_verification_create", new String[]{"/users/%s/identity-verifications", RequestType.POST.toString()});
         put("identify_verification_get", new String[]{"/identity-verifications/%s", RequestType.GET.toString()});
         put("identify_verification_checks_get", new String[]{"/identity-verifications/%s/checks", RequestType.GET.toString()});
+
+        put("recipient_create", new String[]{"/users/%s/recipients", RequestType.POST.toString()});
+        put("recipient_get", new String[]{"/recipients/%s", RequestType.GET.toString()});
+        put("recipient_get_all", new String[]{"/users/%s/recipients", RequestType.GET.toString()});
+        put("recipient_get_schema", new String[]{"/recipients/schema?payoutMethodType=%s&recipientType=%s&currency=%s", RequestType.GET.toString()});
+        put("recipient_validate", new String[]{"/users/%s/recipients/validate", RequestType.POST.toString()});
+        put("recipient_deactivate", new String[]{"/recipients/%s", RequestType.PUT.toString()});
+        put("recipient_get_payout_methods", new String[]{"/recipients/payout-methods?country=%s&currency=%s", RequestType.GET.toString()});
     }};
 
     /**

src/main/java/com/mangopay/core/APIs/RecipientApi.java

@@ -0,0 +1,87 @@
+package com.mangopay.core.APIs;
+
+import com.mangopay.core.enumerations.CountryIso;
+import com.mangopay.core.enumerations.CurrencyIso;
+import com.mangopay.entities.Recipient;
+import com.mangopay.entities.subentities.PayoutMethods;
+import com.mangopay.entities.subentities.RecipientSchema;
+import com.mangopay.entities.subentities.UserRecipients;
+
+public interface RecipientApi {
+    /**
+     * Create a User recipient
+     *
+     * @param recipient the recipient
+     * @param userId    the user identifier
+     * @return Recipient instance
+     */
+    Recipient create(Recipient recipient, String userId) throws Exception;
+
+    /**
+     * Create a User recipient
+     *
+     * @param idempotencyKey idempotency key for this request.
+     * @param recipient      the recipient
+     * @param userId         the user identifier
+     * @return Recipient instance
+     */
+    Recipient create(String idempotencyKey, Recipient recipient, String userId) throws Exception;
+
+    /**
+     * Get a Recipient
+     *
+     * @param recipientId recipient identifier
+     * @return Recipient instance
+     */
+    Recipient get(String recipientId) throws Exception;
+
+    /**
+     * Get all recipients associated with a specific user
+     *
+     * @param userId the user identifier
+     * @return UserRecipients instance
+     */
+    UserRecipients getUserRecipients(String userId) throws Exception;
+
+    /**
+     * Get a Recipient schema
+     *
+     * @param payoutMethodType Defines the payout method (e.g., LocalBankTransfer, InternationalBankTransfer).
+     * @param recipientType    Specifies whether the recipient is an Individual or a Business.
+     * @param currency         3-letter ISO 4217 destination currency code (e.g. EUR, USD, GBP, AUD, CAD,HKD, SGD, MXN).
+     * @return RecipientSchema instance
+     */
+    RecipientSchema getSchema(String payoutMethodType, String recipientType, CurrencyIso currency) throws Exception;
+
+    /**
+     * Validate recipient data
+     *
+     * @param recipient the recipient
+     * @param userId    the user identifier
+     */
+    void validate(Recipient recipient, String userId) throws Exception;
+
+    /**
+     * Validate recipient data
+     *
+     * @param idempotencyKey idempotency key for this request.
+     * @param recipient      the recipient
+     * @param userId         the user identifier
+     */
+    void validate(String idempotencyKey, Recipient recipient, String userId) throws Exception;
+
+    /**
+     * Deactivate a Recipient
+     *
+     * @param recipientId the recipient identifier
+     */
+    void deactivate(String recipientId) throws Exception;
+
+    /**
+     * See payout methods available to your platform by currency and country
+     *
+     * @param country  The destination country of the payout method.
+     * @param currency The currency of the payout method.
+     */
+    PayoutMethods getPayoutMethods(CountryIso country, CurrencyIso currency) throws Exception;
+}

src/main/java/com/mangopay/core/APIs/implementation/RecipientApiImpl.java

@@ -0,0 +1,67 @@
+package com.mangopay.core.APIs.implementation;
+
+import com.mangopay.MangoPayApi;
+import com.mangopay.core.APIs.ApiBase;
+import com.mangopay.core.APIs.RecipientApi;
+import com.mangopay.core.enumerations.CountryIso;
+import com.mangopay.core.enumerations.CurrencyIso;
+import com.mangopay.entities.Recipient;
+import com.mangopay.entities.subentities.PayoutMethods;
+import com.mangopay.entities.subentities.RecipientSchema;
+import com.mangopay.entities.subentities.UserRecipients;
+
+public class RecipientApiImpl extends ApiBase implements RecipientApi {
+    /**
+     * Creates new RecipientApi instance.
+     *
+     * @param root Root/parent instance that holds the OAuthToken and Configuration instance.
+     */
+    public RecipientApiImpl(MangoPayApi root) {
+        super(root);
+    }
+
+    @Override
+    public Recipient create(Recipient recipient, String userId) throws Exception {
+        return this.create(null, recipient, userId);
+    }
+
+    @Override
+    public Recipient create(String idempotencyKey, Recipient recipient, String userId) throws Exception {
+        return this.createObject(Recipient.class, idempotencyKey, "recipient_create", recipient, userId);
+    }
+
+    @Override
+    public Recipient get(String recipientId) throws Exception {
+        return this.getObject(Recipient.class, "recipient_get", recipientId);
+    }
+
+    @Override
+    public UserRecipients getUserRecipients(String userId) throws Exception {
+        return this.getObject(UserRecipients.class, "recipient_get_all", userId);
+    }
+
+    @Override
+    public RecipientSchema getSchema(String payoutMethodType, String recipientType, CurrencyIso currency) throws Exception {
+        return this.getObject(RecipientSchema.class, "recipient_get_schema", payoutMethodType, recipientType, currency);
+    }
+
+    @Override
+    public void validate(Recipient recipient, String userId) throws Exception {
+        validate(null, recipient, userId);
+    }
+
+    @Override
+    public void validate(String idempotencyKey, Recipient recipient, String userId) throws Exception {
+        this.createObject(Recipient.class, idempotencyKey, "recipient_validate", recipient, userId);
+    }
+
+    @Override
+    public void deactivate(String recipientId) throws Exception {
+        this.updateObject(Recipient.class, "recipient_deactivate", new Recipient(), recipientId);
+    }
+
+    @Override
+    public PayoutMethods getPayoutMethods(CountryIso country, CurrencyIso currency) throws Exception {
+        return this.getObject(PayoutMethods.class, "recipient_get_payout_methods", country, currency);
+    }
+}

src/main/java/com/mangopay/core/RestTool.java

@@ -381,10 +381,10 @@ private <T extends Dto, U extends Dto> T doRequest(Class<T> classOfT, String ide
             // get response
             this.responseCode = connection.getResponseCode();
             InputStream is;
-            if (this.responseCode != 200 && this.responseCode != 204) {
-                is = connection.getErrorStream();
-            } else {
+            if (responseCodeIsSuccessful()) {
                 is = connection.getInputStream();
+            } else {
+                is = connection.getErrorStream();
             }
 
             checkApiConnection(is);
@@ -400,20 +400,23 @@ private <T extends Dto, U extends Dto> T doRequest(Class<T> classOfT, String ide
             String responseString = resp.toString();
 
             if (this.debugMode) {
-                if (this.responseCode == 200 || this.responseCode == 204) {
+                if (responseCodeIsSuccessful()) {
                     logger.info("Response OK: {}", responseString);
                 } else {
                     logger.info("Response ERROR: {}", responseString);
                 }
             }
 
-            if (this.responseCode == 200) {
+            if (responseCodeIsSuccessful() && responseCode != 204) {
 
                 this.readResponseHeaders(connection);
 
-                response = castResponseToEntity(classOfT, JsonParser.parseString(responseString).getAsJsonObject());
+                // some endpoints return 200 with empty body
+                if (!responseString.isEmpty()) {
+                    response = castResponseToEntity(classOfT, JsonParser.parseString(responseString).getAsJsonObject());
+                    if (this.debugMode) logger.info("Response object: {}", response.toString());
+                }
 
-                if (this.debugMode) logger.info("Response object: {}", response.toString());
             }
 
             this.checkResponseCode(responseString);
@@ -593,10 +596,10 @@ private <T extends Dto> List<T> doRequestList(Class<T[]> classOfT, Class<T> clas
             //Get Response	
             this.responseCode = connection.getResponseCode();
             InputStream is;
-            if (this.responseCode != 200) {
-                is = connection.getErrorStream();
-            } else {
+            if (responseCodeIsSuccessful()) {
                 is = connection.getInputStream();
+            } else {
+                is = connection.getErrorStream();
             }
 
             checkApiConnection(is);
@@ -613,28 +616,30 @@ private <T extends Dto> List<T> doRequestList(Class<T[]> classOfT, Class<T> clas
             String responseString = resp.toString();
 
             if (this.debugMode) {
-                if (this.responseCode == 200) {
+                if (responseCodeIsSuccessful()) {
                     logger.info("Response OK: {}", responseString);
                 } else {
                     logger.info("Response ERROR: {}", responseString);
                 }
             }
 
-            if (this.responseCode == 200) {
-
+            if (responseCodeIsSuccessful() && responseCode != 204) {
                 this.readResponseHeaders(connection);
 
-                JsonArray ja = JsonParser.parseString(responseString).getAsJsonArray();
+                // some endpoints return 200 with empty body
+                if (!responseString.isEmpty()) {
+                    JsonArray ja = JsonParser.parseString(responseString).getAsJsonArray();
 
-                for (int x = 0; x < ja.size(); x++) {
-                    JsonObject jo = ja.get(x).getAsJsonObject();
-                    T toAdd = castResponseToEntity(classOfTItem, jo);
-                    response.add(toAdd);
-                }
+                    for (int x = 0; x < ja.size(); x++) {
+                        JsonObject jo = ja.get(x).getAsJsonObject();
+                        T toAdd = castResponseToEntity(classOfTItem, jo);
+                        response.add(toAdd);
+                    }
 
-                if (this.debugMode) {
-                    logger.info("Response object: {}", response.toString());
-                    logger.info("Elements count: {}", response.size());
+                    if (this.debugMode) {
+                        logger.info("Response object: {}", response.toString());
+                        logger.info("Elements count: {}", response.size());
+                    }
                 }
             }
 
@@ -697,17 +702,16 @@ private void checkApiConnection(InputStream is) throws ResponseException {
     }
 
     /**
-     * Checks the HTTP response code and if it's neither 200 nor 204 throws a ResponseException.
+     * Checks the HTTP response code and if it's not successful throws a ResponseException.
      *
      * @param message Text response.
-     * @throws ResponseException If response code is other than 200 or 204.
+     * @throws ResponseException If response code is not successful
      */
     private void checkResponseCode(String message) throws ResponseException {
 
-        if (this.responseCode != 200 && this.responseCode != 204) {
+        if (!responseCodeIsSuccessful()) {
 
             HashMap<Integer, String> responseCodes = new HashMap<Integer, String>() {{
-                put(206, "PartialContent");
                 put(400, "Bad request");
                 put(401, "Unauthorized");
                 put(403, "Prohibition to use the method");
@@ -772,4 +776,8 @@ private void checkResponseCode(String message) throws ResponseException {
             throw responseException;
         }
     }
+
+    private boolean responseCodeIsSuccessful() {
+        return responseCode >= 200 && responseCode < 300;
+    }
 }

src/main/java/com/mangopay/core/enumerations/EventType.java

@@ -110,5 +110,9 @@ public enum EventType {
     IDENTITY_VERIFICATION_FAILED,
     IDENTITY_VERIFICATION_INCONCLUSIVE,
     IDENTITY_VERIFICATION_OUTDATED,
-    IDENTITY_VERIFICATION_TIMEOUT
+    IDENTITY_VERIFICATION_TIMEOUT,
+
+    RECIPIENT_ACTIVE,
+    RECIPIENT_CANCELLED,
+    RECIPIENT_DEACTIVATED
 }