Sign in

v2

latestOpenAPI 3.1.02026-07-262279731.3 MB
Mandates

Create a Mandate

<Note icon="fa-regular fa-circle-info"> **Note – Mandate expires after 1 hour**

If not confirmed within 1 hour of the CreationDate, the Mandate expires with the error <a href="/errors/codes/001807">001807</a> and a new one must be created. </Note>

Create a Mandate

For SDD, if the BankAccountId is a Danish or Swedish IBAN (starting DK or SE), this endpoint returns a 400 error because they are not currently supported (see IBAN compatibility).

post/v2.01/{ClientId}/mandates/directdebit/web

Path parameters

ClientIdstring required

Platform's API account identifier, associated with the API key.

Headers

Authorizationstring required

Bearer authentication of the form Bearer <token>, where token is your auth token.

If your platform is using a proxy to take SCA-triggering action on behalf of users, you also need to integrate mTLS authentication and use the api-mtls base URL.

Request body

BankAccountIdstring required

The unique identifier of the bank account.

Warning: The <a href="/api-reference/bank-accounts/bank-account-object">Bank Account</a> Type must be IBAN for the SEPA scheme and GB for the Bacs scheme.

Culturestring required

Allowed values: One of the supported languages in the ISO 639-1 format: DE, EN, ES, FR, IT, NL, PL

The language in which the mandate confirmation page is to be displayed. This value only applies to mandates with the SEPA Scheme.

ReturnURLstring required

Max. length: 220 characters

The URL to which the user is returned after the payment, whether the transaction is successful or not.

Tagstring

Max. length: 255 characters

Custom data that you can add to this object.

Response

Success

Schemestring

The scheme of the mandate, which is available once the mandate is submitted. The value can be one of the following:

  • BACS – Covers payments in the UK, in GBP only.
  • SEPA – Covers payments in the EU.
BankAccountIdstring

The unique identifier of the bank account.

Warning: The <a href="/api-reference/bank-accounts/bank-account-object">Bank Account</a> Type must be IBAN for the SEPA scheme and GB for the Bacs scheme.

BankReferencestring

The banking reference for the Mandate.

Culturestring

Returned values: One of the supported languages in the ISO 639-1 format: DE, EN, ES, FR, IT, NL, PL

The language in which the mandate confirmation page is to be displayed. This value only applies to mandates with the SEPA Scheme.

DocumentURLstring

The URL at which the mandate document can be downloaded.

ReturnURLstring

Max. length: 220 characters

The URL to which the user is returned after the payment, whether the transaction is successful or not.

RedirectURLstring

The URL to which to redirect the user to complete the payment.

Caution: This variable URL is specific to each payment. You must rely on the returned URL in full (host, path, and queries) and not hardcode any part of it.

Idstring

Max length: 128 characters (see data formats for details)

The unique identifier of the object.

CreationDateinteger

Unix timestamp (UTC) of the date and time the object was created.

Statusstring

Returned values: CREATED, SUBMITTED, ACTIVE, FAILED, EXPIRED

The status of the mandate:

  • CREATED – The mandate has been generated but not yet confirmed.
  • SUBMITTED – The mandate has been confirmed and sent to the user's bank, and can be used to request a direct debit pay-in.
  • ACTIVE – The mandate has been accepted by the user's bank or successfully used to process a direct debit direct pay-in. Further pay-ins can be requested.
  • FAILED – The mandate has been canceled or otherwise failed, and can no longer be used for payments.
  • EXPIRED – No payment has been made against the mandate in the last 24 months. It can no longer be used for payments.
UserIdstring

The unique identifier of the User (natural or legal) who owns the bank account.

ExecutionTypestring

Returned values: WEB

The execution type of the mandate.

MandateTypestring

The type of the mandate.

Tagstring

Max. length: 255 characters

Custom data that you can add to this object.

ResultCodestring

The code indicating the result of the operation. This information is mostly used to <a href="/errors/codes">handle errors</a> or for filtering purposes.

ResultMessagestring

The explanation of the result code.