Introduction

If you are unfamiliar with Direct Debit and how it works in UNIPaaS, please refer to this article first.

If you are planning to or have implemented the UNIPaaS UI Web-Embeds, please refer to this article, which addresses implementing Direct Debit with UI Web-Embeds (highly recommended).

In this section, you will be guided through the steps necessary to create a custom Direct Debit flow within your platform’s embedded payment solution.

In addition, please refer to the Direct Debit webhooks you should subscribe to in order to make the most of the offering to vendors.

Finally, once you’ve completed your integration, you can test it using the Direct Debit test scenarios.

Direct Debit Flows

In order to use Direct Debit and implement its flows, there are several API endpoints you should use along the way. We will describe these flows as well as which API endpoints you should use in each step.

Set up a Direct Debit mandate

Description: A vendor wishes to set up a Direct Debit mandate with their customer to start collecting payments from them with Direct Debit.

Note

Within the Direct Debit context, “Collect”, “Collection” or “Collecting” refer to a Direct Debit payment (authorization).

Steps:

1. Once a customer is selected, use the “Get mandate” endpoint to check if this customer has a mandate set up or not. These are the possible statuses for mandates:
   • sent - A vendor has sent a mandate request to their customer.
   • pending_approval - The mandate has not yet been submitted to the customer’s bank OR the mandate has been submitted to the customer’s bank but has not been processed yet.
   • active - The mandate has been successfully set up by the customer’s bank.
   • declined - A technical error has occurred when trying to submit the mandate.
   • rejected - The mandate could not be created (rejected by Bacs).
   • cancelled - The mandate has been cancelled.
2. If there is no mandate at all for this customer, you will need to create a flow that lets your vendor request a mandate from their customer. Use our Mandate Request UI Web-Embed (recommended) or the “Request mandate from customer” endpoint to trigger a request to this customer. This will send an email with a link to the mandate flow for the customer to complete.
3. In case a significant time has passed and the customer has not submitted their mandate, you can create a “resend” flow to let the vendor send an additional reminder to their customer to complete their mandate.
   To do this, use the “Resend mandate request” endpoint to trigger a resend to this customer. This will send an email with the same original link to the mandate flow for the customer to complete.

Important

Direct Debit collections can only be made if there is a mandate in place and it is in one of the following statuses: sent, pending_approval or active.

For sent and pending_approval, the collection will be pending until the mandate has been activated (active status).

For active, the collection will be made.

Tip

We strongly recommend implementing a mandate set up flow from your vendors’ customer list.

Collect payments with Direct Debit

Description: A vendor wishes to collect payments (either one-offs or recurring) from their customer by Direct Debit.

Steps:

1. If the selected customer does not have a mandate set up yet, first set one up.
2. Once the mandate has been set up, you have the following options to collect a payment with Direct Debit:

• For an invoice in your system, use the “Invoice Endpoint” to trigger a Direct Debit collection (payment).

Note

This should be triggered when the invoice is saved.

• For a payment that is does not have an invoice associated with it, you can collect the payment using the /pay-ins /checkout endpoint to trigger a Direct Debit collection (payment), following your own billing/recurring logic.

‘POST’ ‘https://sandbox.unipaas.com/platform/pay-ins/checkout’

Request example:

JSON

{
  "country": "GB",
  "amount": 21,
  "currency": "GBP",
  "email": "email@email.com",
  "vendorId": "680b81e88f595625dc584e6d",
  "consumerReference": "test001",
  "shippingSameAsBilling": true,
  "items": [],
  "dueDate": "2025-10-10",
  "offlinePayment": true,
  "paymentMethods": ["directDebit"]
}

Response example

JSON

