GuidesAPI ReferenceCreate Your Account

Implement Direct Debit With UI Web-Embeds

Suggest Edits

General overview

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

In this section, you will be guided through the steps necessary to implement the Direct Debit payment method within your embedded payments solution, by leveraging the UNIPaaS UI Web-Embeds. Applying these will significantly reduce the integration effort required by your team to add Direct Debit to your offering.

The following UI Web-Embeds/services are required for Direct Debit to work:

Sequence diagram for a Direct Debit collection flow:

How to implement

Invoice endpoint

  • In order to trigger Direct Debit collections (both one-off and recurring), it is required to use the invoice endpoint. This provides us with the relevant information for a Direct Debit collection.
  • Learn about this service and how to implement it here.
  • Handling recurring invoices - see here.
  • UNIPaaS will support changes made to invoices that are due to be collected via Direct Debit. We currently support changes in invoice amount or due date. You will need to inform us of these changes via the update invoice method.
  • Invoice endpoint attributes:
NameIs RequiredTypeDescription
currencyYesISO 4217The currency of the invoice
totalAmountYesNumberThe total invoice amount
totalPaidNoNumberThe total amount paid so far on this invoice.
If not provided, will be set to 0 by default.
referenceYesStringThe invoice number on your system.
batchIdNoStringThe ID of the batch that this invoice was included in.
vatAmountNoNumberThe total VAT amount for the invoice (can be 0).
If not provided, will be set to 0 by default.
publicUrlNoStringA public URL to the invoice PDF version.
dueDateYesDateThe invoice due date.
lineItemsYesArray Line item object - see table below.
CustomerYesObjectCustomer object - see table below.
paymentStatusYesEnumCurrent invoice payment status:
Unpaid = unpaid
Paid = paid
Partially Paid = partially_paid
Refunded = refunded
PartiallyRefunded = partially_refunded
paymentMethodsNoArray, EnumStates which payment methods will be available for this specific invoice.
Note: If Direct Debit is selected, the invoice cannot be paid with UNIPaaS in any other method.

Available Payment Methods:
creaditCard
bankTransfer
directDebit
offlineBankTransfer
paypal

Important - when the Invoice UI Web-Embed is not implemented (e.g., in the recurring payment flow), it is critical to send this parameter with directDebit for every recurring payment if Direct Debit is to be used to collect the payment.

*Based on platform configuration
invoiceObjectNoObjectThe invoice object in its original form as created on your platform.
isRecurringYesBooleanIndicates if this invoice is a recurring one.
subscriptionIdNoStringThe recurring invoice subscription identifier.

lineItem attributes:

NameIs RequiredTypeDescription
descriptionYesStringA description for a specific line item
amountYesNumberA price of a unit for a specific line item
quantityYesNumberThe quantity of a unit for a specific line item

customer attributes:

NameIs RequiredTypeDescription
referenceYesStringPlatform customer identifier.
nameYesStringThe customer full name.
idNoStringUNIPaaS customer identifier.
emailNoStringThe customer's email address.

Invoice

  • Learn about this UI Web-Embed here and learn how to install and implement it here.
  • Add invoice mode (create / edit / view), as described in the implementation guide. Mandatory.
  • Add invoice reference in all invoice modes that exist in your platform (create, edit, view). Mandatory.
  • Add customer reference. This lets UNIPaaS know if the customer has a Direct Debit mandate set up with the vendor. Mandatory.

Pay Portal

  • Learn about this UI Web-Embed here and learn how to install and implement it here.
  • There are no Direct Debit considerations for this implementation.

Mandate Request

  • Learn about this UI Web-Embed here and learn how to install and implement it here.
  • Ensuring that Direct Debit is enabled for the vendor is highly important before presenting them with the Mandate Request UI Web-Embed. This verification can be achieved through the GET/vendors/{vendorId}/payment-options/available endpoint.

Notification

  • Learn about this UI Web-Embed here and learn how to install and implement it here.
  • There are no Direct Debit considerations for this implementation.

🚧

Note

If you don't implement the Notification UI Web-Embed, you will need to implement the notification/create webhook and implement it in the flow of your choice. See more on the notification/create service here.

✅

Tip

We strongly recommend implementing a mandate set up flow from your vendors' customer list. See API implementation guide for more details.

Example of UI Web-Embeds implementation:

<!DOCTYPE html>
<html lang="en">
<head>
    <script type="application/javascript" src="https://cdn.unipaas.com/embedded-ui.js"></script>
    <meta charset="UTF-8">
    <title>Direct Debit</title>
</head>
<body>
<h1>Invoice:</h1>
<div id="invoice"></div>
<h1>Request Mandate:</h1>
<div id="request_mandate"></div>
<h1>Pay Portal:</h1>
<div id="pay_portal"></div>
<h1>Notification:</h1>
<div id="notification"></div>
<script type="text/javascript">
    async function getTokenToken() {
        const url = "https://sandbox.unipaas.com/platform/authorize";
        const secretKey = "gc2haOpujHMbKjAWk3UUWw==";
        const vendorId = "64f8744b29095f715494b228";
        const scopes = ["portal_read","portal_write","onboarding_write","invoice_read", "invoice_write"]
        const options = {
            method: "POST",
            headers: {
                "Accept": "application/json",
                "Authorization": `Bearer ${secretKey}`,
                "Content-Type": "application/json"
            },
            body: JSON.stringify({
                scopes,
                vendorId
            })
        };
        try {
            const response = await fetch(url, options);
            if (!response.ok) {
                throw new Error('Network response was not ok');
            }
            const data = await response.json();
            return data.accessToken; // Assuming the access token is in the response
        } catch (error) {
            console.error('There was a problem with the fetch operation:', error);
            return null;
        }
    }
    async function initializeUniPAAS() {
        const accessToken = await getTokenToken();
        if (accessToken) {
            const config_general = {
                paymentsEnabled: true,
                theme: {
                    colors: {
                        primaryColor: "#2F80ED",
                        secondaryColor: "#687B97",
                        accentTextColor: "#2F80ED",
                        primaryButtonColor: "#2F80ED"
                    },
                    fontFamily: "inherit",
                    boxShadow: "0px 3px 15px rgba(27, 79, 162, 0.11)"
                }
            }
            const components = unipaas.components(accessToken, config_general);
            const config_invoice = {
                mode: 'create',
                customer: {
                    reference: '1234xxx',
                    name: 'John Doe',
                    email: '[email protected]',
                },
                invoice: {
                    reference: 'INV-1234xxxx',
                }
            };
            const invoice = components.create("invoice", config_invoice);
            invoice.mount("#invoice");
            const config_mandate = {
                customer: {
                    reference: '1234xxx',
                    name: 'John Doe',
                    email: '[email protected]',
                }
            };
            const request_mandate = components.create("requestMandate", config_mandate);
            request_mandate.mount("#request_mandate");
            const payPortal = components.create("payPortal");
            payPortal.mount("#pay_portal");
            const config_notif = {
                icon: {
                    url: 'https://cdn.unipaas.com/img/bell-icon.svg',
                    size: 30
                }
            };
            const notification = components.create("notification", config_notif);
            notification.mount("#notification");
        }
    }
    initializeUniPAAS();
</script>
</body>
</html>

Updated 7 months ago