SEPA mandate management

Last changes: 10-30-2023

A SEPA mandate is a legally binding contract permitting a company to withdraw funds from a customer's bank account. With Mandate Management service, it is possible to create, modify, retrieve, and manage mandates efficiently, including empty, partially filled and fully filled mandates.

Create SEPA mandate

The following section will describe the procedure and results of creating a new empty mandate. The endpoint supports creating mandates in two ways: generating an empty mandate with a unique reference or allowing the client to manage the mandate reference. The mandate reference must be unique for each client making the request.

Every create request requires creditor information to be contained.

Create new empty mandate request

Path:: POST {baseURL}/mandates
Header:: Content-Type: application/json
Accept-Language: en-US

{
  "mandateScheme": "SEPA_B2B",
  "referenceInstructions": {
    "generatedReference": true
  },
  "creditorName": "ABC Corporation",
  "creditorIdentifier": "DE123456789",
  "creditorAddress": {
    "city": "Munich",
    "country": "DE",
    "number": "456",
    "addressLine1": "Leopoldstr.",
    "postCode": "80807"
  }
}

Create new empty mandate response

Status Code:: 201 (OK)
Header:: Content-Type: application/json
Accept-Language: en-US

{
  "id": "md_ba22fd34-894c-4232-993a-c56a3e960e47",
  "object": "MANDATE",
  "createdAt": "2023-03-02T14:25:59.078Z",
  "mandateScheme": "SEPA_B2B",
  "mandateReference": "SEPA-20230906-ABC123",
  "status": "CREATED",
  "referenceInstructions": {
    "generatedReference": true
  },
  "creditorName": "ABC Corporation",
  "creditorIdentifier": "DE123456789",
  "creditorAddress": {
    "city": "Munich",
    "country": "DE",
    "number": "456",
    "addressLine1": "Leopoldstr.",
    "postCode": "80807"
  }
}

This section describes how to create a new mandate filled with debtor data only.

Create a new partially filled mandate request

Path:: POST {baseURL}/mandates
Header:: Content-Type: application/json
Accept-Language: en-US

{
  "mandateScheme": "SEPA_B2B",
  "mandateReference": "SEPA-20230906-ABC123",
  "referenceInstructions": {
    "generatedReference": false
  },
  "debtorName": "John Doe",
  "debtorAddress": {
    "city": "Berlin",
    "country": "DE",
    "number": "123",
    "addressLine1": "Main Street",
    "postCode": "12345"
  },
  "creditorName": "ABC Corporation",
  "creditorIdentifier": "DE123456789",
  "creditorAddress": {
    "city": "Munich",
    "country": "DE",
    "number": "456",
    "addressLine1": "Leopoldstr.",
    "postCode": "80807"
  }
}

Create new partially filled mandate response

Status Code:: 201 (OK)
Header:: Content-Type: application/json
Accept-Language: en-US

{
  "id": "md_ba22fd34-894c-4232-993a-c56a3e960e47",
  "object": "MANDATE",
  "createdAt": "2023-03-02T14:25:59.078Z",
  "mandateScheme": "SEPA_B2B",
  "mandateReference": "SEPA-20230906-ABC123",
  "referenceInstructions": {
    "generatedReference": false
  },
  "debtorName": "John Doe",
  "debtorAddress": {
    "city": "Berlin",
    "country": "DE",
    "number": "123",
    "addressLine1": "Main Street",
    "postCode": "12345"
  },
  "creditorName": "ABC Corporation",
  "creditorIdentifier": "DE123456789",
  "creditorAddress": {
    "city": "Munich",
    "country": "DE",
    "number": "456",
    "addressLine1": "Leopoldstr.",
    "postCode": "80807"
  }
}

This section describes how to create a new fully filled mandate. This mandate has to have a client issued mandateReference that needs to be unique for each client making the request.

Create new fully filled mandate request

