The Trustly Direct Debit solution lets you process recurring payments and subscriptions directly from a customer's bank account within the United Kingdom (UK). This robust, convenient method for subscription billing and regular customer debits often results in significantly reduced payment processing costs compared to card networks.

Required fields and format

To set up a Direct Debit Instruction (DDI), you must pass specific information in the establishData object when calling the API.

Mandatory customer and geolocation data

The following customer data must be provided within the establishData object:

• The customer's email and address.

In compliance with the General Data Protection Regulation (GDPR) regulations, don't send the customer's telephone number.

While the API won't verify this data, if it is omitted, the user is prompted to manually enter it at checkout.

Merchant reference requirements

The MerchantReference field is mandatory and must be unique for each mandate. It must adhere to the following Bankers' Automated Clearing Service (BACS) rules:

• The core reference must be 6 to 13 characters long.

• Only uppercase alpha and numeric characters count toward the minimum 6-character length.

• The Data Dictionary (DDIC) must not be used in the first four characters. This is reserved for Payment Service Provider (PSP) use.

• It must not consist of all the same characters. For example, all zeros.

• It must be left-justified within Field 10 of the DDI and Direct Debit record. the first character must be in position one.

• The reference must exactly match the reference quoted on a signed DDI.

• It must be unique for the Service User Number (SUN) to ensure the paying PSP can accurately match the Direct Debit to the correct mandate.

• You must include the payment schedule in the metadata object within the establishData object of the EstablishRequest. For example:

  JSON

  {
      "metadata": {
          "paymentSchedule": {
            "1": { "amount": 23, "date": "27th March"},
            "2": { "amount": 23, "date": "27th April"}
          }
      }
  }

Fixed recurring payments

The following are the requirements for fixed, predictable subscription payments:

• The initial payment date must be at least five days after the mandate is established. Mandates need up to five days for bank confirmation, and transactions attempted before this period fail.
• The AutomaticCapture parameter must be set to true.

You can cancel a recurring transaction on the current day, but only before the cut-off time of 8:30 PM Greenwich Mean Time (GMT).

Variable payments

The following are the requirements for processing payments with variable amounts:

• The first capture transaction cannot occur earlier than five days after the mandate is established, as the mandate needs time for bank confirmation. Attempts before this period may fail.
• You must send an email notification to the user before calling the capture transaction API. This email must clearly state the date and amount of the upcoming transaction.
• You must send an email confirmation to the user as soon as a mandate is successfully created.

Representment

If a Direct Debit transaction fails, usually due to insufficient funds, you can attempt a representment (or retry). The following are the requirements for representment:

• You must enable representment in your configuration.
• You must define the number of days between the failed transaction and each representment attempt.
• You must inform the user using an advanced notice email before each representment attempt.
• A failed transaction can be represented a maximum of two times.
• The representment period is limited to 30 days from the date of the initial failed transaction.
• Direct Debit transactions cannot be refunded.

Import existing mandates

To import existing mandates, complete the following tasks:

• Create CSV files in the required format. Use the recommended naming convention.
• Send the file to your designated SFTP folder.

You'll receive a notification for each transaction processed during the import.

Additional API resources

Use these API calls to manage your Direct Debits and customer data:

Expected responses

The following table lists the response types and reason codes used to indicate the status or reason for a transaction or mandate failure.

You must enable Event Notifications to retrieve status updates on mandates and transactions.See Event notifications.