# Implement Direct Debit Via API # Introduction If you are unfamiliar with Direct Debit and how it works in Unipaas, please refer to [this article](/docs/direct-debit/) first. If you are planning to or have implemented the Unipaas UI Web-Embeds, please refer to [this article](/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](/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](/docs/direct-debit-test-scenarios/). # Direct Debit Flows In order to use Direct Debit and implement its flows, there are several [API endpoints](/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](/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](/docs/ui-web-embeds-integration-guide/#mandate-request) (**recommended**) or the "[Request mandate from customer](/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](/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](/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](/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' '' Request example: * JSON ```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 ```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](/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](/docs/invoices/#update-invoice)", update with "[PATCH Invoice Endpoint](/reference/#tag/vendor/PATCH/vendors/%7BvendorId%7D/invoices/%7BinvoicesId%7D)" to trigger a Direct Debit collection (payment). * For a payment that was created with the "[Create Checkout](/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](/docs/invoices/#update-invoice)", update with "[PATCH Invoice Endpoint](/reference/#tag/vendor/PATCH/vendors/%7BvendorId%7D/invoices/%7BinvoicesId%7D)" to trigger a Direct Debit collection (payment). * For a payment that was created with the "[Create Checkout](/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](/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](/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](/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](/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](/reference/#tag/vendor/GET/vendors/%7BvendorId%7D/consumers/%7BconsumerId%7D/mandates) Response example: * JSON ```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](/reference/#tag/vendor/POST/vendors/%7BvendorId%7D/mandates) Request example: * JSON ```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 ```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](/reference/#tag/vendor/POST/vendors/%7BvendorId%7D/mandates/%7BmandateId%7D/send) Request example: * JSON ```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](/reference/#tag/payin/POST/pay-ins/%7BauthorizationId%7D/void) ### Cancel a Direct Debit mandate Use the following POST request: [{{unipaas\_host}}/platform/vendors/{{vendor\_id}}/mandates/{{mandate\_id}}/cancel](/reference/#tag/vendor/POST/vendors/%7BvendorId%7D/mandates/%7BmandateId%7D/cancel) ### Get all mandates for a vendor Use the following GET request: [{{unipaas\_host}}/platform/vendors/{{vendor\_id}}/mandates](/reference/#tag/vendor/GET/vendors/%7BvendorId%7D/mandates) Response example: * JSON ```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 } ] } ```