{"title":"Manage mandates for direct debits in the UK","category":"default","creationDate":1574035980,"content":"

Limited availability<\/strong><\/span><\/span>
\nDirect debits in the UK are in pilot phase. Some of the processes and documentation may change as the feature evolves.<\/p>\n

\n

A mandate is an authorization that your user gives for allowing a counterparty to debit funds from the user's business account. When your user authorizes a one-time or recurring direct debit, the counterparty's bank notifies Adyen, and a mandate is created. <\/p>\n

After a mandate is created, you can view, amend, or cancel the mandate using Adyen's APIs. This page explains how to make API requests related to mandates and how to get updates about the result of these requests.<\/p>\n

Requirements<\/h2>\n

Before you begin, make sure that you fulfill the following requirements:<\/p>\n\n\n\n\n\n\n\n\n\n\n
Requirement<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
Integration type<\/strong><\/td>\nYou must have an Adyen for Platforms<\/a> integration that includes business accounts.<\/td>\n<\/tr>\n
API credential roles<\/a><\/strong><\/td>\nMake sure that your web service API key has the following role:
  • Manage Direct Debit Mandates role<\/strong><\/li><\/ul><\/td>\n<\/tr>\n
Capabilities<\/strong><\/td>\nMake sure that you enabled the following capability for your user:
  • sendToThirdParty<\/strong><\/span><\/li><\/ul><\/td>\n<\/tr>\n
Webhooks<\/strong><\/td>\nIn your Customer Area, subscribe to the following webhook:
  • Mandate Webhooks<\/strong><\/span><\/li><\/ul><\/td>\n<\/tr>\n
Limitations<\/strong><\/td>\nCurrently, these endpoints only support mandates created for accounts in the UK.<\/td>\n<\/tr>\n
Setup steps<\/strong><\/td>\nReach out to your Adyen contact to enable direct debits in the UK.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

View a list of mandates<\/h2>\n

You can view a list of all mandates created for a business account, regardless of the status.<\/p>\n

To get this list: <\/p>\n

    \n
  1. \n

    Make a GET \/mandates<\/code> request, specifying at least one<\/em> of following parameters:<\/p>\n\n\n\n\n\n\n
    Parameter name<\/th>\nParameter type<\/th>\nRequired<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
    balanceAccountId<\/code><\/td>\nQuery<\/td>\n<\/td>\nThe unique identifier of the balance account linked to your user's business account.<\/td>\n<\/tr>\n
    paymentInstrumentId<\/code><\/td>\nQuery<\/td>\n<\/td>\nThe unique identifier of your user's business account.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

    The following code example shows a GET \/mandates<\/code> request for a balance account with ID BA000000000000000000000001<\/strong><\/span>, linked to a business account with ID PI000000000000000000000001<\/strong><\/span>.<\/p>\n

    \n<\/code-sample>\n<\/div>\n

    A successful request returns an HTTP 200<\/strong><\/span> response.<\/p>\n<\/li>\n

  2. \n

    In the HTTP 200<\/strong><\/span> response, verify that you received the following parameters:<\/p>\n\n\n\n\n\n\n
    Response parameter<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
    mandates<\/code><\/td>\nAn array that contains all mandates that match the query parameters.<\/td>\n<\/tr>\n
    link<\/code><\/td>\nAn object that contains links to the next or previous page, when applicable.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    \n<\/code-sample>\n<\/div>\n<\/li>\n<\/ol>\n

    View a specific mandate<\/h2>\n

    To view the details of a specific mandate:<\/p>\n

      \n
    1. \n

      Make a GET \/mandates\/{mandateId}<\/code> request, specifying the mandateId<\/code> in the path.<\/p>\n

      The following example shows how to get the details of a mandate with ID MNDT000000000000000000000001<\/strong><\/span>.<\/p>\n

      \n<\/code-sample>\n<\/div>\n

      A successful request returns an HTTP 200<\/strong><\/span> response. <\/p>\n<\/li>\n

    2. \n

      In the HTTP 200<\/strong><\/span> response, verify that you received an object with the following parameters:<\/p>\n

      \n \n\n\n\n\n\n\n\n\n\n\n\n\n
      Response parameter<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
      balanceAccountId<\/code><\/td>\nThe unique identifier of the balance account to which the mandate applies.<\/td>\n<\/tr>\n
      counterparty<\/code><\/td>\nAn object that contains information about the party that receives the funds from the direct debit.<\/td>\n<\/tr>\n
      createdAt<\/code><\/td>\nThe date when the mandate was created.<\/td>\n<\/tr>\n
      id<\/code><\/td>\nThe unique identifier of the mandate.<\/td>\n<\/tr>\n
      paymentInstrumentId<\/code><\/td>\nThe unique identifier of your user's business account.<\/td>\n<\/tr>\n
      status<\/code><\/td>\nThe current status of the mandate. Possible values: pending<\/strong><\/span>, approved<\/strong><\/span>, or cancelled<\/strong><\/span>.<\/td>\n<\/tr>\n
      type<\/code><\/td>\nThe type of mandate. Possible value: bacs<\/strong><\/span>.<\/td>\n<\/tr>\n
      updatedAt<\/code><\/td>\nThe date when the mandate was updated, if applicable.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n\n<\/div>\n\n
      \n<\/code-sample>\n<\/div>\n<\/li>\n<\/ol>\n

      Amend a mandate<\/h2>\n

      You can amend a mandate to change what business account the mandate applies to. For example, consider a user that opens a second business account in your platform, exclusively to handle monthly expenses. Instead of creating a new mandate, your user can amend the ID of the business account.<\/p>\n

      To amend a mandate:<\/p>\n

        \n
      1. \n

        Make a PATCH \/mandates\/{mandateId}<\/code> request, specifying the following parameters:<\/p>\n\n\n\n\n\n\n
        Parameter name<\/th>\nParameter type<\/th>\nRequired<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
        mandateId<\/code><\/td>\nPath<\/td>\n\"-white_check_mark-\"<\/td>\nThe unique identifier of the mandate.<\/td>\n<\/tr>\n
        paymentInstrumentId<\/code><\/td>\nRequest<\/td>\n\"-white_check_mark-\"<\/td>\nThe unique identifier of your user's business account.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

        The following example shows how to make a PATCH \/mandates\/{mandateId}<\/code> request for updating the payment instrument ID to which the mandate corresponds.<\/p>\n

        \n<\/code-sample>\n<\/div>\n<\/li>\n
      2. \n

        Verify that you receive an HTTP 202 \u2014 Accepted<\/strong><\/span> response with no content. This means that the request was correct.
        \nAfter this, Adyen processes the request asynchronously. <\/p>\n<\/li>\n

      3. \n

        To be informed about the result of the request, listen to the webhooks<\/a> that Adyen sends to your server.<\/p>\n<\/li>\n<\/ol>\n

        Cancel a mandate<\/h2>\n

        To cancel an existing mandate:<\/p>\n

          \n
        1. \n

          Make a POST \/mandates\/{mandateId}\/cancel<\/code> request, specifying the mandateId<\/code> in the path.<\/p>\n

          The following example shows how to cancel a mandate with ID MNDT000000000000000000000001<\/strong><\/span>.<\/p>\n

          \n<\/code-sample>\n<\/div>\n<\/li>\n
        2. \n

          Verify that you receive an HTTP 202 \u2014 Accepted<\/strong><\/span> response with no content. This means that the request was correct.
          \nAfter this, Adyen processes the request asynchronously. <\/p>\n<\/li>\n

        3. \n

          To be informed about the result of the request, listen to the webhooks<\/a> that Adyen sends to your server.<\/p>\n<\/li>\n<\/ol>\n

          Get updates about requests<\/h2>\n

          Adyen sends webhooks to your server to inform you when a mandate is created, updated, or canceled. Using these webhooks, you can track information such as:<\/p>\n