Add a SEPA Direct Debit B2B funding source

Add a SEPA Direct Debit B2B funding source with the API.

Prerequisites

1. The funding source is a non-Swan account belonging to the Swan account holder.
2. The user adding the funding source is either an account member with the canManageAccountMembership and canViewAccount permissions, or the account holder.
3. Call the mutation with a user access token associated with the account holder. The account holder needs to sign the direct debit mandate by consenting to the sensitive operation of adding a funding source.

Step 1: Add the funding source

1. Call the addDirectDebitFundingSource mutation.
2. Choose the SepaDirectDebitB2b scheme.
   • Though Core is an option in the API, it's not actually available for account funding.
3. Add your accountId, iban, consentRedirectUrl, and a name for your funding source (name is primarily for your reference).
4. Add the success payload: AddDirectDebitFundingSourceSuccessPayload.
5. Add the consent URL to the success payload: fundingSource > DirectDebitFundingSource > paymentMandate > SEPAPaymentDirectDebitMandate > statusInfo > PaymentMandateConsentPendingStatusInfo > consent > consentUrl.
6. Add rejections (not shown).

🔎 Open the mutation in API Explorer

mutation AddSddB2b {
  addDirectDebitFundingSource(
    input: {
      scheme: SepaDirectDebitB2b
      accountId: "$YOUR_ACCOUNT_ID"
      iban: "$YOUR_IBAN"
      consentRedirectUrl: "$YOUR_REDIRECT_URL"
      name: "Your funding source name"
    }
  ) {
    ... on AddDirectDebitFundingSourceSuccessPayload {
      __typename
      fundingSource {
        ... on DirectDebitFundingSource {
          id
          name
          paymentMandate {
            ... on SEPAPaymentDirectDebitMandate {
              id
              name
              statusInfo {
                ... on PaymentMandateConsentPendingStatusInfo {
                  __typename
                  consent {
                    consentUrl
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Step 2: Consent to adding the funding source

1. Send the consentUrl (line 14) with your Swan account holder.
2. Instruct them to consent to adding the funding source.

Note you also receive a funding source ID (line 6) and a payment mandate ID (line 9).

{
  "data": {
    "addDirectDebitFundingSource": {
      "__typename": "AddDirectDebitFundingSourceSuccessPayload",
      "fundingSource": {
        "id": "$YOUR_FUNDING_SOURCE_ID",
        "name": "Your funding source name",
        "paymentMandate": {
          "id": "$YOUR_PAYMENT_MANDATE_ID",
          "name": null,
          "statusInfo": {
            "__typename": "PaymentMandateConsentPendingStatusInfo",
            "consent": {
              "consentUrl": "https://identity.swan.io/consent?consentId=$CONSENT_ID&env=Sandbox"
            }
          },
          "mandateDocumentUrl": ""
        }
      }
    }
  }
}

Funding source and mandate Enabled

After the account holder consents to the adding the funding source, the statuses for both the funding source and the direct debit mandate change to Enabled, and funds can be pulled into the Swan account.

However, the account holder still needs to declare their payment mandate.

Step 3: Get the payment mandate

Get the mandateDocumentUrl to download the payment mandate.

1. Call the fundingSource query.
2. Add the funding source ID (provided in the step 2 payload, line 6)
3. Add the mandateDocumentUrl to the payload (line 10).

🔎 Open the query in API Explorer

query GetMandateUrl {
  fundingSource(id: "$YOUR_FUNDING_SOURCE_ID") {
    ... on DirectDebitFundingSource {
      id
      name
      paymentMandate {
        ... on SEPAPaymentDirectDebitMandate {
          id
          name
          mandateDocumentUrl
        }
      }
    }
  }
}

Step 4: Declare the mandate to the external account provider

The account holder must declare the payment mandate to the provider of their non-Swan account.

1. Open the mandateDocumentUrl provided in the payload (line 9), which automatically triggers the download of the SEPA Direct Debit payment mandate PDF document.
2. Provide the payment mandate document to the account holder.
3. Instruct the account holder to declare the payment mandate to the provider of their non-Swan account.

{
  "data": {
    "fundingSource": {
      "id": "$YOUR_FUNDING_SOURCE_ID",
      "name": "Your funding source name",
      "paymentMandate": {
        "id": "$YOUR_PAYMENT_MANDATE_ID",
        "name": "Your mandate name",
        "mandateDocumentUrl": "https://mandate.swan.io/$YOUR_FUNDING_SOURCE_ID/SANDBOX/FR23ZZZ87D106/UkdSRjJCVUJSSkpXR05EVkY=.pdf?Expires=1734430612&Signature=$SIGNATURE"
      }
    }
  }
}