SDK-2756: Add support for requesting, and fetching Share Code resources + tasks

MrBurtyyy · MrBurtyyy · commit f493962f87ef · 2026-01-06T10:44:14.000Z
diff --git a/yoti-sdk-api/src/main/java/com/yoti/api/client/docs/DocScanConstants.java b/yoti-sdk-api/src/main/java/com/yoti/api/client/docs/DocScanConstants.java
@@ -36,6 +36,8 @@ private DocScanConstants() { }
     public static final String SUPPLEMENTARY_DOCUMENT_TEXT_DATA_CHECK = "SUPPLEMENTARY_DOCUMENT_TEXT_DATA_CHECK";
     public static final String SUPPLEMENTARY_DOCUMENT_TEXT_DATA_EXTRACTION = "SUPPLEMENTARY_DOCUMENT_TEXT_DATA_EXTRACTION";
 
+    public static final String VERIFY_SHARE_CODE_TASK = "VERIFY_SHARE_CODE_TASK";
+
     public static final String LIVENESS = "LIVENESS";
     public static final String ZOOM = "ZOOM";
     public static final String STATIC = "STATIC";
diff --git a/yoti-sdk-api/src/main/java/com/yoti/api/client/docs/session/create/RequiredShareCodePayload.java b/yoti-sdk-api/src/main/java/com/yoti/api/client/docs/session/create/RequiredShareCodePayload.java
@@ -0,0 +1,60 @@
+package com.yoti.api.client.docs.session.create;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+public class RequiredShareCodePayload {
+
+    @JsonProperty("issuer")
+    private final String issuer;
+
+    @JsonProperty("scheme")
+    private final String scheme;
+
+    public RequiredShareCodePayload(String issuer, String scheme) {
+        this.issuer = issuer;
+        this.scheme = scheme;
+    }
+
+    public static RequiredShareCodePayload.Builder builder() {
+        return new RequiredShareCodePayload.Builder();
+    }
+
+    public static final class Builder {
+
+        private String issuer;
+        private String scheme;
+
+        /**
+         * Sets the issuer of the required Share Code
+         *
+         * @param issuer the issuer
+         * @return the builder
+         */
+        public Builder withIssuer(String issuer) {
+            this.issuer = issuer;
+            return this;
+        }
+
+        /**
+         * Sets the scheme of the required Share Code
+         *
+         * @param scheme the scheme
+         * @return
+         */
+        public Builder withScheme(String scheme) {
+            this.scheme = scheme;
+            return this;
+        }
+
+        /**
+         * Builds an {@link RequiredShareCodePayload} using the supplied properties in the builder.
+         *
+         * @return the built {@link RequiredShareCodePayload}
+         */
+        public RequiredShareCodePayload build() {
+            return new RequiredShareCodePayload(issuer, scheme);
+        }
+
+    }
+
+}
diff --git a/yoti-sdk-api/src/main/java/com/yoti/api/client/docs/session/create/SessionSpec.java b/yoti-sdk-api/src/main/java/com/yoti/api/client/docs/session/create/SessionSpec.java
@@ -69,6 +69,9 @@ public class SessionSpec {
     @JsonProperty("create_identity_profile_preview")
     private final Boolean createIdentityProfilePreview;
 
+    @JsonProperty("required_share_codes")
+    private final List<RequiredShareCodePayload> requiredShareCodes;
+
     SessionSpec(Integer clientSessionTokenTtl,
             Integer resourcesTtl,
             ImportTokenPayload importToken,
@@ -85,7 +88,8 @@ public class SessionSpec {
             SubjectPayload subject,
             ResourceCreationContainer resources,
             Boolean createIdentityProfilePreview,
-            AdvancedIdentityProfileRequirementsPayload advancedIdentityProfileRequirements) {
+            AdvancedIdentityProfileRequirementsPayload advancedIdentityProfileRequirements,
+            List<RequiredShareCodePayload> requiredShareCodes) {
         this.clientSessionTokenTtl = clientSessionTokenTtl;
         this.resourcesTtl = resourcesTtl;
         this.importToken = importToken;
@@ -103,6 +107,7 @@ public class SessionSpec {
         this.resources = resources;
         this.createIdentityProfilePreview = createIdentityProfilePreview;
         this.advancedIdentityProfileRequirements = advancedIdentityProfileRequirements;
+        this.requiredShareCodes = requiredShareCodes;
     }
 
     public static Builder builder() {
@@ -263,6 +268,15 @@ public AdvancedIdentityProfileRequirementsPayload getAdvancedIdentityProfileRequ
         return advancedIdentityProfileRequirements;
     }
 
+    /**
+     * The list of Share Codes being requested.
+     *
+     * @return the requested Share Codes
+     */
+    public List<RequiredShareCodePayload> getRequiredShareCodes() {
+        return requiredShareCodes;
+    }
+
     public static class Builder {
 
         private final List<RequestedCheck<?>> requestedChecks;
@@ -282,11 +296,13 @@ public static class Builder {
         private SubjectPayload subject;
         private ResourceCreationContainer resources;
         private Boolean createIdentityProfilePreview;
+        private List<RequiredShareCodePayload> requiredShareCodes;
 
         private Builder() {
             requestedChecks = new ArrayList<>();
             requestedTasks = new ArrayList<>();
             requiredDocuments = new ArrayList<>();
+            requiredShareCodes = new ArrayList<>();
         }
 
         /**
@@ -477,6 +493,17 @@ public Builder withAdvancedIdentityProfileRequirements(AdvancedIdentityProfileRe
             return this;
         }
 
+        /**
+         * Adds a required Share Code to the list
+         *
+         * @param requiredShareCode the required share code
+         * @return the builder
+         */
+        public Builder withRequiredShareCode(RequiredShareCodePayload requiredShareCode) {
+            this.requiredShareCodes.add(requiredShareCode);
+            return this;
+        }
+
         /**
          * Builds the {@link SessionSpec} based on the values supplied to the builder
          *
@@ -500,7 +527,8 @@ public SessionSpec build() {
                     subject,
                     resources,
                     createIdentityProfilePreview,
-                    advancedIdentityProfileRequirementsPayload);
+                    advancedIdentityProfileRequirementsPayload,
+                    requiredShareCodes);
         }
     }
 
diff --git a/yoti-sdk-api/src/main/java/com/yoti/api/client/docs/session/retrieve/IdPhotoResponse.java b/yoti-sdk-api/src/main/java/com/yoti/api/client/docs/session/retrieve/IdPhotoResponse.java
@@ -0,0 +1,16 @@
+package com.yoti.api.client.docs.session.retrieve;
+
+import com.yoti.api.client.Media;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+public class IdPhotoResponse {
+
+    @JsonProperty("media")
+    private Media media;
+
+    public Media getMedia() {
+        return media;
+    }
+    
+}
diff --git a/yoti-sdk-api/src/main/java/com/yoti/api/client/docs/session/retrieve/LookupProfileResponse.java b/yoti-sdk-api/src/main/java/com/yoti/api/client/docs/session/retrieve/LookupProfileResponse.java
@@ -0,0 +1,16 @@
+package com.yoti.api.client.docs.session.retrieve;
+
+import com.yoti.api.client.Media;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+public class LookupProfileResponse {
+
+    @JsonProperty("media")
+    private Media media;
+
+    public Media getMedia() {
+        return media;
+    }
+
+}
diff --git a/yoti-sdk-api/src/main/java/com/yoti/api/client/docs/session/retrieve/ResourceContainer.java b/yoti-sdk-api/src/main/java/com/yoti/api/client/docs/session/retrieve/ResourceContainer.java
@@ -23,6 +23,9 @@ public class ResourceContainer {
     @JsonProperty("applicant_profiles")
     private List<ApplicantProfileResourceResponse> applicantProfiles;
 
+    @JsonProperty("share_codes")
+    private List<ShareCodeResourceResponse> shareCodes;
+
     /**
      * Returns ID documents that were uploaded by the user
      *
@@ -97,6 +100,15 @@ public List<ApplicantProfileResourceResponse> getApplicantProfiles() {
         return applicantProfiles;
     }
 
+    /**
+     * Returns ShareCode resources uploaded by the user
+     *
+     * @return the list of Share Code resources
+     */
+    public List<ShareCodeResourceResponse> getShareCodes() {
+        return shareCodes;
+    }
+
     ResourceContainer filterForCheck(CheckResponse checkResponse) {
         ResourceContainer newResourceContainer = new ResourceContainer();
         newResourceContainer.idDocuments = filterResources(this.idDocuments, checkResponse.getResourcesUsed());
diff --git a/yoti-sdk-api/src/main/java/com/yoti/api/client/docs/session/retrieve/ReturnedProfileResponse.java b/yoti-sdk-api/src/main/java/com/yoti/api/client/docs/session/retrieve/ReturnedProfileResponse.java
@@ -0,0 +1,16 @@
+package com.yoti.api.client.docs.session.retrieve;
+
+import com.yoti.api.client.Media;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+public class ReturnedProfileResponse {
+
+    @JsonProperty("media")
+    private Media media;
+
+    public Media getMedia() {
+        return media;
+    }
+    
+}
diff --git a/yoti-sdk-api/src/main/java/com/yoti/api/client/docs/session/retrieve/ShareCodeResourceResponse.java b/yoti-sdk-api/src/main/java/com/yoti/api/client/docs/session/retrieve/ShareCodeResourceResponse.java
@@ -0,0 +1,41 @@
+package com.yoti.api.client.docs.session.retrieve;
+
+import java.util.List;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+public class ShareCodeResourceResponse extends ResourceResponse {
+
+    @JsonProperty("lookup_profile")
+    private LookupProfileResponse lookupProfile;
+
+    @JsonProperty("returned_profile")
+    private ReturnedProfileResponse returnedProfile;
+
+    @JsonProperty("id_photo")
+    private IdPhotoResponse idPhoto;
+
+    @JsonProperty("file")
+    private FileResponse file;
+
+    public LookupProfileResponse getLookupProfile() {
+        return lookupProfile;
+    }
+
+    public ReturnedProfileResponse getReturnedProfile() {
+        return returnedProfile;
+    }
+
+    public IdPhotoResponse getIdPhoto() {
+        return idPhoto;
+    }
+
+    public FileResponse getFile() {
+        return file;
+    }
+
+    public List<ShareCodeTaskResponse> getVerifyShareCodeTasks() {
+        return filterTasksByType(ShareCodeTaskResponse.class);
+    }
+
+}
diff --git a/yoti-sdk-api/src/main/java/com/yoti/api/client/docs/session/retrieve/ShareCodeTaskResponse.java b/yoti-sdk-api/src/main/java/com/yoti/api/client/docs/session/retrieve/ShareCodeTaskResponse.java
@@ -0,0 +1,4 @@
+package com.yoti.api.client.docs.session.retrieve;
+
+public class ShareCodeTaskResponse extends TaskResponse {
+}
diff --git a/yoti-sdk-api/src/main/java/com/yoti/api/client/docs/session/retrieve/TaskResponse.java b/yoti-sdk-api/src/main/java/com/yoti/api/client/docs/session/retrieve/TaskResponse.java
@@ -13,6 +13,7 @@
 @JsonSubTypes({
         @JsonSubTypes.Type(value = IdDocTextExtractionTaskResponse.class, name = DocScanConstants.ID_DOCUMENT_TEXT_DATA_EXTRACTION),
         @JsonSubTypes.Type(value = SupplementaryDocumentTextExtractionTaskResponse.class, name = DocScanConstants.SUPPLEMENTARY_DOCUMENT_TEXT_DATA_EXTRACTION),
+        @JsonSubTypes.Type(value = ShareCodeTaskResponse.class, name = DocScanConstants.VERIFY_SHARE_CODE_TASK)
 })
 public class TaskResponse {
 
diff --git a/yoti-sdk-api/src/test/java/com/yoti/api/client/docs/session/create/SessionSpecTest.java b/yoti-sdk-api/src/test/java/com/yoti/api/client/docs/session/create/SessionSpecTest.java
@@ -2,6 +2,7 @@
 
 import static org.hamcrest.MatcherAssert.assertThat;
 import static org.hamcrest.Matchers.contains;
+import static org.hamcrest.Matchers.containsInRelativeOrder;
 import static org.hamcrest.Matchers.hasItems;
 import static org.hamcrest.Matchers.hasSize;
 import static org.hamcrest.Matchers.instanceOf;
@@ -39,6 +40,11 @@ public class SessionSpecTest {
     private static final String SOME_SDK_CONFIG_LOCALE = "en";
     private static final String SOME_SDK_CONFIG_PRESET_ISSUING_COUNTRY = "USA";
 
+    private static final String SOME_ISSUER = "UK_GOV";
+    private static final String SOME_SCHEME = "RTW";
+    private static final String SOME_OTHER_ISSUER = "someOtherIssuer";
+    private static final String SOME_OTHER_SCHEME = "someOtherScheme";
+
     private static final String SOME_SDK_CONFIG_SUCCESS_URL = "https://yourdomain.com/some/success/endpoint";
     private static final String SOME_SDK_CONFIG_ERROR_URL = "https://yourdomain.com/some/error/endpoint";
 
@@ -251,4 +257,37 @@ public void shouldBuildWithImportToken() {
         assertThat(sessionSpec.getImportToken(), is(importTokenMock));
     }
 
+    @Test
+    public void shouldBuildWithSingleRequiredShareCode() {
+        RequiredShareCodePayload requiredShareCodePayload = RequiredShareCodePayload.builder()
+                .withIssuer(SOME_ISSUER)
+                .withScheme(SOME_SCHEME)
+                .build();
+
+        SessionSpec sessionSpec = SessionSpec.builder()
+                .withRequiredShareCode(requiredShareCodePayload)
+                .build();
+
+        assertThat(sessionSpec.getRequiredShareCodes(), containsInRelativeOrder(requiredShareCodePayload));
+    }
+
+    @Test
+    public void shouldBuildWithMultipleRequiredShareCodes() {
+        RequiredShareCodePayload requiredShareCodePayload1 = RequiredShareCodePayload.builder()
+                .withIssuer(SOME_ISSUER)
+                .withScheme(SOME_SCHEME)
+                .build();
+        RequiredShareCodePayload requiredShareCodePayload2 = RequiredShareCodePayload.builder()
+                .withIssuer(SOME_OTHER_ISSUER)
+                .withScheme(SOME_OTHER_SCHEME)
+                .build();
+
+        SessionSpec sessionSpec = SessionSpec.builder()
+                .withRequiredShareCode(requiredShareCodePayload1)
+                .withRequiredShareCode(requiredShareCodePayload2)
+                .build();
+
+        assertThat(sessionSpec.getRequiredShareCodes(), containsInRelativeOrder(requiredShareCodePayload1, requiredShareCodePayload2));
+    }
+
 }

-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +package com.yoti.api.client.docs.session.retrieve;
++
 +public class ShareCodeTaskResponse extends TaskResponse {
 +}