{
    "status": "open",
    "mode": "offline",
    "plans": [],
    "isMoto": false,
    "id": "69aebfc03b64c429eaf72fc9",
    "country": "GB",
    "amount": 21,
    "currency": "GBP",
    "reference": "test001",
    "items": [],
    "dueDate": "2025-11-05T00:00:00.000Z",
    "paymentMethods": [
        "directDebit"
    ],
    "vendor": {
        "name": "Unipaas",
        "email": "test.test@example.com",
        "country": "GB"
    },
    "totalAmount": 21,
    "totalPaid": 0,
    "expiresAt": "2025-11-05T00:00:00.000Z",
    "shortLink": "https://sandbox-checkout.unipaas.com/CUb45tcmWX/",
    "merchantId": "6808db2fd8d8f56be334bd4a",
    "signedLinkId": "CUb45tcmWX",
    "consumerId": "69a5725633870dc148b98c8f",
    "createdAt": "2025-10-09T12:40:32.314Z",
    "updatedAt": "2025-10-09T12:40:32.314Z",
    "sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudElkIjoiNjgwOGRiMmZkOGQ4ZjU2YmUzMzRiZDRhIiwibWVyY2hhbnROYW1lIjoiU3RydWR3aWNrTHRkIiwiYW1vdW50IjoyMSwib3JpZ2luYWxBbW91bnQiOjIxLCJjdXJyZW5jeSI6IkdCUCIsImVtYWlsIjoiYW1pdC5tZWxpY2hlc0B1bmlwYWFzLmNvbSIsImNvdW50cnkiOiJHQiIsInNlbGxlcklkIjoiNjgwYjgxZTg4ZjU5NTYyNWRjNTg0ZTZkIiwidmVuZG9ySWQiOiI2ODBiODFlODhmNTk1NjI1ZGM1ODRlNmQiLCJzY29wZXMiOlsid2Vic2RrX2FjY2VzcyIsImRpcmVjdF9kZWJpdF9yZWFkIiwiZGlyZWN0X2RlYml0X3dyaXRlIl0sInBheW1lbnRNZXRob2RzIjpbImRpcmVjdERlYml0Il0sImlzUmVjdXJyaW5nIjpmYWxzZSwiY29uc3VtZXJJZCI6IjY5YTU3MjU2MzM4NzBkYzE0OGI5OGM4ZiIsImNvbnN1bWVyIjp7InJlZmVyZW5jZSI6IlBlbm5pbGVzc190ZXN0MDAxIn0sImVudiI6InNhbmRib3giLCJwYXltZW50TGlua0lkIjoiQ1ViNDV0Y21XTyIsImR1ZURhdGUiOiIyMDI2LTAzLTA5IiwiaWF0IjoxNzczMDYwMDMzLCJleHAiOjE3NzMxNDY0MzN9.zGJjW_MTXCVmtK9TD4YrdHOtTeLPy87sqgMH7vXVqIo",
    "authorizationId": "69aebfc03b64c43f2cf72fcb",
    "paymentOptions": [],
    "qrPaymentLink": "https://sandbox.unipaas.com/platform/qr-code/generate?url=https://sandbox-checkout.unipaas.com/CUb45tcmWO/",
    "vendorId": "680b81e88f595625dc584e6d",
    "consumer": {
        "reference": "test001",
        "billingAddress": {
            "line1": "41 Chalton Street, London NW1 1JD",
            "city": "London",
            "state": "England",
            "postalCode": "NW1 1JD",
            "country": "GB"
        },
        "email": "email@email.com",
        "name": "Test",
        "phone": "+44 07920 000000",
        "shippingAddress": {
            "line1": "41 Chalton Street, London NW1 1JD",
            "city": "London",
            "state": "England",
            "postalCode": "NW1 1JD",
            "country": "GB"
        },
        "shippingSameAsBilling": true
    }
}

Note

Leverage the Mandate and Direct Debit statuses delivered via webhooks to keep track of the lifecycle of the mandate and direct debit flow.

Statuses: [/docs/direct-debit-status/)

Webhooks: [/docs/webhooks-and-notifications/)

Cancel a collection

Description: A vendor wishes to cancel a Direct Debit collection.

Important

Direct Debit collections can only be cancelled until they are submitted to Bacs.

In UNIPaaS, this is as long as they haven’t reached Submitted status. Once submitted, collections cannot be cancelled.

Steps:

1. Use the “Cancel collection” endpoint to cancel the collection.

Update a collection

Description: A vendor wishes to change a Direct Debit collection amount or due date.

Note

Currently, only payment amount or due date changes are supported.

Important

Direct Debit collections can only be updated until they are submitted to Bacs.

In UNIPaaS, this is as long as they haven’t reached Submitted status. Once submitted, collections cannot be updated.

Steps:

