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

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.

Launch the new window

To launch your direct debit mandate in a new window, use the following code:

window.open(
  "https://console.adfin.com/dd-mandate/{direct-debit-id}?mode=popup"
)

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

Handle edge cases

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).

The response contains

  1. The redirectUrl confirmation per the request
  2. The new URL to redirect for the user to sign the mandate
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"
}'

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.

Distribute direct debit mandate using Adfin's workflows

You must create a customer before this step is possible

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

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