Merchants

Swan account holders who are approved to accept payments from their customers using Swan.

Overview

Merchants are account holders 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.

Pending review

Before accepting payments, you need to complete a risk review. To get started, contact your dedicated PIM (Product Integration Manager), or send an email to integration@swan.io.

Managing risk

Accepting payments from customers comes with risk, and Swan prioritizes a risk-based approach.

Swan reviews all requests for merchant profiles, profile updates, and payment methods. Both profiles and payment methods initially start with the status PendingReview.

For payment methods, Swan may change the status to WaitingForInformation when additional details are needed. In such cases, you'll receive these details within the verificationRequirements list. New information must be provided at the Merchant Profile level.

To manage potential risk, Swan can change the rolling reserve and the payment amount limit. If suspicious activity is detected, we can also 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. The user must submit a new request for the account holder, which Swan will review as a separate submission.

Webhooks

Subscribe to numerous webhooks to facilitate your merchant integrations. Review the full list of merchant webhooks, or subscribe to them directly from your Dashboard > Developers > Webhooks.

Merchant profiles

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.

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

Your users can create merchant profiles during onboarding, but only if you've requested the feature for the account holder. Since merchants are considered high risk, merchant profiles should only be requested for account holders who qualify and will accept payments. Requesting merchant profiles for account holders that don't qualify may create false expectations about available features.

To speed up merchant profile enablement, complete as many input fields as possible. A merchant profile contains the following information:

Field Requirements Legend

● REQ Required:Must be completed.

◐ CND Conditional:Required only in specific situations.

○ OPT Optional:Isn't required; may have a default value.

Field	Requirement	Description
Business details	● REQ	Merchant's legal name and product type (Goods, Services, VirtualGoods, or GiftAndDonations).
Projected volumes	● REQ	Expected monthly payment volume and average order value, used to assess the business size and risk.
Link to the merchant's website or social network	◐ CND	Recommended. Provides context on the merchant's activity and may be requested during the review. May be requested after a risk review if it wasn't provided before.
Payment frequency	◐ CND	Defines whether payments are mainly one-off or recurring (e.g. subscriptions).
Logo	○ OPT	A .png file under 1 MB, displayed on the payment page and the mandate PDF.
Accent color	○ OPT	Hex code used to customize the payment page design and mandate.
Customer region	◐ CND	Country or region where the merchant expects to receive payments.
Additional information	◐ CND	Required only if custom information is needed. Specified in the expectedMerchantProfileAdditionalInformation field of the ProjectInfo object in the API.
Supporting documents	◐ CND	Required only after a payment method risk review. Listed in the paymentMethod object in the API.

The merchant profile is created with the status PendingReview, and is visible right away on your Dashboard.

Merchant profile statuses

Profile status	Explanation
PendingReview	The profile is under review by Swan. • If the profile doesn't meet our requirements or we consider it a risk, we'll change the status to Rejected. Otherwise, we'll change the status to Enabled. • Request payment methods while a profile is PendingReview.
Enabled	The profile is active. Capabilities: • Request payment methods and accept payments. • Make updates to the profile's information.
Suspended	Swan assigns this status when we need to review a merchant's profile. The profile can't be Enabled again until we complete our review.
Rejected	Swan assigns this final status when a profile's risk is too high, or for other risk-related reasons.
Disabled	You set this final status using the disableMerchantProfile mutation.

Updating merchant profiles

You can request a merchant profile update with the API mutation requestMerchantProfileUpdate. If you use Swan's Web Banking interface, merchants can request an update through their app. Request an update for the merchant's name, website, product type, expected monthly payment volume, expected average basket, and logo.

Updating a merchant profile produces the following events:

1. The merchant profile status doesn't change, remaining Enabled. The merchant continues to use their merchant profile with the existing information.
2. The update status is PendingReview. Swan reviews the new information to ensure it meets requirements.
3. After Swan reviews and validates the update request, the update status changes to Enabled and the update is published to the merchant profile.
4. 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.

Subject to review

All update requests are reviewed by Swan according to the same risk guidelines as a new merchant profile.

Merchant profile rejection

The merchant profile is created with the status PendingReview, and is visible right away on your Dashboard. It is then updated to either Enabled or Rejected depending on Swan's risk review.

A merchant profile can be rejected for the following reasons:

Rejection reason	Explanation
DuplicateProfile	The profile is the same as an existing one.
InconsistentOrMissingInformation	Key information is missing or highly inconsistent, for example, an unrelated website.
UnsupportedActivity	The activity is prohibited or the NACE code isn't supported.
ContractualCriteriaNotFulfilled	The profile doesn't meet specific criteria agreed upon with Partners.
GenericRejection	The profile was rejected for a general reason not covered by other categories.
SuspiciousBehavior	The profile was rejected due to alerts related to suspicious processing behavior.

