Direct Debit UK

Integration

This product doesn't support the MyCheckout hosted payment pages integration. You can build your Direct Debit UK integration using our APIs or available SDKs in different programming languages.

Before you begin

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

Correct API endpoint
Way to construct the authorization header (API Explorer, SDKs, etc.)
Way to send REST API calls (API Explorer, SDKs, etc.)
Your own checkout page UI

One-off payments

Create payment

To create a payment, make the POST https://{domainname}/v1/{merchantId}/payments API call submitting the required properties.

Property	Data type	Required
order	object	yes
amountOfMoney	object	yes
amount	integer	yes
currencyCode	string	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 the payment, send the POST https://{domainname}/v1/{merchantId}/payments/{paymentId}/approve API call, submitting the required properties. This is only required for first payments, and only when payment status is (800) READY. 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
}

Recurring payments

The payment product used is determined by the isRecurring property and recurringPaymentSequenceIndicator in your createPayment POST https://{domainname}/v1/{merchantId}/payments API call.

Type	Sequence indicator
First collection (new mandate)	"first"
Subsequent recurring	"recurring"

Create a token

You can also create a token using POST https://{domainname}/v1/{merchantId}/tokens API call to be used in your subsequent API requests.

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

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 (Direct Debit Instruction) to BACS (Bankers' Automated Clearing Services) 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.

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, use the POST https://{domainname}/v1/{merchantId}/payments/{paymentId}/refund API call. 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.pending_payment
payment.captured
payment.paid