• For a Direct Debit collection that was created with the “Invoice Endpoint”, update with “PATCH Invoice Endpoint” to trigger a Direct Debit collection (payment).
• For a payment that was created with the “Create Checkout” endpoint, update with “PATCH Checkout” (TBD) endpoint.

Note

When a change is made to a Direct Debit payment, UNIPaaS will cancel the original collection, and immediately create a new one instead.

Update a payment method

Description: A vendor wishes to change a Direct Debit collection to a different payment method (e.g., card or Open Banking) or vise versa.

Important

The Direct Debit payment method can only be changed until the collections are submitted to Bacs.

In UNIPaaS, this is as long as they haven’t reached Submitted status. Once submitted, the payment method cannot be changed.

Steps:

• For a Direct Debit collection that was created with the “Invoice Endpoint”, update with “PATCH Invoice Endpoint” to trigger a Direct Debit collection (payment).
• For a payment that was created with the “Create Checkout” endpoint, update with “PATCH Checkout” (TBD) endpoint.

Note

When a payment is changed from the Direct Debit payment method, UNIPaaS will cancel the Direct Debit collection.

Cancel a mandate

Description: A vendor wishes to cancel a Direct Debit mandate for their customer.

Steps:

1. Use the “Cancel mandate” endpoint to cancel that specific mandate.

️ Warning

When a mandate is cancelled, ALL outstanding Direct Debit collections that can be cancelled will be cancelled.

In addition, new collections will not be possible after a mandate is cancelled.

Aggregate mandates and collections

Description: Allow your vendors to see all their Direct Debit mandates and collections in one place in your platform (e.g., on the customer list).

Steps:

1. To get all the Direct Debit mandates for a vendor, use the “Get all mandates” endpoint.
2. To get all the Direct Debit collections for a vendor, use the “Get all collections” (TBD) endpoint.

Drill through a mandate or collection

Description: Get additional information about a specific Direct Debit mandate or collection.

Steps:

1. To get the details of a Direct Debit mandate, use the “Get mandate” endpoint.
2. To get the details of a Direct Debit collection, use the “Get collection” (TBD) endpoint.

If you have any questions or require further assistance during the implementation process, please don’t hesitate to contact our team.

Test your Direct Debit integration

See Direct Debit Test Scenarios.

Direct Debit API Endpoints

Get a customer’s mandate

Use the following GET request:

{unipaas_host}}/platform/vendors/{{vendor_id}}/consumers/reference/{{consumer_reference}}/mandates

Response example:

JSON

{
    "id": "64c74e2eb7d492861897cb41",
    "vendor": {
        "id": "64b6a89e5dcbc5de96ff8ebc",
        "name": "Dunder Mifflin",
        "email": "jan.levinson.gould@dundermifflin.com"
    },
    "merchant": {
        "id": "633a93e2599b587a1781d41e",
        "name": "UNIPAAS FINANCIAL SERVICES LIMITED"
    },
    "status": "active",
    "consumer": {
        "id": "64c257d27f58cc0138ef06e7",
        "name": "Pam Beesly",
        "reference": "pam-1",
        "email": "pam.beesly@dundermifflin.com",
        "firstName": "Pam",
        "lastName": "Beesly"
    },
    "mandateCreationFormLink": "1BTE1FHTgDJQCCxu14F5S",
    "createdAt": "2023-07-27T11:41:06.721Z",
    "updatedAt": "2023-07-27T11:42:22.988Z",
    "v": 0,
    "bankAccount": {
        "iban": "GB46BUKB20041538290008",
        "name": "BARCLAYS BANK UK PLC",
        "bankCode": "200415",
        "holderName": "Pam Beesly",
        "accountNumber": "38290008",
        "country": "GB"
    },
    "processorReferenceId": "MD000V8YR5AQM5",
    "reference": "59NKT5Q-dunder-mif",
    "paymentOptionId": "64c2581e19c84a151aaaf87c"
}

Create a mandate and send it to the customer

Use the following POST request:

{{unipaas_host}}/platform/vendors/{{vendor_id}}/mandates

Request example:

JSON