Path:: POST {baseURL}/mandates
Header:: Content-Type: application/json
Accept-Language: en-US

{
  "mandateScheme": "SEPA_B2B",
  "referenceInstructions": {
    "generatedReference": true,
    "mandatePrefix": "SEPA-20230906"
  },
  "debtorName": "John Doe",
  "debtorAddress": {
    "city": "Berlin",
    "country": "DE",
    "number": "123",
    "addressLine1": "Main Street",
    "postCode": "12345"
  },
  "debtorBank": {
    "iban": "DE89370400440532013000",
    "bankName": "Example Bank",
    "bic": "EXBKDE81XXX"
  },
  "creditorName": "ABC Corporation",
  "creditorIdentifier": "DE123456789",
  "creditorAddress": {
    "city": "Munich",
    "country": "DE",
    "number": "456",
    "addressLine1": "Leopoldstr.",
    "postCode": "80807"
  },
  "account": {
    "customerAccountId": "CUST-12345",
    "billingAddress": {
      "city": "Berlin",
      "country": "DE",
      "number": "123",
      "addressLine1": "Main Street",
      "postCode": "12345"
    },
    "isBusinessUser": true,
    "businessConsumer": {
      "companyName": "ABC Corporation",
      "companyType": "Limited Liability Company",
      "emailAddress": "contact@abccorp.com",
      "taxId": "DE987654321",
      "culture": "en_US"
    }
  }
}

Create new fully filled mandate response

Status Code:: 201 (OK)
Header:: Content-Type: application/json
Accept-Language: en-US

{
  "id": "md_7c1c304e-72bf-2b57-2570-148879f6da20",
  "object": "MANDATE",
  "createdAt": "2023-03-02T14:25:59.078Z",
  "mandateScheme": "SEPA_B2B",
  "mandateReference": "SEPA-20230906-ABC123",
  "status": "CREATED",
  "referenceInstructions": {
    "generatedReference": true,
    "mandatePrefix": "SEPA-20230906"
  },
  "debtorName": "John Doe",
  "debtorAddress": {
    "city": "Berlin",
    "country": "DE",
    "number": "123",
    "addressLine1": "Main Street",
    "postCode": "12345"
  },
  "debtorBank": {
    "iban": "DE89370400440532013000",
    "bankName": "Example Bank",
    "bic": "EXBKDE81XXX"
  },
  "creditorName": "ABC Corporation",
  "creditorIdentifier": "DE123456789",
  "creditorAddress": {
    "city": "Munich",
    "country": "DE",
    "number": "456",
    "addressLine1": "Leopoldstr.",
    "postCode": "80807"
  },
  "account": {
    "id": "bz_f654a38c-9a51-fe39-a58e-16a5732e2f0e",
    "object": "customer_account",
    "createdAt": "2023-03-02T14:25:59.078Z",
    "customerAccountId": "CUST-12345",
    "billingAddress": {
      "city": "Berlin",
      "country": "DE",
      "number": "123",
      "addressLine1": "Main Street",
      "postCode": "12345"
    },
    "isBusinessUser": true,
    "businessConsumer": {
      "companyName": "ABC Corporation",
      "companyType": "Limited Liability Company",
      "emailAddress": "contact@abccorp.com",
      "taxId": "DE987654321",
      "culture": "en_US"
    }
  }
}

Get all SEPA mandates

The endpoint provides all mandates for the integrator making the request (identified by basicAuth).

Get all mandates parameters

Parameter	Explanation
status	CREATED - filters only mandates with the status created.
ACTIVE - filters only mandates with the status active.
CLOSED - filters only mandates with the status closed.	fromDate	Returns all mandates created on or after that date.
toDate	Returns all mandates created on or before that date.
cursor	First mandate after MandateId provided will be returned.
pageSize	Used for pagination, total number of results to return.

Get all mandates request URL

Path:: GET {baseURL}/mandates
Header:: Content-Type: application/json
Accept-Language: en-US

