Introduction

This guide explains how to manage Direct Debit mandates via the Adfin API, including creating, fetching, and scheduling mandate authorisation flows. It outlines mandate statuses, the customer signing process, UI gating patterns, and best practices for implementation, with practical examples for seamless integration.

Glossary

Quick reference if you are not used to direct debit flows, or payment implementations.

• Mandate: A customer’s authorisation that allows a business to collect Direct Debit payments from their bank account.
• Collections: The process of automatically withdrawing funds from a customer’s bank account based on the agreed payment schedule.
• Redirect URL: A secure link where the customer completes the mandate signing process.

Mandate Lifecycle

A mandate will have a status which refers to what the customer, or you, can do with the mandate.

⚠️ If cancelled by a bank, failureReason may be present. It is not human-readable and should not be displayed.

Creating mandate requests

Request

All mandates start with mandate creation. A customer will have a direct debit created against their specific customer ID. Make sure you read the mandate behaviour here.

http://staging.adfin.com/api/customers/id/directdebitmandates

curl --request PUT
     --url <http://staging.adfin.com/api/customers/{id}/directdebitmandates>
     --header 'accept: application/json

📘

Mandate behaviour

• If the customer has a no mandate, a new one is created
• If the customer has an active or pending mandate, no new one is created.
• A URL is returned where the user should be redirected to complete the signing process.
• If the mandate is cancelled a new one is generated. This allows you to support new mandate processes within Adfin. Cancellations can be user triggered, platform triggered, or bank triggered. You should be ready to be able to support new mandate signatures if they are cancelled

Response

Returns a redirectUrl which must be used to redirect the user to complete the mandate setup.

You can see the full details of the response here: https://docs.adfin.com/reference/create#/

Redirect URI: Adfin provides a redirect URI for you to send the user too, you should use this to get the mandate signed. The mandate will only moved to PENDING once the user has completed this form, else it will stay in CREATED.

Next Step: Redirect the user to the url to complete the mandate.

{
    "id": "WiGr3EBGuORksFWPEj",
    "creationTime": "2025-05-23T14:50:32.132UTC",
    "status": "CREATED",
    "customer": {
        "id": "54e2ffc3-560e-413d-aadb-bfd8f8af4de6",
        "name": "Adfin financial services Ltd",
        "people": [
            {
                "firstName": "Nathan",
                "lastName": "Hall",
                "email": "[email protected]",
                "phoneNo": "+09876543211"
            }
        ],
        "addresses": [
            {
                "city": "London",
                "postalCode": "1245",
                "country": "UK",
                "addressLine1": "Street"
            }
        ],
        "directDebitMandate": {
            "status": "CREATED"
        },
        "timezone": "Europe/London"
    },
    "url": "<https://adfin.com/dd-mandate/WiGr3EBGuORksFWPEj>",
    "sender": {
        "name": "MyNewPlatform"
    },
    "bankAccountNumber": "redacted"
}

Next Step: Redirect the user to the url to complete mandate signing.

Fetching a Customer's Mandate

To retrieve the latest mandate status for a customer, use:

Endpoint GET /customers/id

It returns the full customer profile, the directDebitMandate field contains the latest mandate.

Response example (includes just the relevant fields for this guide)

{
	"id": "54e2ffc3-560e-413d-aadb-bfd8f8af4de6",
	"directDebitMandate": \{
	"id": "WiGr3EBGuORksFWPEj",
	"status": "PENDING",
  "lastUpdatedTime": "2025-05-23T15:05:00Z"
}

Scheduling Mandate Authorisation Emails and Reminders

Adfin handles all of your email requests and chasers for you - helping you get your direct debits signed. This is referred to as a "Schedule" in Adfin, which controls your email workflows for direct debit chasing.

To send an authorization email and reminder flow, create a schedule:

Endpoint PUT /schedules

Request Body (example)

{
  "customerDetails": {
    "id": "customer-id"
  },
  "type": "DD_MANDATE_AUTHORISATION"
}

📘

Behaviour of schedules

If the customer has no mandate or a CANCELLED mandate:

• Schedule will trigger the email and reminders.

If the customer has an existing mandate in any other state:

• No new mandate is created

Returns 200 OK with existing schedule.

Blocking Flow Pattern: Mandate Required Before Progression

Use this pattern when your platform must ensure 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 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:

PUT /customers/id/directdebitmandates

Capture the redirectUrl from the response.

Example payload: https://app.adfin.com/dd-mandate/WmWd0Tg6RiwVTGnSVQ

2. Redirect user to the signing page.

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

3. Gate progression:

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

1. Call GET /customers/id/directdebitmandates
2. Proceed only if 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.

Tips for Implementation

• IgnorefailureReason: Only relevant for debugging cancellations by banks.
• Label mandates based on status for consistent UI/UX.
• Use schedule templates to automate reminders and retries.
• Idempotent behavior: re-triggering on a customer with a valid mandate won’t create duplicates.