{
    "consumer": {
        "name": "Michael Scott",
        "email": "michael.scott@dundermifflin.com",
        "reference": "michael-1"
    },
    "createMandateLink": true,
    "sendEmail": true,
    "requestMandateEmailObject": {
        "subject": "Mandate email subject",
        "body": "Mandate email body"
    }
}

Name	Type	Required	Description
consumer.name	string	YES	The name of the customer who will receive the mandate request.
consumer.email	string	YES	The email to which the mandate request will be sent.
consumer.reference	string	YES	The consumer reference as was sent to UNIPaaS.
createMandateLink	string	YES	Must be set to true.
sendEmail	string	NO	true or false. Dictates if an email is sent to the consumer.email
requestMandateEmailObject.subject	string	NO	The subject that will appear in the email received by the customer. E.g.: “{{consumerName}}, Please Set Up A Direct Debit Mandate”. Required if sendEmail = true
requestMandateEmailObject.body	string	NO	The body that will appear in the email received by the customer. E.g.: “Hi {{consumerName}}, {{vendorName}} would like to set up a Direct Debit mandate with you in order to automatically collect payments for future invoices. Once this is set up, you won’t need to manually pay each invoice - {{vendorName}} can automatically collect from your bank account.” Required if sendEmail = true

Response example:

JSON

{
    "mandate": {
        "id": "64c74e2eb7d492861897cb41",
        "vendor": {
            "id": "64b6a89e5dcbc5de96ff8ebc",
            "name": "Dunder Mifflin",
            "email": "jan.levinson.gould@dundermifflin.com"
        },
        "merchant": {
            "id": "633a93e2599b587a1781d41e",
            "name": "UNIPAAS FINANCIAL SERVICES LIMITED"
        },
        "status": "sent",
        "consumer": {
            "id": "64c74e2e7f58cc0138697910",
            "name": "Michael Scott",
            "reference": "michael-1",
            "email": "michael.scott@dundermifflin.com"
        },
        "mandateCreationFormLink": "AQZ1kWYt58wSsEjF5qz7d",
        "createdAt": "2023-07-31T06:01:18.732Z",
        "updatedAt": "2023-07-31T06:01:18.732Z",
        "v": 0
    },
    "link": {
        "refreshToken": [],
        "views": [
            "direct_debit"
        ],
        "vendorId": "64b6a89e5dcbc5de96ff8ebc",
        "merchantId": "633a93e2599b587a1781d41e",
        "consumerId": "64c74e2e7f58cc0138697910",
        "email": "michael.scott@dundermifflin.com",
        "id": "64c74e2e5dcbc574b4ff8f46",
        "uniqueId": "AQZ1kWYt58wSsEjF5qz7d",
        "expiresAt": "2023-08-14T06:01:18.711Z",
        "status": "sent",
        "supportEmail": null,
        "createdAt": "2023-07-31T06:01:18.714Z",
        "updatedAt": "2023-07-31T06:01:18.714Z",
        "v": 0,
        "url": "https://sandbox-hosted.unipaas.com/consumers/64c74e2e7f58cc0138697910/AQZ1kWYt58wSsEjF5qz7d/mandate"
    }
}

Resend a mandate to the customer

Use the following POST request:

{{unipaas_host}}/platform/vendors/{{vendor_id}}/mandates/{{mandate_id}}/send

Request example:

JSON

{
    "subject": "{{consumer_name}}, Please Set Up A Direct Debit Mandate",
    "body": "Hi {{consumer_name}},<br />John Doe would like to set up a Direct Debit mandate with you in order to automatically collect payments for future invoices. <br />Once this is set up, you won’t need to manually pay each invoice - John Doe can automatically collect from your bank account."
}

Cancel a Direct Debit collection

Use the following POST request:

{{unipaas_host}}/platform/pay-ins/{{authorization_id}}/void

Cancel a Direct Debit mandate

Use the following POST request:

{{unipaas_host}}/platform/vendors/{{vendor_id}}/mandates/{{mandate_id}}/cancel

Get all mandates for a vendor

Use the following GET request:

{{unipaas_host}}/platform/vendors/{{vendor_id}}/mandates

Response example:

JSON

