# Implement Direct Debit Via API # Introduction If you are unfamiliar with Direct Debit and how it works in UNIPaaS, please refer to [this article](https://docs.unipaas.com/docs/direct-debit) first. If you are planning to or have implemented the UNIPaaS UI Web-Embeds, please refer to [this article](https://docs.unipaas.com/docs/implement-direct-debit-with-ui-web-embeds), 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](https://docs.unipaas.com/docs/webhooks-and-notifications) 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](https://docs.unipaas.com/docs/direct-debit-test-scenarios). # Direct Debit Flows In order to use Direct Debit and implement its flows, there are several [API endpoints](https://docs.unipaas.com/docs/implement-direct-debit-via-api#get-a-customers-mandate) 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](https://docs.unipaas.com/docs/implement-direct-debit-via-api#get-a-customers-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](https://docs.unipaas.com/docs/ui-web-embeds-integration-guide#mandate-request) (**recommended**) or the "[Request mandate from customer](https://docs.unipaas.com/docs/implement-direct-debit-via-api#create-a-mandate-and-send-it-to-the-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](https://docs.unipaas.com/docs/implement-direct-debit-via-api#resend-a-mandate-to-the-customer)" 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](https://docs.unipaas.com/docs/implement-direct-debit-via-api#set-up-a-direct-debit-mandate). 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](https://docs.unipaas.com/docs/invoices#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](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: [https://docs.unipaas.com/docs/direct-debit-status#/](https://docs.unipaas.com/docs/direct-debit-status#/) > > Webhooks: [https://docs.unipaas.com/docs/webhooks-and-notifications#/](https://docs.unipaas.com/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](https://docs.unipaas.com/docs/implement-direct-debit-via-api#cancel-a-direct-debit-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](https://docs.unipaas.com/docs/invoices#update-invoice)", update with "[PATCH Invoice Endpoint](https://docs.unipaas.com/reference/invoicecontroller_updateinvoice)" to trigger a Direct Debit collection (payment). * For a payment that was created with the "[Create Checkout](https://docs.unipaas.com/docs/create-payment)" 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](https://docs.unipaas.com/docs/invoices#update-invoice)", update with "[PATCH Invoice Endpoint](https://docs.unipaas.com/reference/invoicecontroller_updateinvoice)" to trigger a Direct Debit collection (payment). * For a payment that was created with the "[Create Checkout](https://docs.unipaas.com/docs/create-payment)" 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](https://docs.unipaas.com/docs/implement-direct-debit-via-api#cancel-a-direct-debit-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](https://docs.unipaas.com/docs/implement-direct-debit-via-api#get-all-mandates-for-a-vendor)" 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](https://docs.unipaas.com/docs/implement-direct-debit-via-api#get-a-customers-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](https://docs.unipaas.com/docs/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](https://docs.unipaas.com/reference/mandatecontroller_getmandatebyconsumerid) 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](https://docs.unipaas.com/reference/mandatecontroller_createmandate) 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](https://docs.unipaas.com/reference/mandatecontroller_sendmandate) Request example: ```json { "subject": "{{consumer_name}}, Please Set Up A Direct Debit Mandate", "body": "Hi {{consumer_name}},
John Doe 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 - 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](https://docs.unipaas.com/reference/websdkpayincontroller_payinvoid) ### Cancel a Direct Debit mandate Use the following POST request: [\{\{unipaas_host}}/platform/vendors/\{\{vendor_id}}/mandates/\{\{mandate_id}}/cancel](https://docs.unipaas.com/reference/mandatecontroller_cancelmandate) ### Get all mandates for a vendor Use the following GET request: [\{\{unipaas_host}}/platform/vendors/\{\{vendor_id}}/mandates](https://docs.unipaas.com/reference/mandatecontroller_getmandates) 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 } ] } ```