Process recurring UK payments

The Trustly Recurring Payments solution (formerly UK Direct Debit) allows you to process recurring payments and subscriptions directly from a customer's bank account within the United Kingdom (UK). This robust, convenient method for subscription billing 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 request object when calling the API.

Mandatory customer and geolocation data

The customer's email and physical address must be provided.

Merchant reference requirements

The MerchantReference field is mandatory and must be unique for each mandate. It must adhere to the following BACS (Bankers' Automated Clearing Service) 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) codes must not be used in the first four characters (reserved for PSP use).
• It must not consist of all the same characters (e.g., "000000").
• It must be left-justified within Field 10 of the DDI record.
• It must be unique for the Service User Number (SUN).
• You must include the payment schedule in the metadata.

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

• Lead Time: The initial payment date must be at least five days after the mandate is established. Mandates need up to five days for bank confirmation (BACS cycle).
• Auto-Capture: The AutomaticCapture parameter must be set to true.
• Cut-off Time: You can cancel a recurring transaction on the current day, but only before 8:30 PM GMT.

BACS cycle workflow

The following diagram illustrates the five-day BACS cycle workflow.

sequenceDiagram
    autonumber off
    participant U as User
    participant M as Merchant
    participant T as Trustly API
    participant B as UK Bank (BACS)

    U->>M: A
    M->>T: B
    T->>B: C
    
    Note over M, B: D
    
    M->>T: E
    T-->>M: F
    
    Note over M, B: G

    M->>T: H
    T->>B: I
    B-->>M: J

Variable payments

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

• Lead Time: The first capture cannot occur earlier than five days after the mandate is established.
• Notification: You must send an email notification to the user before calling the capture API. This email must clearly state the date and amount of the upcoming transaction.
• Confirmation: You must send an email confirmation to the user as soon as a mandate is successfully created.

Representment

If a transaction fails (usually due to insufficient funds), you can attempt a representment.

• You must enable representment in your configuration.
• You must define the retry interval (days between attempts).
• You must send an advanced notice email to the user before each retry.
• Limit: A failed transaction can be retried a maximum of two times.
• Window: The representment period is limited to 30 days from the initial failure.

Representment workflow

The following diagram illustrates the workflow for failed payment representment.

flowchart LR
    Start((A)) --> Fail[B]
    Fail --> Check{C}
    
    Check -- Yes --> Wait[D]
    Check -- No --> Stop((H))
    
    Wait --> Email[E]
    Email --> Retry[F]
    
    Retry --> Result{G}
    Result -- Success --> Done((I))
    Result -- Fail --> Fail
    
    style Start fill:#f9f,stroke:#333,stroke-width:2px
    style Stop fill:#ff9999,stroke:#333,stroke-width:2px
    style Done fill:#99ff99,stroke:#333,stroke-width:2px

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.

API resources

Use these API calls to manage your Recurring Payments mandates.

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.