Merge pull request #316 from swan-io/DOC-1024/merchant-doc-updates

DOC-1024 Merchant doc updates

Author: ntombing

docs/topics/merchants/index.mdx

@@ -10,10 +10,13 @@ import MerchantsDefinition from '../definitions/_merchants.mdx';
 
 ## Overview {#overview}
 
+Merchants are users who want to accept payments by card, SEPA Direct Debit, Internal Direct Debit, or French checks, either directly from a payment link or an invoice. 
+This includes contractors, healthcare professionals, artisans, and business owners, among others.
+
 With a merchant profile and at least one active merchant payment method, you can help your merchants accept payments with Swan.
 
 :::info Pending review
-Before accepting payments, you and your merchant need to complete a risk review.
+Before accepting payments, you need to complete a risk review.
 To get started, contact your dedicated Technical Account Manager, or send an email to [email protected].
 :::
 
@@ -26,7 +29,8 @@ You might be contacted for more information before Swan accepts or rejects the r
 
 To manage potential risk, if suspicious activity is detected, Swan can **change the status** of both **profiles and payment methods** to `Suspended` or `Rejected`.
 Swan can also reinstate a profile or payment method by changing the status to `Enabled`.
-Finally, if Swan assigns the status `Rejected` to a profile or payment method, the decision is final and can't be reversed.
+Finally, if Swan assigns the status `Rejected` to a profile or payment method, the decision is final and can't be reversed. 
+The user must create a new request, which Swan will review as a separate submission.
 
 ### Webhooks {#webhooks}
 
@@ -60,26 +64,39 @@ flowchart LR
 | Profile status | Explanation |
 |---|---|
 | `PendingReview` | Profile or payment method request or update was submitted and is pending a review by Swan.<br /><br />**Next steps**: <ul><li>If the request or update doesn't meet requirements or is deemed risky by Swan, the status moves directly to `Rejected`.</li><li>Otherwise, the status moves to `Enabled`.</li></ul> |
-| `Enabled` | Profile or payment method is active.<br /><br /><ul><li>Use `Enabled` merchant profiles to request payment methods and accept payments with activated payment methods.</li><li>Use `Enabled` payment methods to accept payments.</li><li>Updates to profiles and payment methods can only occur when they have the status `Enabled`.</li></ul> |
+| `Enabled` | Profile or payment method is active.<br /><br /><ul><li>Use `PendingReview` merchant profiles to request payment methods and accept payments with activated payment methods.</li><li>Use `Enabled` payment methods to accept payments.</li><li>Updates to profiles and payment methods can only occur when they have the status `Enabled`.</li></ul> |
 | `Suspended` | Status **assigned by Swan** when the merchant's use of their profile or payment method needs to be reviewed. The status can't return to `Enabled` without a review. |
 | `Rejected` | Final status **assigned by Swan** when Swan decides the risk of this profile or the risk of this payment method for the associated merchant is too high, or for some other risk-related reason. |
 | `Disabled` | Final status **set by you** using the `requestMerchantPaymentMethods` mutation. |
 
 ## Merchant profiles {#profiles}
 
-A **merchant profile** is a collection of business, risk, and support information that fulfills two primary requirements: **approve the account holder** as a merchant, and **facilitate accepting payments** with Swan.
+A **merchant profile** is a collection of business, risk, and support information that fulfills two primary requirements: 
+
+1. **Approve the account holder** as a merchant.
+1. **Facilitate accepting payments** with Swan. 
+
+If a Swan account holder wants to accept payments from customers, they must have at least one merchant profile.
 
-The merchant profile contains the following information:
+Your users can create merchant profiles during onboarding, but only if you've requested the feature for them.
+Since merchants are considered high risk, merchant profiles should only be requested for users who qualify and will accept payments.
+Requesting merchant profiles for users that don't qualify may create false expectations about available features.
 
-- Business details
-- Description of the business activity
-- Link to the merchant's website
-- Projected volumes
-- Logo (optional), displayed online and on mandate PDFs
-- Accent color
+A merchant profile contains the following information:
 
-A merchant profile is required of all Swan account holders wanting to accept payments from customers.
-If you want to accept payments from customers, you must have at least one merchant profile.
+1. Business details
+1. Description of the business activity
+1. Link to the merchant's website or social network
+1. Projected volumes
+1. Payment frequency
+1. Logo (optional), in `.png` format and less than 1 MB. It's shown online and on the PDF of the payment mandate.
+1. Accent color
+1. Customer region
+
+:::tip 
+To speed up **merchant profile enablement**, complete as many input fields as possible.  
+Providing your `customerRegion`, `paymentFrequency`, and at least a `socialNetwork` or `merchantWebsite` can reduce turnaround time.
+:::
 
 The merchant profile is created with the status `PendingReview`, and is visible right away on your Dashboard.
 
