Skip to content
Last updated

Direct debit design patterns

There are several design patterns to consider when asking customers to sign direct debit. Consider here the user experience you want to achieve.

Sign direct debit in pop up window

If you want to launch direct debit in a new window, for example, if you are doing it as part of a sign-up or contracting process.

To launch your direct debit mandate, use must use the following code:

window.open(
  "https://console.adfin.com/dd-mandate/%3Cid%3E?mode=popup"
)

How to build the URI:

Base URLQuery Parameter
console.adfin.com/dd-mandate/id?mode=popup
Generated when you create a direct debit requestThe UI will launch a

Adfin will call window.close automatically when the user clicks the "Close the window button".


🚧 You must use window.open and use query param = popup

You must launch with pop up with window.open() as otherwise the browser will not give permission for Adfin to close the window.


Edge case handling

If the page does not close, Adfin will show a copy saying that we are unable to close the window, and the user should close it and return to their previous browser.

Sign direct debit in full redirect


Example request

Use the following structure with the following requirements:

  1. Pass in the customer's ID and the direct debit mandate path
  2. Pass in the redirectUrl (it must be https).
curl --location --request PUT 'https://api.staging.adfin.com/api/customers/{id}/directdebitmandates' \
--header 'Content-Type: application/json' \
--data '{
    "redirectUrl":"https://www.google.com/maps"
}'

Example response

This response returns the following important information for this flow


{  
    ...
    "redirectUrl":"https://www.yoursite.com/redirect",
    "url": "https://console.adfin.com/dd-mandate/WiGr3EBGuORksFWPEX",
    "sender": {
        "name": "BillerName"
    },
    ...
}

Parameters:

  1. url - where you should redirect the customer to start the flow
  2. redirectUrl - where the customer will be sent after the flow is finished

Block progress until mandate is signed

Use this pattern when your platform must ensure that a customer signs a mandate before continuing. This may be used in a customer onboarding flow, eg. A customer must complete a mandate before they continue.

It is recommended that you use a new tab redirect to the URL here. While it can be rendered in an iframe, you will not be able to listen to front-end events.

1. Create a mandate:

//TODO add code

PUT /customers/id/directdebitmandates

Capture the redirectUrl from the response.

2. Redirect the user to the signing page.

Use the redirectURI provided in the mandate request. This is the adfin URI where a user will sign the mandate.

3. Gate progression:

On return or when the user clicks "next" or "continue":

  1. Call GET /customers/id/directdebitmandates
  2. Proceed only if the status is PENDING or ACTIVE.
  3. If status is CREATED, block and prompt to complete signing. This should be handled in your UI with the user.

This guide walks you through two steps:

  1. Create a Customer in Adfin.
  2. Trigger the Direct Debit mandate distribution workflow for that customer.
    1. If you already have a customer.id, you can skip to Step 2.

Distribute direct debit mandate using Adfin's workingflows

Use the Create Customer endpoint and capture the returned id. You will pass this ID to the mandate workflow in Step 2.

Consult the Customer Create endpoint schema in the Adfin API reference for the complete set of supported fields. Below is a minimal example request.

curl --location --request POST "https://sa.adfin.com/api/customers" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <YOUR_API_KEY>" \
  --data '{
    "name": "Acme LLP",
    "email": "billing@acme-llp.example",
    "metadata": {
      "externalCustomerRef": "acme-001"
    }
  }'
{
  "id": "e3af9a47-6e6c-456a-9a27-e5ebc0a4e3ee",
  "name": "Acme LLP",
  "email": "billing@acme-llp.example",
  "createdAt": "2025-09-10T12:34:56Z",
  "metadata": {
    "externalCustomerRef": "acme-001"
  }
}

Step 2 — Distribute the Direct Debit mandate

Trigger the Direct Debit Mandate Authorisation workflow for your customer using the DD_MANDATE_AUTHORISATION type.

You can find full details for the payload in our API docs: https://docs.adfin.com/reference/createworkflow

curl --location --request PUT 'https://staging.adfin.com/api/workflows' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--data '{
    "name": "mandate chasing",
    "type": "DD_MANDATE_AUTHORISATION",
    "customerDetails": {
        "id": "e3af9a47-6e6c-456a-9a27-e5ebc0a4e3ee" <-- Generated by customer ID in Step 1
    },
    "customMessage": "hey custom message from request"
}'

Example response.

  1. Returns a templateId, not needed to store on your side
  2. Returns the state
  3. Adfin automatically schedules an Email reminder every 5 days until the mandate is signed.
{
    "templateId": "80137094-6ab4-4e54-9ae8-a81c385fdbdf",
    "customerDetails": {
        "id": "c8a9c8f7-f068-44d4-a3d7-d35f862b613a"
    },
    "invoiceDetails": {},
    "name": "mandate authorisation",
    "type": "DD_MANDATE_AUTHORISATION",
    "state": "PENDING",
    "events": [
        {
            "trigger": {
                "days": 0,
                "operator": "ON",
                "referenceDate": "SENT_DATE"
            },
            "triggerDate": "2025-09-17T06:43:12.637UTC",
            "type": "CREATE_DD_MANDATE",
            "state": "SCHEDULED"
        },
        {
            "frequency": {
                "timeUnit": "DAY",
                "frequency": 5
            },
            "trigger": {
                "days": 0,
                "operator": "ON",
                "referenceDate": "SENT_DATE"
            },
            "triggerDate": "2025-09-17T06:43:12.637UTC",
            "type": "SEND_MANDATE_AUTHORISATION_NOTIFICATION",
            "state": "SCHEDULED",
            "details": {
                "channel": "EMAIL",
                "templateId": "44444444-4444-4444-4444-444444444441",
                "customMessage": "<p>hey custom message from request</p>"
            }
        }
    ]
}

This will distribute the Direct debit to the specified customer.


Previous page
Next page