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

Merged
merged 7 commits into from
Jul 25, 2025
Merged

DOC-1024 Merchant doc updates #316

merged 7 commits into from
Jul 25, 2025

Conversation

ntombing
Copy link
Contributor

Merchant overview page ready for review. Still need to update the guides.

@ntombing ntombing requested a review from racene-swan May 28, 2025 13:59
Copy link

linear bot commented May 28, 2025

Copy link

netlify bot commented May 28, 2025

Deploy Preview for incomparable-tiramisu-91a96a ready!

Name Link
🔨 Latest commit f725951
🔍 Latest deploy log https://app.netlify.com/projects/incomparable-tiramisu-91a96a/deploys/688255e976fc18000809ad35
😎 Deploy Preview https://deploy-preview-316--incomparable-tiramisu-91a96a.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

| `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: **approve the account holder** as a merchant, and **facilitate accepting payments** with Swan.
Copy link
Contributor

Choose a reason for hiding this comment

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

This should be in a numbered list.

Copy link
Contributor

Choose a reason for hiding this comment

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

Hey this is still not in a numbered list? i.e.

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.
  2. Facilitate accepting payments with Swan.

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.
If a Swan account holder wants to accept payments from customers, they must have at least one merchant profile.

Merchant profiles can be created at the same time as onboarding.
Copy link
Contributor

Choose a reason for hiding this comment

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

same time as an onboarding? Or simultaneously with onboarding?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

When onboarding is Ongoing Invalid or Valid but not yet Finalized. As soon as they've filled out the form, they're able to see the merchant profile request in their banking app (if the partner has requested the feature for them).

If a Swan account holder wants to accept payments from customers, they must have at least one merchant profile.

Merchant profiles can be created at the same time as onboarding.
Since merchants are considered high risk, profiles should only be created for users who need merchant features.
Copy link
Contributor

Choose a reason for hiding this comment

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

high-risk - what do we mean by "users who need merchant features" - this is unclear since this whole section is about Merchant profiles.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

This is just a warning to ensure merchant features are only given to users who genuinely need them. Technically, partners can create merchant profiles for all users with company accounts, but this risks exposing the feature to users who aren't merchants and don't accept payments - which may cause problems later on.


Merchant profiles can be created at the same time as onboarding.
Since merchants are considered high risk, profiles should only be created for users who need merchant features.
Requesting profiles for all users may lead to unmet expectations.
Copy link
Contributor

Choose a reason for hiding this comment

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

What do we mean by this? will it be rejected? what's the user impact here?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I've explained this in the previous comment.

- Projected volumes
- Logo (optional), displayed online and on mandate PDFs
- Payment frequency
- Logo (optional), in `.png` format and less than 1 mb, displayed online and on mandate PDFs
Copy link
Contributor

Choose a reason for hiding this comment

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

Do we mean 1Mb or MB?

Copy link
Contributor

Choose a reason for hiding this comment

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

What's a mandate PDF?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

We mean 1 MB.

A PDF of a payment mandate.


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.
To speed up enabling your merchant profile, complete as many information fields as possible.
Copy link
Contributor

Choose a reason for hiding this comment

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

Rework this sentence - it's clunky.

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 the you or the user directly, based on your communication preferences.
Copy link
Contributor

Choose a reason for hiding this comment

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

Swan will contact you or the user directly

Copy link
Contributor

@racene-swan racene-swan left a comment

Choose a reason for hiding this comment

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

Left comments directly here :)

@ntombing ntombing force-pushed the DOC-1024/merchant-doc-updates branch 2 times, most recently from e8850ea to 6f462a6 Compare July 15, 2025 13:32
@ntombing ntombing requested a review from racene-swan July 16, 2025 08:55
If a Swan account holder wants to accept payments from customers, they must have at least one merchant profile.

Users can create merchant profiles during onboarding, but only if you've requested the feature for them.
Since merchants are considered high risk, request merchant profiles only for users who qualify and will accept payments.
Copy link
Contributor

Choose a reason for hiding this comment

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

Since merchants are considered high-risk, merchant profiles should only be requested for users who qualify and will accept payments.

What are the other qualifications? Is the only qualification that they accept payments?

Copy link
Contributor Author

@ntombing ntombing Jul 22, 2025

Choose a reason for hiding this comment

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

No, it's not the only one.

To qualify for a merchant profile, the user must:

  • Be an account holder for a company account.
  • They must be approved as a merchant.
  • They're engaging in an activity that involves accepting payments from end users.

Not all company accounts qualify to accept payments. Some only perform transactions and account management actions (e.g., managing beneficiaries), similar to individual accounts. Final approval depends on Swan’s risk review, which includes checks on other qualifications.


Users can create merchant profiles during onboarding, but only if you've requested the feature for them.
Since merchants are considered high risk, request merchant profiles only for users who qualify and will accept payments.
Requesting merchant profiles for ineligible users may create false expectations about available features.
Copy link
Contributor

Choose a reason for hiding this comment

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

We use the term qualify above, and here we use eligible - pick one term and use it consistently.


Users can create merchant profiles during onboarding, but only if you've requested the feature for them.
Since merchants are considered high risk, request merchant profiles only for users who qualify and will accept payments.
Requesting merchant profiles for ineligible users may create false expectations about available features.

The merchant profile contains the following information:
Copy link
Contributor

Choose a reason for hiding this comment

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

A merchant profile?

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 the user directly, based on your communication preferences.
Copy link
Contributor

Choose a reason for hiding this comment

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

user as in end user?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Yes. Yes, we're referring to the partner’s users, our end users. Noted this to discuss, may need to define and adjust throughout the docs. Happy to leave this as is for now.

Copy link
Contributor

@racene-swan racene-swan left a comment

Choose a reason for hiding this comment

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

A couple more changes

@ntombing ntombing force-pushed the DOC-1024/merchant-doc-updates branch from 93d70a1 to 8346ad5 Compare July 22, 2025 05:22
@ntombing ntombing requested a review from racene-swan July 22, 2025 09:58
Copy link
Contributor

@max-koro max-koro left a comment

Choose a reason for hiding this comment

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

Great stuff! Your writing quality is impeccable, I have no suggestions :)

Quick question in addition to the ones below:

typical implementations of payment links include the ability to add a payment link in an invoice, share it via QR Code, or email or SMS
-> Was this requirement cancelled?

1. Accent color
1. Customer region

Complete as many information fields as possible to decrease the turnaround time for enabling the merchant profile.
Copy link
Contributor

@max-koro max-koro Jul 22, 2025

Choose a reason for hiding this comment

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

Recommended information: at least one of socialNetwork or merchantWebsite, as well as customerRegion, paymentFrequency.

Source

We should probably callout this specific information makes onboarding faster. I'd make this a tip callout :)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Done ✅

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.

@ntombing ntombing force-pushed the DOC-1024/merchant-doc-updates branch from 2ec87cb to 12c9b17 Compare July 23, 2025 10:19
@ntombing
Copy link
Contributor Author

ntombing commented Jul 23, 2025

Great stuff! Your writing quality is impeccable, I have no suggestions :)

Quick question in addition to the ones below:

typical implementations of payment links include the ability to add a payment link in an invoice, share it via QR Code, or email or SMS
-> Was this requirement cancelled?

Hey,

Thanks for the review. The recommendation wasn't canceled, it was already addressed in a previous ticket: Cards for merchants overview.

I made some missed changes to the Sandbox, Request a merchant profile and Request card payment method pages.

Thanks! :)

Copy link
Contributor

@max-koro max-koro left a comment

Choose a reason for hiding this comment

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

LGTM

@ntombing ntombing removed the request for review from racene-swan July 24, 2025 16:21
@racene-swan racene-swan self-requested a review July 25, 2025 06:32
@ntombing ntombing merged commit 53fc5ed into main Jul 25, 2025
4 checks passed
@ntombing ntombing deleted the DOC-1024/merchant-doc-updates branch July 25, 2025 08:36
@ntombing ntombing restored the DOC-1024/merchant-doc-updates branch July 25, 2025 08:37
@ntombing ntombing deleted the DOC-1024/merchant-doc-updates branch July 25, 2025 08:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants