Guides
GuidesAPI ReferenceCreate Your Account

Implement Direct Debit Via API

Suggest Edits

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, use the "Create Checkout" endpoint to trigger a Direct Debit collection (payment).

📘

Note

For each payment created, you will need to add the paymentMethod parameter and set it to directDebit. Without this parameter, UNIPaaS will not identify the created payment as one that should be collected with Direct Debit.

However, if the payment is made in a flow that includes the Invoice UI Web-Embed, DO NOT add the paymentMethod parameter.

📘

Note

In order to enable Direct Debit within your recurring payment creation mechanism, for each recurring payment created, you will need to add the paymentMethod parameter and set it to directDebit, similarly to a one-off collection.

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:

📘

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:

📘

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:

{
    "id": "64c74e2eb7d492861897cb41",
    "vendor": {
        "id": "64b6a89e5dcbc5de96ff8ebc",
        "name": "Dunder Mifflin",
        "email": "[email protected]"      
    },
    "merchant": {
        "id": "633a93e2599b587a1781d41e",
        "name": "UNIPAAS FINANCIAL SERVICES LIMITED"
    },
    "status": "active",
    "consumer": {
        "id": "64c257d27f58cc0138ef06e7",
        "name": "Pam Beesly",
        "reference": "pam-1",
        "email": "[email protected]",
        "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:

{
    "consumer": {
        "name": "Michael Scott",
        "email": "[email protected]",
        "reference": "michael-1"
    },
    "createMandateLink": true,
    "requestMandateEmailObject": {
        "subject": "Mandate email subject",
        "body": "Mandate email body"
    }
}
NameTypeRequiredDescription
consumer.namestringYESThe name of the customer who will receive the mandate request.
consumer.emailstringYESThe email to which the mandate request will be sent.
consumer.referencestringYESThe consumer reference as was sent to UNIPaaS.
createMandateLinkstringYESMust be set to true.
requestMandateEmailObject.subjectstringYESThe subject that will appear in the email received by the customer. E.g.:
"{{consumerName}}, Please Set Up A Direct Debit Mandate"
requestMandateEmailObject.subjectstringYESThe 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."

Response example:

{
    "mandate": {
        "id": "64c74e2eb7d492861897cb41",
        "vendor": {
            "id": "64b6a89e5dcbc5de96ff8ebc",
            "name": "Dunder Mifflin",
            "email": "[email protected]"
        },
        "merchant": {
            "id": "633a93e2599b587a1781d41e",
            "name": "UNIPAAS FINANCIAL SERVICES LIMITED"
        },
        "status": "sent",
        "consumer": {
            "id": "64c74e2e7f58cc0138697910",
            "name": "Michael Scott",
            "reference": "michael-1",
            "email": "[email protected]"
        },
        "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": "[email protected]",
        "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:

{
    "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:

{
    "items": [
        {
            "id": "64c207e7b7d4928c1a971d24",
            "vendor": {
                "id": "64b6a89e5dcbc5de96ff8ebc",
                "name": "Dunder Mifflin",
                "email": "[email protected]"
            },
            "merchant": {
                "id": "633a93e2599b587a1781d41e",
                "name": "UNIPAAS FINANCIAL SERVICES LIMITED"
            },
            "status": "pending_approval",
            "consumer": {
                "id": "64c207e77f58cc0138e60251",
                "name": "Michael Scott",
                "reference": "michael-1",
                "email": "[email protected]",
                "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": "[email protected]"
            },
            "merchant": {
                "id": "633a93e2599b587a1781d41e",
                "name": "UNIPAAS FINANCIAL SERVICES LIMITED"
            },
            "status": "active",
            "consumer": {
                "id": "64c257d27f58cc0138ef06e7",
                "name": "Pam Beesly",
                "reference": "pam-1",
                "email": "[email protected]",
                "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": "[email protected]"
            },
            "merchant": {
                "id": "633a93e2599b587a1781d41e",
                "name": "UNIPAAS FINANCIAL SERVICES LIMITED"
            },
            "status": "rejected",
            "consumer": {
                "id": "64c2c37d7f58cc0138f98c33",
                "name": "Dwight Schrute",
                "reference": "dwight-1",
                "email": "[email protected]",
                "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
        }
    ]
}

Updated about 1 year ago