https://{baseURL}/mandates?status=CREATED&fromDate=2023-03-02&toDate=2023-03-02&cursor=md_7c1c304e-72bf-2b57-2570-148879f6da20&pageSize=25

Get all mandates response

Status Code:: 200 (OK)
Header:: Content-Type: application/json
Accept-Language: en-US

{
  "meta": {
    "hasMore": false
  },
  "data": [
    {
      "id": "md_54c8e62b-f96a-4698-8323-783284873a68",
      "object": "MANDATE",
      "createdAt": "2023-03-02T14:25:59.078Z",
      "mandateScheme": "SEPA_B2B",
      "mandateReference": "SEPA-20230906-ABC123",
      "status": "CREATED",
      "referenceInstructions": {
        "generatedReference": true
      },
      "creditorName": "ABC Corporation",
      "creditorIdentifier": "DE123456789",
      "creditorAddress": {
        "city": "Munich",
        "country": "DE",
        "number": "456",
        "addressLine1": "Leopoldstr.",
        "postCode": "80807"
      }
    },
    {
      "id": "md_7c1c304e-72bf-2b57-2570-148879f6da20",
      "object": "MANDATE",
      "createdAt": "2023-03-02T14:25:59.078Z",
      "mandateScheme": "SEPA_B2B",
      "mandateReference": "SEPA-20230906-ABC123",
      "status": "CREATED",
      "referenceInstructions": {
        "generatedReference": true,
        "mandatePrefix": "SEPA-20230906"
      },
      "debtorName": "John Doe",
      "debtorAddress": {
        "city": "Berlin",
        "country": "DE",
        "number": "123",
        "addressLine1": "Main Street",
        "postCode": "12345"
      },
      "debtorBank": {
        "iban": "DE89370400440532013000",
        "bankName": "Example Bank",
        "bic": "EXBKDE81XXX"
      },
      "creditorName": "ABC Corporation",
      "creditorIdentifier": "DE123456789",
      "creditorAddress": {
        "city": "Munich",
        "country": "DE",
        "number": "456",
        "addressLine1": "Leopoldstr.",
        "postCode": "80807"
      },
      "account": {
        "id": "bz_f654a38c-9a51-fe39-a58e-16a5732e2f0e",
        "object": "customer_account",
        "createdAt": "2023-03-02T14:25:59.078Z",
        "customerAccountId": "CUST-12345",
        "billingAddress": {
          "city": "Berlin",
          "country": "DE",
          "number": "123",
          "addressLine1": "Main Street",
          "postCode": "12345"
        },
        "isBusinessUser": true,
        "businessConsumer": {
          "companyName": "ABC Corporation",
          "companyType": "Limited Liability Company",
          "emailAddress": "contact@abccorp.com",
          "taxId": "DE987654321",
          "culture": "en_US"
        }
      }
    },
    {
      "id": "md_456949e4-0406-44ed-8f1d-ebced96b02cf",
      "object": "MANDATE",
      "createdAt": "2023-03-02T14:25:59.078Z",
      "mandateScheme": "SEPA_B2B",
      "mandateReference": "SEPA-20230906-DEF456",
      "status": "ACTIVE",
      "referenceInstructions": {
        "generatedReference": false,
        "mandatePrefix": "SEPA-20230906"
      },
      "debtorName": "Jane Smith",
      "debtorAddress": {
        "city": "Hamburg",
        "country": "DE",
        "number": "789",
        "addressLine1": "Elm Street",
        "postCode": "54321"
      },
      "debtorBank": {
        "iban": "DE12345678901234567890",
        "bankName": "Another Bank",
        "bic": "ANBKDE81XXX"
      },
      "creditorName": "XYZ Ltd",
      "creditorIdentifier": "DE987654321",
      "creditorAddress": {
        "city": "Frankfurt",
        "country": "DE",
        "number": "101",
        "addressLine1": "Oak Street",
        "postCode": "60000"
      },
      "acceptance": {
        "id": "xd_12345678-9012-3456-7890-123456789012",
        "object": "mandate_acceptance",
        "createdAt": "2023-03-02T14:25:59.078Z",
        "mandateSignedLocation": "Hamburg",
        "mandateDateOfSignature": "2023-09-10",
        "mandateAcceptance": "OFFLINE"
      },
      "account": {
        "id": "bz_abcdef12-3456-7890-abcd-ef1234567890",
        "object": "customer_account",
        "createdAt": "2023-03-02T14:25:59.078Z",
        "customerAccountId": "CUST-67890",
        "billingAddress": {
          "city": "Hamburg",
          "country": "DE",
          "number": "789",
          "addressLine1": "Elm Street",
          "postCode": "54321"
        },
        "isBusinessUser": false,
        "businessConsumer": {
          "companyName": "N/A",
          "companyType": "N/A",
          "emailAddress": "N/A",
          "taxId": "N/A",
          "culture": "en_GB"
        }
      }
    }
  ]
}

