Appearance

Get a mandate​

mandates
GET
/api/v1/mandates/{mandateReference}

Retrieve details of a single mandate by its reference.

Authorizations​

bearerAuth
Type
HTTP (bearer)

Parameters​

Header Parameters

x-region*

Regional routing header. Must be EU for SEPA mandates.

Type
string
Required
Valid values
"EU"

Path Parameters

mandateReference*

The client-provided mandate reference identifier.

Type
string
Required
Example"MAND-SEPA-2024-001"
Min Length
5
Max Length
50
Pattern
"^[A-Z0-9\\-]+$"

Responses​

Mandate details.

application/json
object

Lifecycle status of the mandate.

  • APPROVED — Mandate registered and pending activation.
  • ACTIVE — Mandate is live and can be used for direct debit collections.
  • CANCELLED — Mandate deactivated via DELETE. Cannot be used for collections.
  • EXPIRED — Mandate passed its endDate and is no longer valid.
Valid values"APPROVED""ACTIVE""CANCELLED""EXPIRED"

Payment scheme identifier. Currently supported: SEPA — Single Euro Payments Area (EU).

Valid values"SEPA"

Client-provided unique mandate reference. Uppercase, lowercase, alphanumeric and hyphens only.

Min Length5
Max Length50
Pattern"^[a-zA-Z0-9\\-]+$"
object

Legal name of the creditor (merchant or service provider).

Min Length2
Max Length100
Pattern"^[A-Za-z0-9][A-Za-z0-9 .&'()_-]*$"
object
object
object

Legal name of the debtor (payer).

Min Length2
Max Length100
Pattern"^[a-zA-Z\\s\\-]+$"
object
Required
object

Debtor email address.

Format"email"
Min Length5
Max Length100
Pattern"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"

Debtor phone number in E.164 format.

Min Length10
Max Length20
Pattern"^\\+?[1-9]\\d{1,14}$"
object
object

Mandate collection parameters. Valid field combinations for SEPA:

type debitType Use
ONE_OFF EXACT_AMOUNT Single collection only. Provide amount.
RECURRING EXACT_AMOUNT or MAXIMUM_AMOUNT Ongoing regular collections. Provide amount (EXACT_AMOUNT) or maxAmount (MAXIMUM_AMOUNT).

mode rules: CORE only — SEPA Core Direct Debit (consumers; 5-day first-collection notice).

frequency is optional.
Do not pair type=ONE_OFF with debitType=MAXIMUM_AMOUNT — these are contradictory.

SEPA direct debit mode:

  • CORE — SEPA Core Direct Debit (consumers; 5-day first-collection notice)

Optional. When omitted, defaults to CORE.

Valid values"CORE"
Default"CORE"

Type of mandate collection: RECURRING (ongoing regular collections), ONE_OFF (single collection).

Valid values"RECURRING""ONE_OFF"

Specifies whether the mandate collects the exact specified amount or up to a maximum amount.

Valid values"EXACT_AMOUNT""MAXIMUM_AMOUNT"

Fixed collection amount per occurrence. Required when debitType is EXACT_AMOUNT.

Pattern"^[1-9]\\d{0,8}(\\.\\d{1,2})?$"

Maximum collection amount per occurrence. Required when debitType is MAXIMUM_AMOUNT. Actual collected amount may vary up to this ceiling.

Pattern"^[1-9]\\d{0,8}(\\.\\d{1,2})?$"

ISO 4217 currency code. Must be EUR for SEPA mandates.

Valid values"EUR"

Collection frequency pattern.

Valid values"MONTHLY""QUARTERLY""HALF_YEARLY""YEARLY""AS_AND_WHEN_PRESENTED"

Date the mandate becomes active. ISO 8601 format (YYYY-MM-DD).

Format"date"
Pattern"^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$"

Date the mandate expires. ISO 8601 format (YYYY-MM-DD). Omit or set untilCancelled: true for open-ended mandates.

Format"date"
Pattern"^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$"

If true, the mandate remains active until explicitly cancelled. Mutually exclusive with endDate.

object

Authorization consent record. Required for SEPA mandates — this is the legal proof of debtor consent for direct debit collections. A mandate without authorization cannot be used for collections.

Merchant category code for the mandate collection.

Min Length4
Max Length10

Day of month for collection when frequency is MONTHLY. Values 1–28 recommended to avoid month-end issues.

Minimum1
Maximum31

Human-readable collection purpose shown to the debtor.

Min Length1
Max Length250

The date and time the mandate was created in ISO 8601 format. Example: 2024-03-24T03:14:15Z.

Format"date-time"
Pattern"^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])T([01]\\d|2[0-3]):[0-5]\\d:[0-5]\\dZ$"

The date and time the mandate was last updated in ISO 8601 format. Example: 2024-03-24T03:14:15Z.

Format"date-time"
Pattern"^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])T([01]\\d|2[0-3]):[0-5]\\d:[0-5]\\dZ$"

The date and time the mandate expired in ISO 8601 format. Example: 2024-03-24T03:14:15Z.

Format"date-time"
Pattern"^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])T([01]\\d|2[0-3]):[0-5]\\d:[0-5]\\dZ$"

Response Headers

Deprecation

Indicates deprecation (boolean)

Typestring
Exampletrue
Sunset

Sunset date in HTTP-date format [ISO 8601]. Example: `2024-03-24T03:14:15Z`.

Typestring (date-time)
Example2024-03-24T03:14:15Z

Samples​