This site requires javascript to be enabled.

Direct Debit UK Skip to main content
Worldline Connect Home Page
Global Collect (Connect)
Other Worldline developer portals

Results for

Results for Searching
  1. Home
  2. Payment methods
  3. Direct Debit UK

Direct Debit UK

Only available on GlobalCollect platform

Integration

Bankers' Automated Clearing Services

Before you begin

To follow along with this guide, please ensure that you have the following ready:

One-off payments

Create a token

Before making a Direct Debit UK payment you need to obtain a token using POST https://{domainname}/v1/{merchantId}/tokens API call.

Below, you'll find an example API call with the essential data. To add more information with additional properties, please visit to our API Reference.

Property Data type Required
paymentProductId integer yes
nonSepaDirectDebit object yes
customer object yes
billingAddress object yes
city string yes
street string yes
zip string yes
mandate object yes
paymentProduct705SpecificData object yes
authorisationId string yes
bankAccountBban object yes
accountNumber string yes
bankCode string yes
countryCode string yes

Below, you'll find an example request containing the essential data. For more information, please refer to our API Reference.

CREATE TOKEN REQUEST
{
  "paymentProductId": 705,
  "nonSepaDirectDebit": {
    "mandate": {
      "paymentProduct705SpecificData": {
      	"authorisationId": "",
        "bankAccountBban": {
          	"accountNumber": "<8-digit UK account number>",
          	"bankCode":    "<6-digit sort code, numeric only, no dashes e.g. 190909>",
          	"branchCode":   "",
          	"checkDigit":   "",
          	"countryCode":  "GB"
        }
      }
    },
    "customer": {
      "merchantCustomerId": "",
      "personalInformation": {
        "name": {
          "firstName": "",
          "surname":   ""
        }
      },
      "billingAddress": {
        "street":     	"",
    	"houseNumber": "<house/flat number>",
		"city": "",
		"zip":  "",
		"countryCode": "GB"
    }
  }
}

The result of processing this request is shown below. You need to save this token because further communication is not possible without specifying this token.

CREATE TOKEN RESPONSE
{
    "isNewToken": true,
    "token": "a326af5e-db47-43b8-bbb4-8b8fa04b5391"
}

Get Token

After creating a token, we recommend retrieving and inspecting the token before confirmation using GET https://{domainname}/v1/{merchantId}/tokens/{tokenId} API call.

Confirm token

After creating a token, you need to approve it using POST https://{domainname}/v1/{merchantId}/tokens/{tokenId}/approvesepadirectdebit API call.

This API call confirms the mandate has been signed by the consumer and submits the DDI to BACS via AUDDIS (Automated Direct Debit Instruction Service). This starts the 3–5 business day mandate registration and validation period.

Property Data type Required
mandateSignatureDate string yes
mandateSignaturePlace string yes
mandateSigned boolean yes
APPROVE DIRECT DEBIT UK MANDATE REQUEST
{
    "mandateSignaturePlace": "Monument Valley",
    "mandateSignatureDate": "20200107",
    "mandateSigned": true
}

A successful response for this request will be an HTTP status of 204. If the token has already been validated, the response will look like this:

APPROVE DIRECT DEBIT UK MANDATE ALREADY SIGNED
{
    "errorId": "6617caba5da562890912d54db99fc09d",
    "errors": [
        {
            "code": "700647",
            "requestId": "463",
            "message": "MANDATE ALREADY SIGNED",
            "httpStatusCode": 400
        }
    ]
}

Any payment created now will be at status 600 PENDING. Do not initiate an Approve/Capture request until the Mandate Response file delivers an Mandate Assumed Approved record for this mandate. Approving before the Mandate Assumed Approved confirmation will result in a Bankers' Automated Clearing Services (BACS) rejection.

Create payment

To create a payment, use POST https://{domainname}/v1/{merchantId}/payments API call.

Property Data type Required
order object yes
amountOfMoney object yes
amount integer yes
currencyCode string yes
customer object yes
billingAddress string yes
city string yes
street string yes
zip string yes
countryCode string yes
DirectDebitPaymentMethodSpecificInput object yes
directDebitText string yes
isRecurring boolean yes
paymentProduct705SpecificInput object yes
authorisationId string yes
BankAccountBban object yes
accountNumber string yes
bankCode string yes
countryCode string yes
transactionType string yes
paymentProductId string no
recurringPaymentSequenceIndicator string depends
requiresApproval string yes
token string yes
CREATE PAYMENT REQUEST
{
"directDebitPaymentMethodSpecificInput": {
	"paymentProductId": 705,                
	"isRecurring":true,
    "recurringPaymentSequenceIndicator":  "first",
    "requiresApproval": true,
    "token": "",
    "directDebitText": ""
  },
"order": {
	"amountOfMoney": {
      "currencyCode": "GBP",
      "amount": 
    },
    "customer": {
      "personalInformation": {
        "name": { 
			"firstName": "", 
			"surname": "" 
		}
      },
      "billingAddress": {
        "street": "", 
		"houseNumber": "",
        "city": "", 
		"zip": "", 
		"countryCode": "GB"
      }
    },
    "references": {
      "merchantReference": ""
    }
  }
}
CREATE PAYMENT RESPONSE
{
  "creationOutput": {
    "additionalReference": "00000099911000003410",
    "externalReference": "000000999110000034100000100001"
  },
  "merchantAction": {
    "actionType": "SHOW_TRANSACTION_RESULTS",
    "showData": [
      {
        "key": "PAYMENTREFERENCE",
        "value": "0"
      },
      {
        "key": "REFERENCENUMBER",
        "value": "1000003410"
      }
    ]
  },
  "payment": {
    "id": "000000999110000034100000100001",
    "paymentOutput": {
      "amountOfMoney": {
        "amount": 1009,
        "currencyCode": "GBP"
      },
      "references": {
        "paymentReference": "0"
      },
      "paymentMethod": "directDebit",
      "directDebitPaymentMethodSpecificOutput": {
        "paymentProductId": 705
      }
    },
    "status": "PENDING_APPROVAL",
    "statusOutput": {
      "isCancellable": true,
      "isRetriable": false,
      "statusCategory": "PENDING_MERCHANT",
      "statusCode": 600,
      "statusCodeChangeDateTime": "20260902070805",
      "isAuthorized": false,
      "isRefundable": false
    }
  }
}

Approve payment

To approve/capture the payment, use POST https://{domainname}/v1/{merchantId}/payments/{paymentId}/approve API call. This is only required for first payments, and only when payment status is (800) READY (MA record received in MR1 file). An empty body is sufficient.

Property Data type Required
directDebitPaymentMethodSpecificInput object no
token string no
dataCollect string no
APPROVE PAYMENT REQUEST
{
    "directDebitPaymentMethodSpecificInput" : {
        "token" : "df8e21c5-de6d-4df9-9c67-f9cccdb2c6ca",
        "dateCollect" : "20240508"
    },
    "order" : {
        "references" : {
            "merchantReference" : "Subscription01"
        }
    },
    "amount" : 1599
}
APPROVE PAYMENT RESPONSE
{
WIP
}

Recurring payments

Create token for recurring payments

The process for creating recurring payments is only slightly different from regular one-off payments. You need to create a token with POST https://{domainname}/v1/{merchantId}/tokens API call, specifying additional properties:

Property Data type Required
paymentProductId integer yes
sepaDirectDebit object yes
customer object yes
billingAddress object yes
countryCode string yes
mandate object yes
bankAccountIban object yes
accountHolderName string yes
iban string yes
debtor object yes
surname string yes
isRecurring boolean no

Confirm recurring payment token

After creating a token, you need to confirm it using POST https://{domainname}/v1/{merchantId}/tokens/{tokenId}/approvesepadirectdebit API call.

Property Data type Required
mandateSignatureDate string no
mandateSignaturePlace string no
mandateSigned boolean no

Submit recurring payment request

When submitting a payment request, you can omit some request details, such as the payment product ID.

  • recurringPaymentSequenceIndicator - this property is required for the recurring payment. It comes with one of three values:
    • first = transaction is the first of a series of recurring transactions
    • recurring = transaction is a subsequent in a series of recurring transactions
    • last = transaction is the last one in a series of recurring transactions

Approve payment

To approve/capture the payment, use POST https://{domainname}/v1/{merchantId}/payments/{paymentId}/approve API call.

Property Data type Required
token string no
dataCollect string no
APPROVE PAYMENT REQUEST
{
    "directDebitPaymentMethodSpecificInput" : {
        "token" : "df8e21c5-de6d-4df9-9c67-f9cccdb2c6ca",
        "dateCollect" : "20240508"
    },
    "order" : {
        "references" : {
            "merchantReference" : "Subscription01"
        }
    },
    "amount" : 1000
}
APPROVE PAYMENT RESPONSE
{
   "payment" : {
      "id" : "000008800510000139970000100001",
      "paymentOutput" : {
         "amountOfMoney" : {
            "amount" : 1000,
            "currencyCode" : "EUR"
         },
         "references" : {
            "paymentReference" : "0"
         },
         "paymentMethod" : "directDebit",
         "sepaDirectDebitPaymentMethodSpecificOutput" : {
            "paymentProductId" : 770
         }
      },
      "status" : "CAPTURE_REQUESTED",
      "statusOutput" : {
         "isCancellable" : true,
         "isRetriable" : false,
         "statusCategory" : "PENDING_CONNECT_OR_3RD_PARTY",
         "statusCode" : 800,
         "statusCodeChangeDateTime" : "20240508152943",
         "isAuthorized" : false,
         "isRefundable" : false
      }
   }
}

Refunds

Refunds are processed as Bank Transfers (Payment Product ID: 1015) and can be initiated via the Connect API on the original payment, or via the Refund button in the Worldline Payment Console. The maximum refund
value is 100% of the original settlement amount. Refunds must be submitted within 180 calendar days of the original collection. Partial refunds are supported

To start a refund process, you should use the API call POST https://{domainname}/v1/{merchantId}/payments/{paymentId}/refund. This action is only applicable if the payment status is PAID.

If you wish to refund the full order amount, you can do so by sending a request using the same API call with an empty body.

Property Data type Required
amountOfMoney object no
currencyCode string yes
amount integer no
bankRefundMethodSpecificInput object no
bankAccountBban object no
accountNumber string no
bankCode string no
contryCode string no
POST REFUND REQUEST
{
    "amountOfMoney": {
        "amount": 1000,
        "currencyCode": "EUR"
    }
}

You have the option to refund a part of the funds as well. For this, it's necessary to include a payload with the amountOfMoney object, where you specify the amount and the currencyCode. Additionally, if you want to view the details of your refund, you can use the GET https://{domainname}/v1/{merchantId}/payments/{paymentId}/refunds API call.

Webhooks

To track transaction status updates, you can subscribe to the following webhooks notifications:

  • payment.created
  • payment.redirected
  • payment.pending_payment
  • payment.captured
  • payment.paid
Next Process flows