Get SEPA mandate by ID

The endpoint returns mandates by ID in the chronological order.

Parameter Explanation mandateId Mandate ID is required.

Get all mandates request URL

Path:: GET {baseURL}/mandates/{mandateId}
Header:: Content-Type: application/json
Accept-Language: en-US

https://{baseURL}/mandates/md_7c1c304e-72bf-2b57-2570-148879f6da20

Get all mandates response

Status Code:: 200 (OK)
Header:: Content-Type: application/json
Accept-Language: en-US

{
  "id": "md_7c1c304e-72bf-2b57-2570-148879f6da20",
  "object": "MANDATE",
  "createdAt": "2023-03-02T14:25:59.078Z",
  "mandateScheme": "SEPA_B2B",
  "mandateReference": "SEPA-20230906-ABC123",
  "status": "CREATED",
  "referenceInstructions": {
    "generatedReference": true,
    "mandatePrefix": "SEPA-20230906"
  },
  "debtorName": "John Doe",
  "debtorAddress": {
    "city": "Berlin",
    "country": "DE",
    "number": "123",
    "addressLine1": "Main Street",
    "postCode": "12345"
  },
  "debtorBank": {
    "iban": "DE89370400440532013000",
    "bankName": "Example Bank",
    "bic": "EXBKDE81XXX"
  },
  "creditorName": "ABC Corporation",
  "creditorIdentifier": "DE123456789",
  "creditorAddress": {
    "city": "Munich",
    "country": "DE",
    "number": "456",
    "addressLine1": "Leopoldstr.",
    "postCode": "80807"
  },
  "account": {
    "id": "bz_f654a38c-9a51-fe39-a58e-16a5732e2f0e",
    "object": "customer_account",
    "createdAt": "2023-03-02T14:25:59.078Z",
    "customerAccountId": "CUST-12345",
    "billingAddress": {
      "city": "Berlin",
      "country": "DE",
      "number": "123",
      "addressLine1": "Main Street",
      "postCode": "12345"
    },
    "isBusinessUser": true,
    "businessConsumer": {
      "companyName": "ABC Corporation",
      "companyType": "Limited Liability Company",
      "emailAddress": "contact@abccorp.com",
      "taxId": "DE987654321",
      "culture": "en_US"
    }
  }
}

Update SEPA mandate

Update or complete a mandate by setting the specified parameter values. Any unprovided parameters will remain unchanged.

Update mandate parameters

Parameter Explanation mandateId Mandate ID is required.

Update mandate request

Path:: PUT {baseURL}/mandates/{mandateId}
Header:: Content-Type: application/json
Accept-Language: en-US

