Initiate an Internal Direct Debit transaction

Prerequisites

• Debtor's account status: any except Closing or Closed
• Merchant profile status: Enabled
• Payment method status: Enabled
• Direct debit payment mandate status: Enabled
• Debtor and merchant have accounts in the same Swan projects
• (B2B only) Debtor's account type: Company

Guide

1. Confirm you have a project access token or, if you're an account member, a user access token with CanManageAccountMembership permissions.
2. Call the initiateMerchantPaymentCollection mutation.
3. Include the amount value and currency.
4. Choose internalDirectDebit (line 5), and add the payment mandate ID (line 6) from the declare a payment mandate guide.
5. Add validations and rejections that are helpful for you, as well as optional information such as a reference for your internal use.

Mutation

Dates

Dates for this mutation use ISO 8601 convention: YYYY-MM-DDTHH-mm-ssZ.

If the date is left empty, the transaction will be executed as soon as possible. If the date indicated is a non-business day, the transaction will be executed on the next business day.

🔎 Open the mutation in API Explorer

mutation InitiateIdd {
  initiateMerchantPaymentCollection(
    input: {
      amount: { value: "50", currency: "EUR" }
      internalDirectDebit: {
        mandateId: "$YOUR_MANDATE_ID"
      }
    }
  ) {
    ... on ValidationRejection {
      __typename
      message
      fields {
        path
        message
        code
      }
    }
    ... on InternalErrorRejection {
      __typename
      message
    }
    ... on NotFoundRejection {
      id
      message
    }
    ... on ForbiddenRejection {
      __typename
      message
    }
    ... on InitiateMerchantPaymentCollectionSuccessPayload {
      __typename
      merchantPaymentCollection {
        id
        statusInfo {
          status
        }
      }
    }
  }
}

Payload

Note the id (line 6) for your Internal Direct Debit payment and the status Initiated (line 8).

{
  "data": {
    "initiateMerchantPaymentCollection": {
      "__typename": "InitiateMerchantPaymentCollectionSuccessPayload",
      "merchantPaymentCollection": {
        "id": "$YOUR_PAYMENT_ID",
        "statusInfo": {
          "status": "Initiated"
        }
      }
    }
  }
}

Next steps

1. At this point, two transactions are created automatically and sequentially:
   1. First, an incoming Internal Direct Debit (InternalDirectDebitIn) is created in the merchant's account with the status Upcoming.
   2. Then, an outgoing Internal Direct Debit (InternalDirectDebitOut) is created in the debtor's account with the status Upcoming.
2. On the settlement date, Swan confirms the transaction can be completed, meaning the following must be true:
   1. Debtor's Swan account status: Enabled (Different from the prerequisites because the account doesn't need to be enabled to start the transaction.).
   2. Direct debit payment mandate status: Enabled.
   3. Debtor's available balance is enough to cover the transaction.
3. Then, Swan updates the status for both the InternalDirectDebitIn and InternalDirectDebitOut to Booked.

Payment received

• B2B transactions: the merchant receives the payment as soon as the status passes to Booked.
• Standard transactions: rolling reserve begins after the transaction is Booked. After the indicated rolling reserve period, the merchant receives the payment.