Skip to content

DOC-1024 Merchant doc updates #316

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 35 additions & 14 deletions docs/topics/merchants/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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].
:::

Expand All @@ -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}

Expand Down Expand Up @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I’d recommend giving more information about size and format of the logo.

Did they forget to tell you about the size or cancel the min/max pixels size requirement? I see nothing else in Notion

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It was previously "Logo (optional), displayed online and on mandate PDFs".
I updated it to "less than 1 MB" - no other sizing requirements were shared. The min/max pixels size are not necessary to publish this. We can update the doc when these are defined.

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 one `socialNetwork` or `merchantWebsite` can reduce turnaround time.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Providing your `customerRegion`, `paymentFrequency`, and at least one `socialNetwork` or `merchantWebsite` can reduce turnaround time.
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.

Expand All @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion docs/topics/merchants/partials/_webhooks.mdx
Original file line number Diff line number Diff line change
@@ -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.
:::
4 changes: 4 additions & 0 deletions docs/topics/merchants/profiles/guide-request.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
52 changes: 33 additions & 19 deletions docs/topics/merchants/sandbox.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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**.
Expand All @@ -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.
:::
```