@@ -94,7 +111,11 @@ Updating a merchant profile produces the following events:
 1. The [**merchant profile status**](#statuses) doesn't change, remaining `Enabled`. The merchant continues to use their merchant profile with the existing information.
 1. The **update status** is `PendingReview`. Swan reviews the new information to ensure it meets requirements. 
 1. After Swan reviews and validates the update request, the update status changes to `Enabled` and the update is published to the merchant profile.
-1. If Swan rejects the update request, the merchant profile remains `Enabled`, but with the existing information. The update isn't published.
+1. If Swan rejects the update request, the merchant profile remains `Enabled` by default, unless Swan decides otherwise. 
+The merchant profile status doesn't change.
+
+When a merchant payment method is requested, Swan may ask for additional information even if the merchant profile is already `Enabled`.
+Swan will contact you or your user directly, based on your communication preferences.
 
 If you requested an update and your update status is `PendingReview`, but you need to **make another change**, submit a new update request.
 Swan reviews both requests, but only the most recent is made public. 

docs/topics/merchants/partials/_webhooks.mdx

@@ -1,4 +1,4 @@
 :::info Webhook notification
 Go to your **Dashboard** > **Developers** > **Webhooks** to subscribe to the `MerchantPaymentMethod` [webhook](../../../developers/using-api/webhooks.mdx) and receive a notification when the [status](../index.mdx#statuses) of your request changes. 
-You'll be notified when changes are made to the rolling reserve and payment amount limit. 
+You'll also be notified when changes are made to the rolling reserve and payment amount limit. 
 :::

docs/topics/merchants/profiles/guide-request.mdx

@@ -23,6 +23,10 @@ Swan might contact you for more information before accepting or rejecting the me
 1. The new merchant is created with the status `PendingReview`.
 1. Swan [reviews the new merchant profile](../index.mdx#risk) and updates the status.
 
+:::tip 
+Provide your `customerRegion`, `paymentFrequency`, and at least one `socialNetwork` or `merchantWebsite` to speed up **merchant profile enablement**.
+:::
+
 ## Mutation {#mutation}
 
 <a href="https://explorer.swan.io?query=bXV0YXRpb24gTWVyY2hhbnRQcm9maWxlIHsKICByZXF1ZXN0TWVyY2hhbnRQcm9maWxlKAogICAgaW5wdXQ6IHsKICAgICAgYWNjb3VudElkOiAiJFlPVVJfQUNDT1VOVF9JRCIKICAgICAgbWVyY2hhbnROYW1lOiAiTWVyY2hhbnQgQ29tcGFueSBOYW1lIgogICAgICBwcm9kdWN0VHlwZTogR29vZHMKICAgICAgZXhwZWN0ZWRNb250aGx5UGF5bWVudFZvbHVtZTogeyB2YWx1ZTogIjMwMDAiLCBjdXJyZW5jeTogIkVVUiIgfQogICAgICBleHBlY3RlZEF2ZXJhZ2VCYXNrZXQ6IHsgdmFsdWU6ICI1MCIsIGN1cnJlbmN5OiAiRVVSIiB9CiAgICB9CiAgKSB7CiAgICAuLi4gb24gUmVxdWVzdE1lcmNoYW50UHJvZmlsZVN1Y2Nlc3NQYXlsb2FkIHsKICAgICAgX190eXBlbmFtZQogICAgICBtZXJjaGFudFByb2ZpbGUgewogICAgICAgIGFjY291bnRJZAogICAgICAgIGlkCiAgICAgICAgc3RhdHVzSW5mbyB7CiAgICAgICAgICBzdGF0dXMKICAgICAgICAgIC4uLiBvbiBFbmFibGVkTWVyY2hhbnRQcm9maWxlU3RhdHVzSW5mbyB7CiAgICAgICAgICAgIF9fdHlwZW5hbWUKICAgICAgICAgICAgZW5hYmxlZEF0CiAgICAgICAgICAgIHN0YXR1cwogICAgICAgICAgfQogICAgICAgIH0KICAgICAgICBwcm9kdWN0VHlwZQogICAgICB9CiAgICB9CiAgICAuLi4gb24gRm9yYmlkZGVuUmVqZWN0aW9uIHsKICAgICAgX190eXBlbmFtZQogICAgICBtZXNzYWdlCiAgICB9CiAgICAuLi4gb24gQWNjb3VudE5vdEZvdW5kUmVqZWN0aW9uIHsKICAgICAgaWQKICAgICAgbWVzc2FnZQogICAgfQogICAgLi4uIG9uIEludGVybmFsRXJyb3JSZWplY3Rpb24gewogICAgICBfX3R5cGVuYW1lCiAgICAgIG1lc3NhZ2UKICAgIH0KICAgIC4uLiBvbiBWYWxpZGF0aW9uUmVqZWN0aW9uIHsKICAgICAgX190eXBlbmFtZQogICAgICBtZXNzYWdlCiAgICAgIGZpZWxkcyB7CiAgICAgICAgY29kZQogICAgICAgIG1lc3NhZ2UKICAgICAgICBwYXRoCiAgICAgIH0KICAgIH0KICB9Cn0K&tab=api" className="explorer-badge">Open in API Explorer</a>

docs/topics/merchants/sandbox.mdx

@@ -10,19 +10,23 @@ When testing your integration, you might need to simulate certain events with th
 
 ### Simulate updating merchant profile status {#simulate-profile-status}
 
-In Sandbox only, you need to update the merchant profile status to `Enabled`.
+In Sandbox, you need to update the merchant profile status to `Enabled`.
 
 1. Open your Swan Dashboard.
 1. Go to **Developers** > **Event Simulator**.
-1. Go to **Merchant payments**.
+1. Go to **Merchant profiles**.
 1. Go to the tab to update the merchant profile status.
 1. Change the merchant profile status to `Enabled`.
 
+:::info Testing API
+You can simulate enabling or updating a merchant profile using the `simulateMerchantProfileRequestOutcome` and `simulateMerchantProfileUpdateRequestOutcome` mutations in the Testing API.
+:::
+
 ## Merchant payment methods {#simulate-payment-method}
 
 ### Simulate updating merchant payment method status {#simulate-payment-method-status}
 
-In Sandbox only, you need to update the merchant payment method status to `Enabled`.
+In Sandbox, you need to update the merchant payment method status to `Enabled`.
 
 1. Open your Swan Dashboard.
 1. Go to **Developers** > **Event Simulator**.
@@ -32,32 +36,42 @@ In Sandbox only, you need to update the merchant payment method status to `Enabl
 
 ### Simulate enabling a payment method {#simulate-payment-method-enable}
 
-You can also use the **Partner Testing API**.
+You can also use the **Testing API** to simulate updating a merchant payment method.
+
+#### Guide {#guide}
+
+1. Call the `simulateMerchantPaymentMethodRequestOutcome` mutation (line 2).
+1. Add the `merchantPaymentMethodId` (line 4).
+1. Add `merchantPaymentMethodStatus` and select `Enabled` (line 5).
+1. Select the payment method type you want to simulate, for example `SepaDirectDebitB2BMerchantPaymentMethod`. (line 8).
+1. Add relevant rejection details to your mutation (lines 11 and 14).
+
+:::info Testing API
+Use the `simulateMerchantPaymentMethodUpdateRequestOutcome` mutation to simulate updating the merchant payment method.
+:::
 
-- Line 4: Enter the corresponding `merchantProfileId`.
-- Line 5: Choose the `methodType` you'd like to simulate activating.
+#### Mutation {#mutation}
 
-```graphql {4-5} showLineNumbers
+<a href="https://explorer.swan.io?query=bXV0YXRpb24gRW5hYmxlUGF5bWVudE1ldGhvZCB7CiAgc2ltdWxhdGVNZXJjaGFudFBheW1lbnRNZXRob2RSZXF1ZXN0T3V0Y29tZSgKICAgIGlucHV0OiB7CiAgICAgIG1lcmNoYW50UGF5bWVudE1ldGhvZElkOiAiJFlPVVJfUEFZTUVOVF9NRVRIT0RfSUQiCiAgICAgIG1lcmNoYW50UGF5bWVudE1ldGhvZFN0YXR1czogRW5hYmxlZAogICAgfQogICkgewogICAgLi4uIG9uIFNlcGFEaXJlY3REZWJpdEIyQk1lcmNoYW50UGF5bWVudE1ldGhvZCB7CiAgICAgIGlkCiAgICB9CiAgICAuLi4gb24gTm90Rm91bmRSZWplY3Rpb24gewogICAgICBtZXNzYWdlCiAgICB9CiAgICAuLi4gb24gTWVyY2hhbnRQYXltZW50TWV0aG9kV3JvbmdTdGF0dXNSZWplY3Rpb24gewogICAgICBfX3R5cGVuYW1lCiAgICAgIG1lc3NhZ2UKICAgIH0KICB9Cn0K&tab=test-api" className="explorer-badge">Open Testing API</a>
+
+```graphql {2,4-5,8,11,14} showLineNumbers
 mutation EnablePaymentMethod {
-  simulateUpdateMerchantProfile(
+  simulateMerchantPaymentMethodRequestOutcome(
     input: {
-      merchantProfileId: "$YOUR_MERCHANT_PROFILE_ID"
-      merchantPaymentMethod: { methodType: $METHOD_TYPE, status: Enabled }
+      merchantPaymentMethodId: "$YOUR_PAYMENT_METHOD_ID"
+      merchantPaymentMethodStatus: Enabled
     }
   ) {
-    ... on SimulateUpdateMerchantProfileSuccessPayload {
-      __typename
+    ... on SepaDirectDebitB2BMerchantPaymentMethod {
+      id
     }
     ... on NotFoundRejection {
-      id
+      message
     }
-    ... on MerchantProfileWrongStatusRejection {
+    ... on MerchantPaymentMethodWrongStatusRejection {
       __typename
+      message
     }
   }
 }
-```
-
-:::caution SEPA Direct Debit
-For SEPA Direct Debit, you can *only* use the Partner Testing API to update the status of your payment methods.
-:::
+```