{
  "debtorName": "John Doe",
  "debtorAddress": {
    "city": "Berlin",
    "country": "DE",
    "number": "123",
    "addressLine1": "Main Street",
    "postCode": "12345"
  },
  "debtorBank": {
    "iban": "DE89370400440532013000",
    "bankName": "Example Bank",
    "bic": "EXBKDE81XXX"
  }
}

Update mandate response

Path:: https://{baseURL}/mandates/{mandateId}
Status Code:: 200 (OK)
Header:: Content-Type: application/json
Accept-Language: en-US

{
  "id": "md_7c1c304e-72bf-2b57-2570-148879f6da20",
  "object": "MANDATE",
  "createdAt": "2023-03-02T14:25:59.078Z",
  "mandateScheme": "SEPA_B2B",
  "mandateReference": "SEPA-20230906-ABC123",
  "status": "CREATED",
  "referenceInstructions": {
    "generatedReference": false
  },
  "debtorName": "John Doe",
  "debtorAddress": {
    "city": "Berlin",
    "country": "DE",
    "number": "123",
    "addressLine1": "Main Street",
    "postCode": "12345"
  },
  "debtorBank": {
    "iban": "DE89370400440532013000",
    "bankName": "Example Bank",
    "bic": "EXBKDE81XXX"
  },
  "creditorName": "ABC Corporation",
  "creditorIdentifier": "DE123456789",
  "creditorAddress": {
    "city": "Munich",
    "country": "DE",
    "number": "456",
    "addressLine1": "Leopoldstr.",
    "postCode": "80807"
  }
}

Delete SEPA mandate

This endpoint deletes an inactive mandate.

Delete mandate parameters

Parameter Explanation mandateId Mandate ID is required.

Delete mandate request

Path:: DELETE {baseURL}/mandates/{mandateId}
Header:: Content-Type: application/json
Accept-Language: en-US

https://{baseURL}/mandates/md_7c1c304e-72bf-2b57-2570-148879f6da20

Delete mandate response

Path:: https://{baseURL}/mandates/md_7c1c304e-72bf-2b57-2570-148879f6da20
Status Code:: 204 (Mandate deleted successfully)
Header:: Content-Type: application/json
Accept-Language: en-US

Activate SEPA mandate

This endpoint initiates the activation of a mandate, enabling it for payment processing.

Parameter Explanation mandateId Mandate ID is required.

Activate mandate request

Path:: PUT {baseURL}/mandates/{mandateId}/activate
Header:: Content-Type: application/json
Accept-Language: en-US

{
  "mandateSignedLocation": "Munich",
  "mandateDateOfSignature": "2023-09-28",
  "mandateAcceptance": "OFFLINE"
}

Activate mandate response

Path:: https://{baseURL}/mandates/{mandateID}/activate
Status Code:: 200 (OK)
Header:: Content-Type: application/json
Accept-Language: en-US

{
  "id": "si_89266fef-480f-0af0-ef4b-d8a92aefef13",
  "object": "mandate_acceptance",
  "createdAt": "2023-03-02T14:25:59.078Z",
  "storedPaymentOptionReference": "b2c5aafa-afda-481d-9813-d36bc6fcac15",
  "mandateSignedLocation": "Munich",
  "mandateDateOfSignature": "2023-09-28",
  "mandateAcceptance": "OFFLINE"
}

Cancel active SEPA mandate

This endpoint initiates a request for mandate cancellation, making it unusable for any future payment processing.

Parameter	Explanation
mandateId	Mandate ID is required.

Cancel mandate request

Path:: PUT {baseURL}/mandates/{mandateId}/cancel
Header:: Content-Type: application/json
Accept-Language: en-US

https://{baseURL}/mandates/md_7c1c304e-72bf-2b57-2570-148879f6da20/cancel

Cancel mandate response

Path:: https://{baseURL}/mandates/{mandateId}/cancel
Status Code:: 204 (Mandate cancelled successfully)
Header:: Content-Type: application/json
Accept-Language: en-US

Previous

Next