Dwolla · ShreyaThapa · Feb 21, 2024 · Feb 21, 2024 · Feb 21, 2024
diff --git a/pages/changelog.mdx b/pages/changelog.mdx
@@ -12,15 +12,22 @@ Keep up to date on new product features and enhancements, API docs, tools change
 
 ## Upcoming
 
-### 2023-08-31
+## Completed
 
-**SUNSET**
+### 2024-02-20
 
-- Dwolla will be retiring the `dwolla.js` library, which supports adding an unverified bank funding source. Check out the official [announcement](https://discuss.dwolla.com/t/may-2023-updates-retiring-dwolla-s-client-side-javascript-library-dwolla-js/8969).
-- The legacy dwolla.js will be replaced with functionality that has been added to our [Drop-in Components library](/concepts/drop-in-components#latest-v220). This library will serve as our primary web UI components library and offer an enhanced developer experience. Please refer to our [migration guide](https://discuss.dwolla.com/t/migration-guide-dwolla-js-to-dwolla-web-js/8968) for more details, including alternative solutions.
-- The following API endpoints will be removed as part of the sunset: `/customers/{id}/iav-token` and `/customers/{id}/funding-sources-token`.
+**ADDED**
 
-## Completed
+- Added a new `retry-with-full-ssn` link to the Customer resource. This link appears whenever retry information is required for the Controller in order to verify the business verified Customer.
+- Check out our [Developer documentation](https://developers.dwolla.com/docs/balance/business-verified-customer/handle-verification-statuses#handling-retry-status) for more information.
+
+### 2024-01-11
+
+**SUNSET**
+
+- Dwolla has retired the `dwolla.js` library, which supported adding an unverified bank funding source. Check out the official [announcement](https://discuss.dwolla.com/t/may-2023-updates-retiring-dwolla-s-client-side-javascript-library-dwolla-js/8969).
+- The legacy dwolla.js has been replaced with functionality that has been added to our [Drop-in Components library](/concepts/drop-in-components#latest-v220). This library will serve as our primary web UI components library and offer an enhanced developer experience. Please refer to our [migration guide](https://discuss.dwolla.com/t/migration-guide-dwolla-js-to-dwolla-web-js/8968) for more details, including alternative solutions.
+- The following API endpoints are removed as part of the sunset: `/customers/{id}/iav-token` and `/customers/{id}/funding-sources-token`.
 
 ### 2023-05-15
 
@@ -265,9 +272,9 @@ Keep up to date on new product features and enhancements, API docs, tools change
 
 - New version of C# SDK.
 - Breaking changes:
-  - DwollaClient no longer throws on API errors, they should be properly deserialized into RestResponse.Error instead.
-  - DwollaException, RestException, and RestResponse.Exception are removed.
-  - Use `EmptyResponse` instead of `object` in DwollaClient interface.
+- DwollaClient no longer throws on API errors, they should be properly deserialized into RestResponse.Error instead.
+- DwollaException, RestException, and RestResponse.Exception are removed.
+- Use `EmptyResponse` instead of `object` in DwollaClient interface.
 - Check it out on our [Github](https://github.com/Dwolla/dwolla-v2-csharp)
 
 ### 2018-05-11

diff --git a/pages/docs/balance/business-verified-customer/handle-verification-statuses.mdx b/pages/docs/balance/business-verified-customer/handle-verification-statuses.mdx
@@ -36,18 +36,105 @@ As a developer, you will want to handle the various Customer statuses that can b
 
 ## Handling `retry` status
 
-A `retry` status occurs when a Customer’s identity scores are too low during the initial verification attempt. Dwolla will require the **full 9-digits** of the Controller’s SSN on the retry attempt in order to give our identity vendor more information in an attempt to receive a sufficient score to approve the Customer account. The Customer will have one more opportunity to correct any mistakes.
+A `retry` status occurs when a Customer’s identity scores are too low during a verification attempt. Typically, a `retry` status occurs after the initial creation of a business-verified customer, however, a customer can also be placed into a retry status via the Dwolla Dashboard if the customer is in a `document` status. When the customer is in the `retry` status, your application needs to re-initiate the verification process by prompting the user via a form to resubmit their identifying information.
 
 <AlertBar variation="warning">
   You need to gather new information if the Customer is placed into the{" "}
-  <code>retry</code>
-  status; simply passing the same information will result in the same insufficient
-  scores.
+  <code>retry</code> status; simply passing the same information will result in
+  the same insufficient scores.
 </AlertBar>
 
-All fields that were required in the initial Customer creation attempt will be required in the retry attempt, along with the full 9-digit SSN.
+### Determining information needed to retry verification
 
-### Sole Proprietorship - Request and response
+When a business verified Customer is placed in the `retry` verification status, Dwolla will return a link in the API response after [retrieving a Customer](https://developers.dwolla.com/docs/balance/api-reference/customers/retrieve). The retry link contained within the `_links` object of the response helps your application determine if a retry is needed and what type of retry is required. What data you need to request from the customer depends on the retry scenario:
+
+- **Business-only retry**: A `retry-verification` link is returned. Include all fields required during initial customer but **omit** Controller information. For business verified Customers with Controllers, different links can be returned depending on whether retry is needed for just the business, or both the Controller and business.
+
+- **Controller and business retry**: A `retry-with-full-ssn` link is returned. If the Controller information needs to be retried, all fields that were required in the initial Customer creation attempt will be required in the retry attempt, along with **the full 9-digit SSN** of the Controller in order to give our identity vendor more information in an attempt to receive a sufficient score to approve the Customer account ([see example request below](#business-with-controller-retry-with-full-ssn---request-and-response)).
+
+#### Understanding \_embedded errors
+
+Additionally, `_embedded` errors are included in the Customer resource which include information about the next steps required to get the Customer verified (see example response below). Refer to the table below for the list of possible links and their descriptions.
+
+| Link name           | Description                                                                     |
+| ------------------- | ------------------------------------------------------------------------------- |
+| retry-verification  | Identifies if retry information is needed for the business.                     |
+| retry-with-full-ssn | Identifies if retry information is needed for both the Controller and business. |
+
+#### Example response
+
+```json
+{
+  "_links": {
+    "self": {
+      "href": "https://api-sandbox.dwolla.com/customers/20c2d8e2-8ccf-42fd-bd9e-757c396f342d",
+      "type": "application/vnd.dwolla.v1.hal+json",
+      "resource-type": "customer"
+    },
+    "retry-verification": {
+      "href": "https://api-sandbox.dwolla.com/customers/20c2d8e2-8ccf-42fd-bd9e-757c396f342d",
+      "type": "application/vnd.dwolla.v1.hal+json",
+      "resource-type": "customer"
+    },
+    "retry-with-full-ssn": {
+      "href": "https://api-sandbox.dwolla.com/customers/20c2d8e2-8ccf-42fd-bd9e-757c396f342d",
+      "type": "application/vnd.dwolla.v1.hal+json",
+      "resource-type": "customer"
+    }
+  },
+  "_embedded": {
+    "errors": [
+      {
+        "code": "Required",
+        "message": "Full SSN required",
+        "path": "",
+        "_links": {
+          "retry-with-full-ssn": {
+            "href": "https://api-sandbox.dwolla.com/customers/20c2d8e2-8ccf-42fd-bd9e-757c396f342d",
+            "type": "application/vnd.dwolla.v1.hal+json",
+            "resource-type": "customer"
+          }
+        }
+      }
+    ]
+  },
+  "id": "20c2d8e2-8ccf-42fd-bd9e-757c396f342d",
+  "firstName": "Account",
+  "lastName": "Admin",
+  "email": "[email protected]",
+  "type": "business",
+  "status": "retry",
+  "created": "2024-02-20T22:53:00.727Z",
+  "address1": "9876 Million Dollar St",
+  "address2": "Unit 123",
+  "city": "Des Moines",
+  "state": "IA",
+  "postalCode": "50265",
+  "phone": "5555555555",
+  "businessName": "Jane Corp",
+  "doingBusinessAs": "This is the DBA name",
+  "website": "https://www.dwolla.com",
+  "correlationId": "CID-bc3b6cd8-fca0-471d-b6f2-4b10abb20956",
+  "controller": {
+    "firstName": "Jane",
+    "lastName": "Doe",
+    "title": "CEO",
+    "address": {
+      "address1": "1749 18th st",
+      "address2": "apt 12",
+      "address3": "Ste 123",
+      "city": "Des Moines",
+      "stateProvinceRegion": "IA",
+      "country": "US",
+      "postalCode": "50266"
+    }
+  },
+  "businessType": "llc",
+  "businessClassification": "9ed38155-7d6f-11e3-83c3-5404a6144203"
+}
+```
+
+### Sole Proprietorship (`retry-verification`) - Request and response
 
 ```bash
 POST https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5
@@ -174,7 +261,121 @@ dwolla.post(customerUrl, requestBody).then(function (res) {
 });
 ```
 
-### Business with Controller - Request and response
+### Business with Controller (`retry-verification`) - Request and response
+
+```bash
+POST https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5
+Content-Type: application/vnd.dwolla.v1.hal+json
+Accept: application/vnd.dwolla.v1.hal+json
+Authorization: Bearer 0Sn0W6kzNic+oWhDbQcVSKLRUpGjIdl/YyrHqrDDoRnQwE7Q
+
+{
+    "firstName": "Jane",
+    "lastName": "Merchant",
+    "email": "[email protected]",
+    "ipAddress": "143.156.7.8",
+    "type": "business",
+    "address1": "123 Corrected Address St",
+    "city": "Some City",
+    "state": "NY",
+    "postalCode": "11101",
+    "businessClassification": "9ed3f670-7d6f-11e3-b1ce-5404a6144203",
+    "businessType": "llc",
+    "businessName":"Jane Corp",
+    "ein":"00-0000000"
+}
+```
+
+```php
+<?php
+$customersApi = new DwollaSwagger\CustomersApi($apiClient);
+$customerUrl = 'https://api-sandbox.dwolla.com/customers/b70c3194-35fa-49e8-9243-d55a30e06d1e';
+$retryCustomer = $customersApi->updateCustomer([
+  'firstName' => 'Jane',
+  'lastName' => 'Merchant',
+  'email' => '[email protected]',
+  'type' => 'business',
+  'address1' => '123 Corrected Address St',
+  'city' => 'Some City',
+  'state' => 'NY',
+  'postalCode' => '11101',
+  'phone' => '5554321234',
+  'businessClassification' => '9ed3f670-7d6f-11e3-b1ce-5404a6144203',
+  'businessType' => 'llc',
+  'businessName' => 'Jane Corp',
+  'ein' => '00-0000000'], $customerUrl);
+
+?>
+```
+
+```ruby
+# Using DwollaV2 - https://github.com/Dwolla/dwolla-v2-ruby (Recommended)
+customer_url = 'https://api.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5'
+request_body = {
+  :firstName => 'Jane',
+  :lastName => 'Merchant',
+  :email => '[email protected]',
+  :type => 'business',
+  :address1 => '123 Corrected Address St',
+  :city => 'Some City',
+  :state => 'NY',
+  :postalCode => '11101',
+  :businessClassification => '9ed38155-7d6f-11e3-83c3-5404a6144203',
+  :businessType => 'llc',
+  :businessName => 'Jane Corp',
+  :ein => '12-3456789'
+}
+
+customer = app_token.post customer_url, request_body
+customer.id # => "62c3aa1b-3a1b-46d0-ae90-17304d60c3d5"
+```
+
+```python
+# Using dwollav2 - https://github.com/Dwolla/dwolla-v2-python (Recommended)
+customer_url = 'https://api.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5'
+request_body = {
+  'firstName': 'Jane',
+  'lastName': 'Merchant',
+  'email': '[email protected]',
+  'type': 'business',
+  'address1': '123 Corrected Address St',
+  'city': 'Some City',
+  'state': 'NY',
+  'postalCode': '11101',
+  'businessClassification': '9ed38155-7d6f-11e3-83c3-5404a6144203',
+  'businessType': 'llc',
+  'businessName': 'Jane Corp',
+  'ein': '12-3456789'
+}
+
+customer = app_token.post(customer_url, request_body)
+customer.body.id # => '62c3aa1b-3a1b-46d0-ae90-17304d60c3d5'
+```
+
+```javascript
+var customerUrl =
+  "https://api.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5";
+var requestBody = {
+  firstName: "Jane",
+  lastName: "Merchant",
+  email: "[email protected]",
+  type: "business",
+  address1: "123 Corrected Address St",
+  city: "Some City",
+  state: "NY",
+  postalCode: "11101",
+  businessClassification: "9ed38155-7d6f-11e3-83c3-5404a6144203",
+  businessType: "llc",
+  businessName: "Jane Corp",
+  ein: "12-3456789",
+};
+
+dwolla.post(customerUrl, requestBody).then(function (res) {
+  res.body.id; // => '62c3aa1b-3a1b-46d0-ae90-17304d60c3d5'
+});
+```
+
+### Business with Controller (`retry-with-full-ssn`) - Request and response
 
 ```bash
 POST https://api-sandbox.dwolla.com/customers/62c3aa1b-3a1b-46d0-ae90-17304d60c3d5

diff --git a/pages/docs/balance/testing/customers.mdx b/pages/docs/balance/testing/customers.mdx
@@ -31,12 +31,32 @@ There are various reasons a [Verified Customer](/concepts/customer-types#verifie
 
 In production, Dwolla will place the Verified Customer in either the `retry`, `kba`, `document`, `verified`, or `suspended` state of verification after an initial identity verification check.
 
-**For personal Verified Customers**, reference the guide on [customer verification](/guides/personal-verified-customer/handle-verification-statuses) for more information on handling identity verification for Verified Customers. To simulate the various statuses in the Sandbox, submit either `verified`, `retry`, `kba`, `document`, or `suspended` in the **firstName** parameter in order to [create a new Verified Customer](https://developers.dwolla.com/api-reference/customers/create#verified-personal-customer---request-parameters) with that status.
+**For personal Verified Customers**: Reference the guide on [customer verification](https://developers.dwolla.com/docs/balance/personal-verified-customer) for more information on handling identity verification for Verified Customers. To simulate the various statuses in the Sandbox, supply either `verified`, `retry`, `kba`, `document`, or `suspended` in the **firstName** parameter in order to [create a new Verified Customer](https://developers.dwolla.com/docs/balance/api-reference/customers/create#verified-personal-customer---request-parameters) with that status.
 
-**For business Verified Customers**, reference the guide on [customer verification](/guides/business-verified-customer/create-a-customer) that goes over information on properly verifying a business's Controller, the business and associated Beneficial Owners. To simulate the various statuses in the Sandbox, submit either `verified`, `retry`, or `suspended` in the **controller firstName** parameter in order to [create a new Verified Customer](https://developers.dwolla.com/api-reference/customers/create#verified-business-customer-businesstypellc-corporation-or-partnership---request-parameters) with that status. To simulate different verification status for Beneficial Owners, submit either `incomplete` or `document` in the **beneficial owner firstName** parameter.
+**For business Verified Customers**: Reference the guide on [customer verification](https://developers.dwolla.com/docs/balance/business-verified-customer) that goes over information on properly verifying a business's Controller, the business, and associated Beneficial Owners.
 
-With business Verified Customers, documents may be needed for the Controller, the business, or both the Controller and business. To simulate the `document` status for the controller, submit `document` in the **controller firstName** parameter.
-Similarly, to simulate the `document` status for the business, submit `document` in the **businessName** parameter. To simulate both the Controller and the business in `document`, submit `document` in both the **controller firstName** and the **businessName** parameters.
+Here's how to simulate the different statuses and verification links for business Verified Customers in Sandbox:
+
+`retry` status:
+
+- For the business - Supply `retry` in the **businessName** parameter. This action will return a `retry-verification` link in the Customer resource.
+
+- For both the Controller and business - Supply `retry` in the **controller firstName** parameter. This action will return both a `retry-verification` link and a `retry-with-full-ssn` link in the Customer resource.
+
+`document` status:
+
+- For the controller - Supply `document` in the **controller firstName** parameter. This action will return a `verify-with-document` linkin the Customer resource.
+
+- For the business - Supply `document` in the **businessName** parameter. This action will return a `verify-business-with-document` link in the Customer resource.
+
+- For both the Controller and the business - Submit `document` in both the **controller firstName** and the **businessName** parameters. This action will return a `verify-controller-and-business-with-document` link in the Customer resource.
+
+`suspended`:
+
+- Supply `suspended` in the **controller firstName** parameter to create a new Verified Customer with that status.
+
+**For beneficial owners**:
+To simulate different verification statuses for Beneficial Owners, submit either `incomplete` or `document` in the **beneficial owner firstName** parameter.
 
 ### Simulate KBA verified and failed events