Payment methods

Your merchants can accept customer payments using several payment methods.

Merchant payment methods are connected to a merchant profile, and a single merchant profile can have multiple payment methods. To accept payments with Swan, there must be an Enabled merchant profile and at least one Enabled merchant payment method.

To learn how to request payment methods, refer to the request payment method guides for card payments, SEPA Direct Debit, Internal Direct Debit, and French checks. You can request multiple methods in one API call.

Available payment methods

Your merchants can request the following online payment methods to accept payments with Swan:

• Cards
• SEPA Direct Debit (B2B and Core)
• Internal Direct Debit (B2B and Standard)
• French checks (API only; debtor's bank must be located in France)

All merchant payment method requests are subject to a risk review and start with the status PendingReview. As part of this process, Swan may need to request additional information from the merchant to complete the assessment.

Payment method statuses

Payment method status	Explanation
PendingReview	The payment method is under review by Swan. • If the request doesn't meet our requirements or we consider it a risk, we'll change the status to Rejected. • Otherwise, we'll change the status to Enabled. Capabilities: • While a profile is PendingReview, you can still request payment methods.
WaitingForInformation	More information is needed before the payment method can be reviewed by Swan. • The verificationRequirements shows what the Partner must provide to trigger a new review. • Submit supporting documents and request a new review using the requestSupportingDocumentCollectionReview mutation. • After all required information is submitted, the status returns to PendingReview for a new review.
Enabled	The payment method is active. • Use Enabled payment methods to accept payments. • Updates to payment methods can only occur when they are Enabled.
Suspended	Swan assigns this status when we need to review the merchant's use of their payment method. The payment method can't be Enabled again until we complete our review.
Rejected	Swan assigns this final status when a payment method's risk is too high, or for other risk-related reasons.
Disabled	You set this final status using the disableMerchantPaymentMethod mutation.

Payment method rejection

A merchant payment method can be rejected for the following reasons:

Rejection reason	Explanation
InvalidUseCase	The requested payment method is incompatible with the merchant's business model.
InconsistentOrMissingInformation	The merchant didn't provide, or refused to provide, requested information.
UnsupportedPaymentMethod	The Partner isn't allowed to request this payment method.
ContractualCriteriaNotFulfilled	The request doesn't meet the contractual criterion agreed upon with the Partner.
GenericRejection	The request was rejected for a reason not covered by other categories.

Rolling reserve

Rolling reserve is a policy Swan applies to merchant transactions to protect the merchant and Swan against various risk factors, primarily insufficient funds and attempted fraud. The reserved amount acts as a safety net to cover potential loss for both Swan and the merchant.

Rolling reserve is expressed as a percentage over a period of time (example: 10% of the payment amount over 30 business days), and applies to most payment methods used by merchants to accept payments with Swan.

For the indicated period of time, the amount isn't part of the merchant's available account balance, after which the funds are released to the merchant and can be used.

Payment method	Rolling reserve	Default amount
Cards	✓ Yes	100% over 5 business days
SEPA Direct Debit - Core	✓ Yes	Determined by a merchant profile risk assessment
SEPA Direct Debit - B2B	✓ Yes	100% over 3 business days
Internal Direct Debit - Standard	✓ Yes	Determined by a merchant profile risk assessment
Internal Direct Debit - B2B	✗ No	n/a
French checks	✓ Yes	100% over 10 interbank business days

Webhooks

Subscribe to the relevant webhooks to stay informed about updates:

• Rolling reserve value, payment amount limit, and payment methods: subscribe to the merchant payment methods webhooks.

• Merchant profile changes: subscribe to the merchant profile webhooks.

• Transaction-level rolling reserve releases: the TransactionRollingReserve.Updated and TransactionRollingReserve.Released webhooks notify you when the rolling reserve of an individual transaction is updated or released.

Use both merchant and transaction webhooks to cover account-level and transaction-level updates.

Payment amount limit

For security and risk management, Swan may apply a payment amount limit to single card payments. This limit defines the maximum amount a user can spend in one card transaction. If a payment exceeds this limit, the API returns a ForbiddenRejection error.

Versions

Swan creates a new version of your payment method every time an update is approved. Only one version of a payment method can have the status Enabled.

Swan manages the statuses for Enabled or PendingReview payment methods automatically. Therefore, you don't need to change the status before calling the API.

Guides

• Merchant onboarding
• Request a merchant profile
• Update a merchant profile
• Provide missing information
• Get information about a merchant profile
• Sandbox
• Request payment methods:
  • Cards
  • SEPA Direct Debit
  • Internal Direct Debit
  • French checks
• Create payment links:
  • Cards