Doc-1817: [Partner ops] Manage SEPA Direct Debit mandates - #659
Open
racene-swan wants to merge 8 commits into
Open
Doc-1817: [Partner ops] Manage SEPA Direct Debit mandates#659racene-swan wants to merge 8 commits into
racene-swan wants to merge 8 commits into
Conversation
✅ Deploy Preview for incomparable-tiramisu-91a96a ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
max-koro
reviewed
Jul 1, 2026
max-koro
left a comment
max-koro
left a comment
Contributor
There was a problem hiding this comment.
Nice one! Just a few comments, 1 blocking:
Comment on lines
+98
to
+117
| ## Stop or cancel a direct debit | ||
|
|
||
| Suspending or canceling a mandate **requires your dev team**. There's no self-service option in the Dashboard. | ||
|
|
||
| | Action | What it does | Reversible? | When to use | | ||
| | --- | --- | --- | --- | | ||
| | **Suspend** | Blocks future debits. Any pending instructions are rejected. | Yes. It can be re-enabled | User wants to temporarily pause debits from a creditor | | ||
| | **Cancel** | Permanently ends the mandate | No | User wants to permanently stop all debits from a creditor | | ||
|
|
||
| **What to do:** | ||
|
|
||
| 1. Confirm with your user whether they want to suspend (temporary) or cancel (permanent). | ||
| 1. Pass the request to your dev team with the **mandate ID** (visible in **Dashboard** > **Received direct debit mandates**) and the action (`suspend` or `cancel`). | ||
| 1. Your dev team can follow the [Suspend a mandate](https://docs.swan.io/topics/payments/direct-debit/guide-suspend-mandate/) or [Cancel a mandate](https://docs.swan.io/topics/payments/direct-debit/guide-cancel-mandate/) guide. | ||
|
|
||
| :::note | ||
| If your integration already supports this, your user may be able to do it directly from your product's interface. | ||
| ::: | ||
|
|
||
| **Can't reach your dev team?** Contact Swan support with the mandate ID and requested action. |
Contributor
There was a problem hiding this comment.
Suggested change
| ## Stop or cancel a direct debit | |
| Suspending or canceling a mandate **requires your dev team**. There's no self-service option in the Dashboard. | |
| | Action | What it does | Reversible? | When to use | | |
| | --- | --- | --- | --- | | |
| | **Suspend** | Blocks future debits. Any pending instructions are rejected. | Yes. It can be re-enabled | User wants to temporarily pause debits from a creditor | | |
| | **Cancel** | Permanently ends the mandate | No | User wants to permanently stop all debits from a creditor | | |
| **What to do:** | |
| 1. Confirm with your user whether they want to suspend (temporary) or cancel (permanent). | |
| 1. Pass the request to your dev team with the **mandate ID** (visible in **Dashboard** > **Received direct debit mandates**) and the action (`suspend` or `cancel`). | |
| 1. Your dev team can follow the [Suspend a mandate](https://docs.swan.io/topics/payments/direct-debit/guide-suspend-mandate/) or [Cancel a mandate](https://docs.swan.io/topics/payments/direct-debit/guide-cancel-mandate/) guide. | |
| :::note | |
| If your integration already supports this, your user may be able to do it directly from your product's interface. | |
| ::: | |
| **Can't reach your dev team?** Contact Swan support with the mandate ID and requested action. | |
| ## Stop or cancel a direct debit | |
| Suspending a mandate **requires your dev team** — there's no self-service option in the Dashboard. There's also no action to permanently cancel a mandate; `OneOff` mandates are canceled automatically after they're used. | |
| | Action | What it does | Reversible? | When to use | | |
| | --- | --- | --- | --- | | |
| | **Suspend** | Blocks future debits. Any pending instructions are rejected. | Yes. It can be re-enabled. | User wants to stop debits from a creditor. | | |
| **What to do:** | |
| 1. Confirm your user wants to stop debits from the creditor. | |
| 1. Pass the request to your dev team with the **mandate ID** (visible in the **Received direct debit mandates** tab). | |
| 1. Your dev team can follow the [Suspend a mandate](https://docs.swan.io/topics/payments/direct-debit/guide-suspend-mandate/) guide. To resume debits later, they can [enable the mandate](https://docs.swan.io/topics/payments/direct-debit/guide-enable-mandate/). | |
| :::note | |
| If your integration already supports this, your user may be able to suspend debits directly from your product's interface. | |
| ::: | |
| **Can't reach your dev team?** Contact Swan support with the mandate ID. |
Contributor
There was a problem hiding this comment.
No cancel mutation exists (add/enable/suspend/update only), and guide-cancel-mandate 404s. Canceled is only ever reached automatically — OneOff mandates after use. Kept the heading so #stop-or-cancel-a-direct-debit stays valid.
| 1. Pass the update request to your dev team with the **mandate ID** and the details that need changing. | ||
| 1. Your dev team can follow the [Update a mandate](https://docs.swan.io/topics/payments/direct-debit/guide-update-mandate/) guide. | ||
| 1. Once they've submitted the update, share the consent URL with your user. | ||
| 1. If the mandate stays in `ConsentInitiationPending` for more than 24 hours, follow up with your user. |
Contributor
There was a problem hiding this comment.
Suggested change
| 1. If the mandate stays in `ConsentInitiationPending` for more than 24 hours, follow up with your user. | |
| 1. If the mandate stays in `ConsentPending` for more than 24 hours, follow up with your user. |
After the update mutation the mandate is ConsentPending (active consent, URL awaiting the debtor) — per the update-mandate payload. ConsentInitiationPending is the pre-initiation / post-consent-KO state (CRED-1602, DOC-1559, both shipped Q1 2026), which needs re-initiation, not just a nudge.
| | B2B mandate not consented | Mandate status is `ConsentInitiationPending` or `ConsentPending` | Initiate consent or remind your user to complete it | | ||
| | Insufficient available balance | Check available balance (not booked) before 6:00 AM CET | Your user must add funds before the next execution date | | ||
| | Account closed or closing | Check account status | A new account is needed | | ||
| | Invalid mandate information | Creditor's details don't match registered mandate | Contact the creditor to verify UMR and SCI | |
Contributor
There was a problem hiding this comment.
Suggested change
| | Invalid mandate information | Creditor's details don't match registered mandate | Contact the creditor to verify UMR and SCI | | |
| | Invalid mandate information | Creditor's details don't match registered mandate | Contact the creditor to verify the Unique Mandate Reference (UMR) and SEPA Creditor Identifier (SCI) | |
UMR/SCI first appear here but are only spelled out later in the checklist — expand on first use.
| To check existing mandates: | ||
|
|
||
| 1. Go to **Dashboard** > **Data** > **Accounts**. | ||
| 1. Select the account and open the **Received direct debit mandates** tab. |
Contributor
There was a problem hiding this comment.
Can you confirm the exact Dashboard tab label? The add-mandate guide writes it as Received Direct Debit Mandates (title case) — worth matching.
| | Cause | How to check | What to do | | ||
| | --- | --- | --- | | ||
| | B2B mandate not consented | Mandate status is `ConsentInitiationPending` or `ConsentPending` | Initiate consent or remind your user to complete it | | ||
| | Insufficient available balance | Check available balance (not booked) before 6:00 AM CET | Your user must add funds before the next execution date | |
Contributor
There was a problem hiding this comment.
Suggested change
| | Insufficient available balance | Check available balance (not booked) before 6:00 AM CET | Your user must add funds before the next execution date | | |
| | Insufficient available balance | Check the `Available` balance (not `Booked`) before 6:00 AM CET | Your user must add funds before the next execution date | |
Optional — docs code-format balance names; same could apply on R12 and R81.
|
|
||
| ## Understand when payments are executed | ||
|
|
||
| Swan checks all pending direct debit instructions at **6:00 AM CET/CEST** on the day the payment is due. At that point, Swan checks: |
Contributor
There was a problem hiding this comment.
Suggested change
| Swan checks all pending direct debit instructions at **6:00 AM CET/CEST** on the day the payment is due. At that point, Swan checks: | |
| Swan checks all pending direct debit instructions at **6:00 AM CET/CEST** on the day the payment is due, following the [full execution logic](https://docs.swan.io/topics/payments/direct-debit/#received-instructions-execution). At that point, Swan checks: |
max-koro
reviewed
Jul 27, 2026
|
|
||
| Your user's refund rights depend on their mandate scheme. For full details, including timelines for returns and creditor reversals, refer to the [SEPA Direct Debit specifications](https://docs.swan.io/topics/payments/direct-debit/#specifications). | ||
|
|
||
| ###Quick reference for your support conversations |
Contributor
There was a problem hiding this comment.
Suggested change
| ###Quick reference for your support conversations | |
| ### Quick reference for your support conversations |
|
|
||
| ::: | ||
|
|
||
| ### Core vs. B2B: what's the difference? |
Contributor
There was a problem hiding this comment.
Suggested change
| ### Core vs. B2B: what's the difference? | |
| ### Differences between Core and B2B mandates |
| - You need help investigating a rejection that doesn't match the causes in this guide. | ||
| - A user is requesting a Core direct debit refund. | ||
|
|
||
| ### Always include: |
Contributor
There was a problem hiding this comment.
Suggested change
| ### Always include: | |
| ### Always include |
| - Any API error messages from your development team. | ||
| - Supporting files or screenshots, if relevant. | ||
|
|
||
| ### For B2B mandate requests, also include: |
Contributor
There was a problem hiding this comment.
Suggested change
| ### For B2B mandate requests, also include: | |
| ### For B2B mandate requests, also include |
| - Mandate document, if available | ||
| - Confirmation that the request came from someone authorized to manage payments on the account (usually the legal representative). | ||
|
|
||
| ### For refund requests, also include: |
Contributor
There was a problem hiding this comment.
Suggested change
| ### For refund requests, also include: | |
| ### For refund requests, also include |
| | --- | --- | --- | | ||
| | `Enabled` | The mandate is active. | If a direct debit still failed, check the account balance, that the account status is `Enabled`, or whether the creditor details match. | | ||
| | `ConsentInitiationPending` or `ConsentPending` | The user hasn't finished setting up or consenting to the B2B mandate yet. | Ask them to complete the approval before the payment due date. If stuck, walk them through it in your product or raise a Swan Support request. | | ||
| | `Suspended` | The mandate is temporarily blocked. No debits can go through. | Check with the user, do they want to keep it blocked or resume it? To resume it, your user can do this from your product if your integration supports it. Otherwise, raise a Swan Support request. | |
Contributor
There was a problem hiding this comment.
Suggested change
| | `Suspended` | The mandate is temporarily blocked. No debits can go through. | Check with the user, do they want to keep it blocked or resume it? To resume it, your user can do this from your product if your integration supports it. Otherwise, raise a Swan Support request. | | |
| | `Suspended` | The mandate is temporarily blocked. No debits can go through. | Check with the user: do they want to keep it blocked or resume it? To resume it, your user can do this from your product if your integration supports it. Otherwise, raise a Swan Support request. | |
| | **Core** | Individuals and business accounts in Euros between accounts in the Single Euro Payments area (SEPA) only | Automatically. Swan creates it when the first direct debit instruction arrives. No registration needed. | Yes, up to 8 calendar weeks (no questions asked) or 13 months (unauthorized). | Yes | | ||
| | **B2B** | Businesses only | Manually. The user must sign, register, and consent to the mandate before use. | None | Yes | | ||
|
|
||
| **How to tell them apart:** if a mandate document doesn't mention **B2B** or **business-to-business**, it's a Core mandate. No action needed. The details appear in the Dashboard once the creditor sends the first direct debit. |
Contributor
There was a problem hiding this comment.
Suggested change
| **How to tell them apart:** if a mandate document doesn't mention **B2B** or **business-to-business**, it's a Core mandate. No action needed. The details appear in the Dashboard once the creditor sends the first direct debit. | |
| **How to tell them apart:** If a mandate document doesn't mention **B2B** or **business-to-business**, it's a Core mandate. No action needed. The details appear in the Dashboard once the creditor sends the first direct debit. |
Comment on lines
+258
to
+259
| - Any API error messages from your development team. | ||
| - Supporting files or screenshots, if relevant. |
Contributor
There was a problem hiding this comment.
Suggested change
| - Any API error messages from your development team. | |
| - Supporting files or screenshots, if relevant. | |
| - Any API error messages from your development team | |
| - Supporting files or screenshots, if relevant |
These are label-style fragments, so per our list rule they don't take fullstops, matching the rest of each checklist. Left R278–279 as-is since those are imperative sentences and keep theirs.
| - Signature date | ||
| - Mandate language | ||
| - Mandate document, if available | ||
| - Confirmation that the request came from someone authorized to manage payments on the account (usually the legal representative). |
Contributor
There was a problem hiding this comment.
Suggested change
| - Confirmation that the request came from someone authorized to manage payments on the account (usually the legal representative). | |
| - Confirmation that the request came from someone authorized to manage payments on the account (usually the legal representative) |
Comment on lines
+275
to
+277
| - Confirmation that the transaction is Core / B2C, not B2B. | ||
| - Confirmation that the transaction is `Booked`. | ||
| - Confirmation that no refund has already been received or initiated. |
Contributor
There was a problem hiding this comment.
Suggested change
| - Confirmation that the transaction is Core / B2C, not B2B. | |
| - Confirmation that the transaction is `Booked`. | |
| - Confirmation that no refund has already been received or initiated. | |
| - Confirmation that the transaction is Core / B2C, not B2B | |
| - Confirmation that the transaction is `Booked` | |
| - Confirmation that no refund has already been received or initiated |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.