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' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--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:

curl --location --request PUT 'https://api.staging.adfin.com/api/customers/{id}/directdebitmandates' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --data '{
    "redirectUrl": "https://www.yoursite.com/redirect"
  }'

Capture the mandate id and url from the response.

2. Redirect the user to the signing page.

Use the url returned in the mandate response. This is the Adfin page where the user signs the mandate.

3. Gate progression:

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

  1. Call GET /customers/directdebitmandates/{mandateId} with the mandate id from step 1.
  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"
  },
  "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