Merge pull request #8 from Lenddo/v2.6

V2.6
Lenddo · Oct 3, 2017 · 8f5079d · 8f5079d
2 parents 44eef9a + 4660e0e
commit 8f5079d
Show file tree

Hide file tree

Showing 7 changed files with 210 additions and 4 deletions.
diff --git a/README.md b/README.md
@@ -9,6 +9,7 @@
 - [Requirements](#requirements)
 - [Installation](#installation)
 - [REST Services](#rest-services)
+  - [Authorize API Client](#authorize-api-client)
   - [Service Client](#service-client)
   - [Whitelabel Client](#whitelabel-client)
   - [Handling Exceptions](#handling-exceptions)
@@ -31,7 +32,11 @@ The Lenddo PHP SDK is available via Composer and can be installed by running the
 Please refer to the packagist link here: https://packagist.org/packages/lenddo/sdk.
 
 ## REST Services
-The **ServiceClient** and **WhiteLabelClient** This SDK will allow you to contact Lenddo's REST based services. It acts as a wrapper around the  popular **GuzzleHttp\Guzzle** package. A common interface will be returned regardless of the Guzzle version used and the original Guzzle request/response objects are exposed for your convenience.
+The **AuthorizeApiClient**, **ServiceClient** and **WhiteLabelClient** This SDK will allow you to contact Lenddo's REST based services. It acts as a wrapper around the  popular **GuzzleHttp\Guzzle** package. A common interface will be returned regardless of the Guzzle version used and the original Guzzle request/response objects are exposed for your convenience.
+
+### Authorize API Client
+The **AuthorizeApiClient** will allow you to impact product output by asynchronously providing data critical to the scoring or verification process.
+- [Read the documentation here](docs/authorize_api_client.md)
 
 ### Service Client
 The **ServiceClient** will allow you to retrieve the scoring, verification, and decision results from Lenddo.
@@ -51,6 +56,11 @@ While the REST Services allow you to retrieve the results of a scoring or verifi
 - [Read the documentation here](docs/webhooks.md)
 
 ## ChangeLog
+**v2.6** Release Notes - https://github.com/Lenddo/php-lenddo/releases/tag/v2.6
+> **Summary**
+> * Adding Support for ApplicationMultipleScores [Documentation](docs/service_client.md#get-results-for-a-multiple-score-model)
+> * Adding support for Authorize API & PriorityData [Documentation](docs/authorize_api_client.md)
+
 **v2.5** Release Notes - https://github.com/Lenddo/php-lenddo/releases/tag/v2.5
 > **Summary**
 > * Adding support for e-mail probe in the verification class.

diff --git a/docs/authorize_api_client.md b/docs/authorize_api_client.md
@@ -0,0 +1,112 @@
+# Authorize API Client
+_Provide additional data criticla for the onboarding experience._
+
+The Authorize API Client provides asynchronous methods to communicate critical data to Lenddo that may impact the product
+output. This data may be used for verification, scoring, decisioning etc.
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**
+
+- [Instantiating the Client](#instantiating-the-client)
+- [PriorityData](#prioritydata)
+  - [Workflow](#workflow)
+    - [Diagram](#diagram)
+  - [API](#api)
+  - [Errors](#errors)
+- [Error Handling](#error-handling)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+
+## Instantiating the Client
+```php
+<?php
+
+// Fill out the ID & Secret provided to you by your contact at Lenddo.
+$api_app_id = '';
+$api_app_secret = '';
+
+// Require the Composer autoloader
+require 'vendor/autoload.php';
+
+// Instantiate the Lenddo Service Client
+$client = new Lenddo\AuthorizeApiClient( $api_app_id , $api_app_secret );
+```
+
+## PriorityData
+### Workflow
+Priority Data may be provided at any time when enabled for your parnter script. Please communicate with your Lenddo
+representative on how to enable this feature if you require it. Priority data may be typical data (verification probes) 
+or atypical data such as credit bureau reports or proprietary data owned by your business.
+
+Data may be received at anytime before or after the user onboarding experience. When enabled for your account a user will
+not be processed until _both_ the priority data is received _and_ the user completes the onboarding process.
+
+#### Diagram
+![webhook details image](img/priority_data_workflow.png)
+
+### API
+PriorityData has the following arguments:
+
+1. **partner_script_id** - This is your partner script ID that the user will be associated with. This partner script 
+**must** have Priority Data enabled. 
+2. **application_id** - this is the client id that you're posting the token for. This must match the APPLICATION_ID that
+the user enters Authorize with. This ID is transactional and represents a single application within Lenddo.
+3. **extra_data** - This is unstructured data which may be prudent to the product output. The information and structure 
+**must** be communicated with Lenddo prior to sending it. Without this communication there is no ability to parse and understand
+the incoming data. _must be an array_
+4. **verification_data** - This is an optional argument which will allow you to send probe data with the verification object.
+    * [Read verification documentation here](verification.md)
+
+```php
+<?php
+$application_id = '20160418-130';
+
+$extra_data = array(
+	// Just a sample
+	'credit_bureau_data' => array(
+		// data here
+	)
+);
+
+$verification = new Lenddo\Verification();
+$verification->setFirstName('First Name')->setMiddleName('MN')->setLastName('Last Name');
+
+
+$response = $client->priorityData($partner_script_id, $application_id, $extra_data, $verification);
+
+// Get the Status Code for the response
+$status_code = $response->getStatusCode(); // 200
+
+// Retrieve the body of the response
+$commit_job_results = $response->getBody();
+
+$success = $status_code === 200;
+```
+
+### Errors
+* **BAD_REQUEST** _HTTP Status Code: 400_
+>    Request was malformed, or missing required data.
+    
+* **PARTNER_SCRIPT_PRIORITY_DATA_DISABLED** _HTTP Status Code 400_
+>    This occurs when the specified *PARTNER_SCRIPT_ID* does not have priority data enabled. Please contact your Lenddo Representative
+    
+* **PRIORITY_DATA_ALREADY_EXISTS** _HTTP Status Code 400_
+>    This occurs when the *PARTNER_SCRIPT_ID* and *APPLICATION_ID* combination has already had priority data submitted for it.
+    Priority data may only be submitted once per combination.
+
+* **INTERNAL_ERROR** _HTTP Status Code: 500_
+>    An internal error occurred. If this persists please contact a Lenddo Representative.
+
+## Error Handling
+You can retrieve the body of an error via the following method:
+```php
+try {
+    //.. your request code here
+} catch ( Exception $e ) {
+    $http_status = $e->getResponse()->getStatusCode(); // 400
+
+    $error_body = $e->getBody();
+}
+```
diff --git a/docs/img/priority_data_workflow.png b/docs/img/priority_data_workflow.png
diff --git a/docs/service_client.md b/docs/service_client.md
@@ -7,6 +7,7 @@ The `ServiceClient` allows partners to retrieve scoring and verification results
 
 - [Create the Lenddo REST Service Client](#create-the-lenddo-rest-service-client)
 - [Get a Score](#get-a-score)
+- [Get results for a Multiple Score model](#get-results-for-a-multiple-score-model)
 - [Get a Verification](#get-a-verification)
 - [Get an Application Decision](#get-an-application-decision)
 - [Send Extra Application Data](#send-extra-application-data)
@@ -30,8 +31,7 @@ $client = new Lenddo\ServiceClient( $id, $secret );
 ```
 
 ## Get a Score
-Please refer to the [scoring response documentation](scoring_response.md) to understand the returned 
-structure of the verification object.
+Please refer to the [scoring response documentation](scoring_response.md) to understand the returned result.
 
 To retrieve the score you'll need the application ID and the partner script ID that you used to create the application.
 
@@ -51,6 +51,33 @@ $score_value = $score_results->score;
 $score_flags = $score_results->flags;
 ```
 
+## Get results for a Multiple Score model
+To retrieve the results for a multiple score model you'll need the application ID and the partner script ID that you 
+used to create the application. Please use this if directed by your Lenddo Representative.
+
+```php
+<?php
+
+$response = $client->applicationMultipleScores('APPLICATION_ID', 'PARTNER_SCRIPT_ID');
+
+// Get the Status Code for the response
+$status_code = $response->getStatusCode(); // 200
+
+// Retrieve the body of the response
+$score_results = $response->getBody();
+
+// Return the score value and reason flags.
+$scores_array = $score_results->scores; // array of scores
+$flags = $score_results->flags; // all flags
+
+// first score result
+$score_1_model = $scores_array->scores[0]->model_id;
+$score_1_value = $scores_array->scores[0]->score;
+$score_1_flags = $scores_array->scores[0]->flags;
+$score_1_created = $scores_array->scores[0]->created;
+$score_1_features_values = $scores_array->scores[0]->feature_values;
+```
+
 ## Get a Verification
 Please refer to the [verification response documentation](https://github.com/Lenddo/php-lenddo/blob/master/docs/verification_response.md) to understand the returned 
 structure of the verification object.

diff --git a/docs/whitelabel_client.md b/docs/whitelabel_client.md
@@ -124,7 +124,7 @@ $status_code = $response->getStatusCode(); // 200
 // Retrieve the body of the response
 $commit_job_results = $response->getBody();
 
-// Get the profile ID
+// Verify the request was successful
 $success = $status_code === 200 && $commit_job_results->success = true;
 ```
 

diff --git a/src/AuthorizeApiClient.php b/src/AuthorizeApiClient.php
@@ -0,0 +1,43 @@
+<?php
+
+namespace Lenddo;
+
+use Lenddo\clients\Base;
+
+/**
+ * Class AuthorizeApiClient
+ *
+ * Used for communicating with the Authorize API. These communications usually have an impact on the product output or
+ *   user experience.
+ *
+ * @package Lenddo
+ */
+class AuthorizeApiClient extends Base
+{	protected $_hosts = array(
+		'authorize_api' => 'https://authorize-api.partner-service.link/'
+	);
+
+	/**
+	 * When enabled on a partner script a user will not be processed until priority data comes in. This data may come in
+	 *   any time before or after a user enters the Authorize Onboarding process.
+	 *
+	 * @param $partner_script_id
+	 * @param $application_id
+	 * @param $extra_data
+	 * @param Verification $verification
+	 */
+	public function priorityData($partner_script_id, $application_id, $extra_data, Verification $verification = null) {
+		if (!is_null($extra_data) && !is_array($extra_data)) {
+			throw new \InvalidArgumentException('$extra_data must either be null or an array');;
+		}
+
+		return $this->_postJSON($this->_hosts['authorize_api'], 'onboarding/prioritydata', array(
+			'partner_script_id' => $partner_script_id,
+			'application_id' => $application_id,
+			'data' => array_filter(array(
+				'verification_data' => $verification ? $verification->export() : array(),
+				'partner_data' => $extra_data
+			))
+		));
+	}
+}
diff --git a/src/ServiceClient.php b/src/ServiceClient.php
@@ -64,6 +64,20 @@ public function applicationScore($application_id, $partner_script_id)
 		));
 	}
 
+	/**
+	 * Calls the Lenddo Service with the provided client id to return a application multiple score result.
+	 * - Used when a model is assigned to a partner script which outputs multiple scores.
+	 *
+	 * @param string $application_id
+	 * @return \Lenddo\clients\guzzle_handlers\response\ResponseInterface
+	 */
+	public function applicationMultipleScores($application_id, $partner_script_id)
+	{
+		return $this->_get($this->_hosts['score_service'], 'ApplicationMultipleScores/' . $application_id, array(
+			'partner_script_id' => $partner_script_id
+		));
+	}
+
 	/**
 	 * @param $application_id - This is your unique application id.
 	 * @param $partner_script_id - This is the partner script ID that you created this application with.