{
    "items": [
        {
            "id": "64c207e7b7d4928c1a971d24",
            "vendor": {
                "id": "64b6a89e5dcbc5de96ff8ebc",
                "name": "Dunder Mifflin",
                "email": "jan.levinson.gould@dundermifflin.com"
            },
            "merchant": {
                "id": "633a93e2599b587a1781d41e",
                "name": "UNIPAAS FINANCIAL SERVICES LIMITED"
            },
            "status": "pending_approval",
            "consumer": {
                "id": "64c207e77f58cc0138e60251",
                "name": "Michael Scott",
                "reference": "michael-1",
                "email": "michael.scott@dundermifflin.com",
                "firstName": "Michael",
                "lastName": "Scott"
            },
            "mandateCreationFormLink": "AQZ1kWYt58wSsEjF5qz7d",
            "createdAt": "2023-07-27T06:00:07.859Z",
            "updatedAt": "2023-07-27T08:59:21.611Z",
            "v": 0,
            "bankAccount": {
                "id": "64c231e619c84a2312aaf808",
                "iban": "GB46BUKB20041538290008",
                "name": "BARCLAYS BANK UK PLC",
                "bankCode": "200415",
                "holderName": "Michael Scott",
                "accountNumber": "38290008",
                "country": "GB"
            },
            "processorReferenceId": "MD000V8W3HCR30",
            "reference": "YVM9JP6-dunder-mif"
         },
         {
            "id": "64c257d2b7d4927b4e9727a6",
            "vendor": {
                "id": "64b6a89e5dcbc5de96ff8ebc",
                "name": "Dunder Mifflin",
                "email": "jan.levinson.gould@dundermifflin.com"
            },
            "merchant": {
                "id": "633a93e2599b587a1781d41e",
                "name": "UNIPAAS FINANCIAL SERVICES LIMITED"
            },
            "status": "active",
            "consumer": {
                "id": "64c257d27f58cc0138ef06e7",
                "name": "Pam Beesly",
                "reference": "pam-1",
                "email": "pam.beesly@dundermifflin.com",
                "firstName": "Pam",
                "lastName": "Beesly"
            },
            "mandateCreationFormLink": "1BTE1FHTgDJQCCxu14F5S",
            "createdAt": "2023-07-27T11:41:06.721Z",
            "updatedAt": "2023-07-27T11:42:22.988Z",
            "v": 0,
            "bankAccount": {
                "id": "64c2580919c84a207eaaf874",
                "iban": "GB46BUKB20041538290008",
                "name": "BARCLAYS BANK UK PLC",
                "bankCode": "200415",
                "holderName": "Pam Beesly",
                "accountNumber": "38290008",
                "country": "GB"
            },
            "processorReferenceId": "MD000V8YR5AQM5",
            "reference": "59NKT5Q-dunder-mif",
            "paymentOptionId": "64c2581e19c84a151aaaf87c"
         },
         {
            "id": "64c2c37db7d492bd609735bf",
            "vendor": {
                "id": "64b6a89e5dcbc5de96ff8ebc",
                "name": "Dunder Mifflin",
                "email": "jan.levinson.gould@dundermifflin.com"
            },
            "merchant": {
                "id": "633a93e2599b587a1781d41e",
                "name": "UNIPAAS FINANCIAL SERVICES LIMITED"
            },
            "status": "rejected",
            "consumer": {
                "id": "64c2c37d7f58cc0138f98c33",
                "name": "Dwight Schrute",
                "reference": "dwight-1",
                "email": "dwight.k.schrute@dundermifflin.com",
                "firstName": "Dwight",
                "lastName": "Schrute"
            },
            "mandateCreationFormLink": "qRO6T5M2CoHgvk-w-se88",
            "createdAt": "2023-07-27T19:20:29.048Z",
            "updatedAt": "2023-07-27T19:22:39.535Z",
            "v": 0,
            "bankAccount": {
                "id": "64c2c3f019c84a9872aaf968",
                "iban": "GB46BUKB20041538290008",
                "name": "BARCLAYS BANK UK PLC",
                "bankCode": "200415",
                "holderName": "Dwight Schrute",
                "accountNumber": "38290008",
                "country": "GB"
            },
            "processorReferenceId": "MD000V97QD8HND",
            "reference": "8MKZR36-dunder-mif",
            "processorErrorReason": "invalid_bank_details"
         },
    ],
    "totals": [
        {
            "count": 3
        }
    ]
}