SEPA (Single Euro Payments Area) is an area consisting of 34 European countries in which payment transactions denominated in Euro are being standardized.

SEPA provides:
  • SEPA direct debit (collect money from customer)
  • SEPA credit transfer (refund money to customer)
  • in 34 countries
  • in EUR currency

In order to accept SEPA Direct Debit payments, merchants have to comply with certain rules set by the European Payments Council.

Sequence Diagrams

Direct Debit with Chargeback and Encashment

SEPA Mandate Management

SEPA Direct Debit allows for so-called merchant-inititiated transactions. Merchants need to ask for permission from the customer to be able to trigger cash flow without user interaction. This permission is granted in the form of a mandate. Mandates are granted per IBAN and are valid up to 36 months after the last transaction or until revoked by the customer.

Mandates Managed by PAYONE

PAYONE offers automatic mandate management for easy and compliant mandate management by the merchant. In order to invoke the PAYONE mandate management, you need to implement the managemandate Request. This request takes personal data of your customer (most importantly their IBAN) as input and checks whether a valid mandate exists for this IBAN. If there is no valid mandate yet, the response will consist of pending mandate data, including HTML text you can use to display a compliant mandate text for the customer.

Pending Mandate - Example Request + Example Response
Request
mid=12345
aid=54321
portalid=123456
api_version=3.11
encoding=UTF-8
clearingtype=elv
mode=test
request=managemandate
country=DE
currency=EUR
zip=24118
city=Kiel
street=Fraunhoferstr. 2 - 4
email=test@payone.com
firstname=Max
lastname=Payer
iban=DE32500105171357431781
language=de

Response
status=APPROVED
mandate_identification=TM-38563881 // the unique mandate ID
mandate_status=pending
mandate_text= // html parsed for readability

SEPA-Lastschriftmandat

Zahlungsempfänger: Demo Company GmbH - Musterstadt, DE
Gläubiger-Identifikationsnummer: TESTTESTTE11
Mandatsreferenz: TM-38563881

Ich ermächtige den Zahlungsempfänger, Zahlungen von meinem Konto mittels Lastschrift einzuziehen. Zugleich weise ich mein Kreditinstitut an, die von dem Zahlungsempfänger auf mein Konto gezogenen Lastschriften einzulösen.

Hinweis: Ich kann innerhalb von acht Wochen, beginnend mit dem Belastungsdatum, die Erstattung des belasteten Betrages verlangen. Es gelten dabei die mit meinem Kreditinstitut vereinbarten Bedingungen.

Name des Zahlungspflichtigen:
    Max Payer
Straße und Hausnummer:
    Fraunhoferstr. 2 - 4
Postleitzahl:
    24118
Ort:
    Kiel
Land:
    DE
E-Mail:
    test@example.com
Bankkontonummer - IBAN:
    DEXX50010517XXXXXX1781

Kiel, 07.09.2022, Max Payer

creditor_identifier=TESTTESTTE11
iban=DE32500105171357431781
Active Mandate - Example Request + Example Response
Request
mid=12345
aid=54321
portalid=123456
api_version=3.11
encoding=UTF-8
clearingtype=elv
mode=test
request=managemandate
country=DE
currency=EUR
zip=24118
city=Kiel
street=Fraunhoferstr. 2 - 4
email=test@payone.com
firstname=Max
lastname=Payer
iban=DE32500105171357431781
language=de

Response
status=APPROVED
mandate_identification=TM-68433219
mandate_status=active
mandate_text=
creditor_identifier=TESTTESTTE11
iban=DE32500105171357431781
bic=MARKDEF1100

Pending mandates only get persisted if a payment request like preauthorization or authorization with the same IBAN are sent up to two hours after the managemandate Request.

Users have to explicitly consent to the mandate. This is mostly done in UX by clicking a checkbox. Make sure to proceed with the checkout only after consent is given.
Merchants who use our "PPS" product that aggregates payments must use the PAYONE mandate management

Download Mandate PDFs

You can use the getfile Request to receive active mandates as PDF to display them to your customers.

Getfile Example
api_version=3.11
encoding=UTF-8
file_format=PDF
file_reference=TM-68433219
file_type=SEPA_MANDATE
mid=12345
mode=test
portalid=123456
request=getfile

The response to this request will be an application/pdf encoded http stream.
Mandate PDFs will look like examples:

Manage Your Own Mandates

You can choose to manage your customers' mandates on your own. In this case, make sure that a unique mandate_identification parameter is given in the payment request. You'll have to handle all other parts of mandate management yourself, though.

Dispute Management and Chargebacks

SEPA Direct Debit payments can be disputed by the customer. Most online banking systems allow customers to revoke payments initiated by merchants pretty easily for up to 8 weeks after the payment. If such a payment has been revoked by the customer, we'll send a transactionstatus with txaction=cancelation to your transactionstatus endpoint. This event can trigger our own dunning procedure, or you'll have to handle the dispute with the customer yourself.

Testing SEPA Direct Debit

End-to-End Tests

Our platform offers test date for specific Direct Debit usecases. However, most of these will only work for the given usecase. If you want to test SEPA Direct Debits end-to-end, any formally correct IBAN will do. You could for example use your own IBAN or generate one here: http://randomiban.com/

Specific Usecases

Create a Mandate (managemandate)
These test data will not work with Frontend. Frontend is a payment form that is provided by PAYONE Platform (URL https://frontend.pay1.de/frontend/v2/ or https://secure.pay1.de/frontend/). These test data will work with Server-API / Client-API / shop modules (e.g. Magento, Oxid, Shopware, …).
Get mandate agreement from end customer
Bank-Country Bank account / IBAN Bank Code / BIC Result

DE

2599100003

12345678

always pending mandate

DE

DE00123456782599100003

TESTTEST

always pending mandate

DE

2599100004

12345678

always active mandate

DE

DE00123456782599100004

TESTTEST

always active mandate

DE

DE00123456782599100004

TESTTESX

Error 887, BIC not valid

Refunds are not possible with above test data
Download a SEPA-mandate (getfile)
file_reference  file_type file_format Result

XX-T0000000

SEPA_MANDATE

PDF

PDF-stream

XX-T0006500

SEPA_MANDATE

PDF

Error 6500

XX-T0006502

SEPA_MANDATE

PDF

Error 6502

Germany (DE) / Austria (AT)
Note: These test data will not work with Frontend. Frontend is a payment form that is provided by PAYONE Platform (URL https://frontend.pay1.de/frontend/v2/ or https://secure.pay1.de/frontend/). These test data will work with Server-API / Client-API / shop modules (e.g. Magento, Oxid, Shopware, …).
Banks often do not return specific failed causes due to privacy regulations
Bank-Country IBAN / BIC Bank Code / Accountnumber Result

DE

DE00123456782599100010

TESTTEST

12345678

2599100010

Mandate is valid for 10 minutes from creation/last usage

DE

DE00123456782599100011

TESTTEST

12345678

2599100011

Mandate is valid for 30 minutes from creation/last usage

DE

DE00123456782599100012

TESTTEST

12345678

2599100012

Mandate is valid for 60 minutes from creation/last usage

DE

DE00123456782599100013

TESTTEST

12345678

2599100013

Mandate is valid for 1400 minutes (1 day) from creation/last usage

DE

DE00123456782599100014

TESTTEST

12345678

2599100014

Mandate is valid for 2880 minutes (2 days) from creation/last usage

Direct Debit; SEPA mandates valid for 3 years after last usage:

Bank-Country IBAN / BIC Bank Code / Accountnumber Result

DE

DE85123456782599100003

TESTTEST

12345678

2599100003

Successful direct debit
 

DE

DE70120300000111111112

TESTTEST

12030000

111111112

Return debit note due to Insufficient fundsfailedcause: soc, fee: 8,60

DE

DE70120300000111111113

TESTTEST

12030000

111111113

Return debit note because the payer objects to the direct debitfailedcause: obj, RLS-Gebühr/CB-fee: 8,60

DE

DE70120300000111111114

TESTTEST

12030000

111111114

Return debit note because Account expired failedcause: cka, RLS-Gebühr/CB-fee: 8,60

DE

DE70120300000111111115

TESTTEST

12030000

111111115

Return debit note because Account no. / name not identical, incorrect or savings account failedcause: uan, RLS-Gebühr/CB-fee: 8,60

DE

DE70120300000111111116

TESTTEST

12030000

111111116

Return debit note because No direct debit failedcause: ndd, RLS-Gebühr/CB-fee: 8,60

DE

DE70120300000111111117

TESTTEST

12030000

111111117

Return debit note because the payer recalls the direct debitfailedcause: rcl, RLS-Gebühr/CB-fee: 8,60

DE

DE70120300000111111118

TESTTEST

12030000

111111118

Return debit note because the executing bank returns the direct debitfailedcause: ret, RLS-Gebühr/CB-fee: 8,60

AT

AT963500000123456789

TESTTEST

Successful direct debit

SEPA - Technical and Regulatory Details

Basics - Terminology and Definitions

SEPA

SEPA (Single Euro Payments Area) is an area consisting of 34 European countries in which payment transactions denominated in Euro are being standardized.

SEPA provides:
  • SEPA direct debit (collect money from customer)
  • SEPA credit transfer (refund money to customer)
  • in 34 countries
  • in EUR currency
     

In order to accept SEPA Direct Debit payments, merchants have to comply with certain rules set by the European Payments Council.

IBAN/BIC

For you as an online trader this transition will not only affect direct debit payments but any bank account-based payment method. From now on, bank account details must be provided in IBAN/BIC format. This is true for both your customers' and your own accounts. All German bank account details of our merchants will be converted automatically by us. However, if you are using a foreign bank account, we will have to ask you to take care of that transition yourself.

For payments via online transfer, on invoice or by prepayment, it is sufficient to indicate the IBAN/BIC of your merchant account to receive the payments. In case of refunds or repayments, the respective IBAN/BIC will also be required.

PAYONE has adapted the processing of bank statements for IBAN/BIC in such a way, that the automatic assignment of transactions and return debit notes will still be possible.

All account details for accounts with German financial institutions will automatically be converted to the IBAN/BIC format during a transaction. This means that the account details of existing customers will remain unchanged in our system until a transaction is performed. Details for bank accounts with foreign institutions cannot be converted automatically (see below).

SEPA with PAYONE

Converting account number/sort code into IBAN/BIC

We will generate the IBAN and BIC from the provided account number and sort code wherever this is necessary for a transaction for both existing customers' and newly submitted account details for German accounts. We will also complement the BIC, if only an IBAN was submitted. This allows you to use the "IBAN only" procedure, which was officially introduced in Germany on 1st February 2014. We do not offer this service for accounts at foreign institutions. For German accounts, PAYONE has a conversion rate of over 99% of all valid bank details (excluding deprecated or deleted bank codes).

We will break down the IBAN/BIC into the country-specific account details (BBAN, in Germany: account number/sort code) for both German and foreign bank accounts ensuring that the dataset in our system always contains IBAN/BIC and BBAN. Any payment information provided in IBAN/BIC format before the official SEPA migration is therefore processed correctly without any risk of rejected payments due to missing account information.

Bank account check

The so-called Bankaccount Check (request "bankaccountcheck") is extended by the above conversion. You will receive the converted account data with the response. The same applies to the new "managemandate" request (see below).

SEPA Direct Debit

SEPA requires a number of changes for processing direct debit payments. With the extension of our interfaces and enhanced features on the PAYONE Platform, we offer you to retrieve individual customised SEPA direct debits. The spectrum ranges from the simple processing of SEPA direct debits without the need to adapt the interfaces at your end up to a complete SEPA service which includes obtaining mandates as well as generating and managing mandate PDFs.

Creditor ID

The creditor ID identifies your company to the end customer and is issued on the account statement of the end customer. The creditor ID is also required for obtaining a mandate, since mandates are always created for a particular beneficiary or creditor.

If you use the PAYONE Collection Service, you are automatically assigned a business identifier of PAYONE's own creditor IDs – so everything is taken care of.

If you process direct debits via your own accounts, please send your creditor ID to PAYONE; we need this information in combination with the mandate reference for processing your direct debits.

SEPA mandate retrieval

You are generally free to adapt the retrieval process for your SEPA mandates according to your own requirements. However, there are certain rules for retrieving mandates. Please consult your principal bank to find out the exact form for obtaining your mandates.

PAYONE offers a mandate retrieval procedure that meets the requirements of the German banking industry for SEPA mandates (telecommunications-based transmission complying with the requirement for written documentation according to article 127 paragraph 2, 126 b – German Civil Code). This procedure has passed the corresponding legal examination. In addition, PAYONE has aligned this procedure with its own principal banks.

Please note that the legal situation with regard to obtaining mandates in online trading will remain uncertain in the coming years. Therefore, you will have to check with your principal bank whether it accepts the procedure described here or whether it insists on using a paper-based mandate. Please note that, in any event, the burden of proof and evidence for the existence of a mandate that was authorised by the payer is with you as the payee. Therefore, no guarantee can be given that the electronic mandate issued will be recognised by the debtor's bank in case of dispute. In this case, the deadline for returning goods is extended from 8 weeks to 13 months. (This is essentially the current practice in electronic direct debit)

PAYONE functions in the SEPA Direct Debit scheme

PAYONE provides the following functions for processing SEPA direct debits:

Mandate reference generation

If the mandate references are not transmitted by the merchant's API, PAYONE automatically generates these references. PAYONE exclusively uses recurring mandates. If you use your own mandate references, please note that PAYONE only stores one mandate reference for each individual account (IBAN). If you submit the same account with a different mandate reference, our system will reject this and issue an error message. If you leave the generation of mandate references to PAYONE, our system will automatically check for each IBAN whether a valid mandate is already available or whether a new mandate needs to be created.

For PPS merchants, these mandate references are always automatically generated and must not be transmitted with the request. This also means it's not possible to use both PPS and your own mandate management!
Determination of SEPA lead times

The SEPA regulations provide two different lead times of five and two days for an initial or for subsequent direct debits respectively. Direct debits between two German credit institutions will use the "COR1 procedure" reducing the lead time to only one day. Please consult your principal bank to find out whether and when it will support the COR1 procedure. The stipulated lead times are expressed in international banking days, so-called TARGET2 days. An additional regional banking day must be added for the submitting bank. PAYONE will determine whether the mandate is an initial or subsequent direct debit and will calculate the corresponding lead time.

Mandate text generation in HTML

PAYONE uses the request "managemandate" to generate mandate texts in the language of the consumer (currently German or English) that will be displayed to the consumer during the ordering process prompting him or her to confirm the mandate. The texts comply with the requirements of the European Payment Council EPC. Please refer to the Appendix for PAYONE's default mandate text.

Mandate text generation in PDF format

If you commission the product "SEPA mandates as PDF", a PDF containing the mandate content in the language of the consumer (currently German or English) will be created for each newly generated mandate. The texts comply with the requirements of the European Payment Council EPC. Please refer to the Appendix for PAYONE's default mandate text.

The mandate is stored on the PAYONE Platform from where you can retrieve it any time using the request "getfile".

There is a charge for generating mandates as a PDF files. Please note that PAYONE will only store one mandate for each of account (IBAN). If you order another mandate for the same account, the system will not generate a new mandate and there will not be any additional cost for you.

Using the Invoicing module for creating pre-notifications

If you have commissioned our Invoicing module for your billing processes, you can use these invoices for dispatching pre-notifications. If you use PAYONE's default invoice template, all the required SEPA data such as the creditor ID, the mandate reference and the posting date will be added automatically. If you use a custom template, please provide us with a sample when ordering the service so that we can make the necessary adjustments.

Mandate administration options

There are different options for handling mandates. The options outlined here describe a typical process in the area of retail with shipment of goods. A content provider's process may vary slightly, the SEPA functions remain the same, however. For detailed representations of the different processes and requests, please refer to the sequence diagrams in the Appendix.

SEPA direct debit with the PAYONE procedure for mandate retrieval

If you are using the full functionality of the PAYONE mandate administration, you can retrieve SEPA compliant direct debits (see above). PAYONE covers all specific SEPA requirements.

The sequence is as follows:
  1. The consumer selects a product in the merchant's online shop.
  2. The consumer enters his or her personal address and payment information.
    • The merchant system will transfer the customer data with the request "managemandate" to PAYONE. No SEPA-relevant data have to be provided. If the merchant submits a mandate reference, PAYONE will use this information. Otherwise PAYONE will generate a new mandate reference automatically.
    • PAYONE checks the payment data. If there is no mandate text associated to this account, the system will generate a "floating" mandate with a mandate reference and a mandate text in the consumer's language in HTML format.
    • If there already is a mandate, the status "active" is transmitted. The mandate retrieval and storage steps described below (items 3 and 4) will not be required then meaning that the consumer will not have to acknowledge the mandate.
  3. The SEPA-compatible mandate text is shown to the consumer for him or her to confirm.
  4. The consumer acknowledges the mandate retrieval and completes the ordering process.
    • The merchant system transmits the above-mentioned mandate reference to PAYONE with the next request (e.g. "preauthorization") which constitutes the consumer's authorisation of the mandate.
    • If the merchant has commissioned the product "SEPA mandates as PDF", PAYONE will also create a mandate-PDF and save this on the PAYONE Platform.
  5. The consumer will receive the mandate as a PDF file.
    • If PAYONE has generated a mandate (see above), the merchant system can use the "getfile" request to retrieve this mandate and use it for further processes (e.g. provide it for download to the consumer).
  6. The merchant dispatches the product and initiates the payment.
    • The merchant initiates the payment (e.g. using the "capture" request). No SEPA-relevant data have to be provided.
    • PAYONE will calculate the posting date and collect the direct debit.
    • PAYONE transmits all data required by the merchant for a pre-notification via the server API.
    • If the dealer has commissioned the Invoicing module, PAYONE will send the invoice with the pre-notification to the customer.

SEPA direct debit with own mandate retrieval

You can use the server API as described below, if you prefer to retrieve the mandates yourself:

  1. The consumer selects a product in the merchant's online shop.
  2. The consumer enters his or her personal address and payment information.
    • The merchant retrieves the SEPA mandate from the end customer using his or her own system and requirements. This includes defining his or her own mandate reference.
  3. The consumer completes the order.
    • The order is transferred to PAYONE using an API request (e.g. "preauthorization"). The merchant includes the above-mentioned mandate reference in the request.
    • If no mandate information has been stored at PAYONE for the transferred account details, the mandate is saved with the provided mandate reference on the PAYONE Platform.  If the merchant has commissioned the product "SEPA mandates as PDF", PAYONE will also create a mandate-PDF and save this on the PAYONE Platform.
    • No new mandate will be generated if there already is one available.
  4. The merchant dispatches the product and initiates the payment.
    • The merchant initiates the payment (e.g. using the "capture" request). No SEPA-relevant data have to be provided.
    • PAYONE will calculate the posting date and collect the direct debit.
    • PAYONE transmits all data required by the merchant for a pre-notification via the server API.
    • If the dealer has commissioned the Invoicing module, PAYONE will send the invoice with the pre-notification to the customer.
SEPA direct debit with automatically generated mandates

If PAYONE handles the generation of the mandate reference, the process is similar to the one described above under "SEPA direct debit with own mandate retrieval". The merchant is provided all relevant data for ensuring a SEPA-compliant direct debit process via the server API. PAYONE meets all technical requirements for SEPA direct debit submission and mandate referencing using this procedure. Please note, however, that you must ensure a SEPA-compliant retrieval of the mandates from your consumers yourself when using this procedure.

  1. The consumer selects a product in the merchant's online shop.
  2. The consumer enters his or her personal address and payment information.
  3. The consumer completes the order.
    • The order is transferred to PAYONE using an API request (e.g. "preauthorization"). The merchant does not transmit any SEPA-relevant data.
    • If there is no mandate for the transferred account details on the PAYONE Platform, the system will generate a new one. If the merchant has commissioned the product "SEPA mandates as PDF", PAYONE will also create a mandate-PDF and save this on the PAYONE Platform. 
    • No new mandate will be generated if there already is one available.
  4. The merchant dispatches the product and initiates the payment.
    • The merchant initiates the payment (e.g. using the "capture" request). The merchant does not transmit any SEPA-relevant data.
    • PAYONE will calculate the posting date and collect the direct debit.
    • PAYONE transmits all data required by the merchant for the mandate and the pre-notification via the server API.
    • If the dealer has commissioned the Invoicing module, PAYONE will send the invoice with the pre-notification to the customer.
More options

Of course, you can also use the different options and requests separately. For example, you can decide to use the request "managemandate" without subsequently generating and saving the mandate as a PDF file. Or you can use the product "SEPA mandates as PDF" without previously having generated a "floating" mandate using the request "managemandate".

The PAYONE server API
Request "managemandate"
The "managemandate" request provides the following functionality:
  1. Bankaccount check: The transmitted account details are validated.
  2. IBAN converter:
    • German bank account details with account number/sort code are automatically converted into the IBAN/BIC format. The converted account data is transmitted via the API. This allows you to display them to the end customers for verification and information.
    • Account details provided in the IBAN/BIC format will be complemented with the country-specific account details (BBAN, in Germany: account number/sort code).
  3. Verification whether a mandate has been stored for these account details in the past.
  4. Generation of a new "floating" mandate with a mandate text in the consumer's language in case no mandate is found.

If the mandate reference of the "floating" mandate is re-transmitted for the following request, this mandate will be stored permanently. If no subsequent request is sent, (e.g. because the consumer cancels the purchasing process), the "floating" mandate will be deleted after two hours.

Subsequent requests may be one of the following:
  • preauthorization
  • authorization
  • createaccess
  • vauthorization
  • updateuser

Since a "bankaccount check" is performed during this request it will incur the same cost per call as the request "bankaccount check" itself. You will find a description of the API parameters in the API documentation. Please refer to the Appendix for a sequence diagram with the mandate.
The request "getfile"

You can use the "getfile" request to download the mandate as a PDF from the PAYONE Platform. For this, the PDFs must have been generated previously, of course. This is done during the generation of a new mandate, if you have commissioned the product "SEPA mandates as PDF".

This request does not incur any charges. You will find a description of the API parameters in the API documentation.

Please refer to the Appendix for a sequence diagram with the mandate.

Check list: What do I have to do?
  • If you are using the PAYONE Payment Service (PPS), you do not need your own creditor ID for processing direct debits via PAYONE. You are automatically assigned a business identifier of PAYONE's creditor IDs.
  • If you are not using the PPS, you will have to provide your own creditor ID for using the direct debit procedure. You can request your own creditor ID at the German Central Bank at https://extranet.bundesbank.de/scp/.
    This is also required for working with the new requests for mandate administration in test mode.
    • If you want to use the direct debit procedure, please contact your principal bank with regard to a debt collection agreement.
    • Please clarify with your bank if direct debits are executed automatically or whether the execution requires the prior authorisation via an accompanying note to the transferred media.
  • Provide us with the IBAN/BIC information for your accounts. PAYONE has automatically converted your bank accounts held at German financial institutions to the IBAN/BIC format and sent you a corresponding overview. 
  • Decide on the nature and the scope of the SEPA implementation.
  • Plan the adaptation of your interfaces.
  • Enable the extended SEPA response data in the PMI under Configuration, Payment Portals. You can choose separate configurations for this data for test mode and for live mode to adjust your test systems accordingly.

FAQ – Frequently asked questions and answers
Question Answer

We have a great number of customers who have subscribed to our services for some time now. I have read that previously used direct debit mandates will be converted automatically into SEPA mandates. Does that mean that these mandates will remain effective? Or do we have to obtain a new direct debit mandate for each subscriber?

A valid direct debit mandate can be easily translated into a SEPA mandate. You will have to inform your customers about the conversion of their direct debit mandate indicating their mandate reference and the creditor ID. (This can be done by e-mail).

What is a pre-notification?

The pre-notification is used to announce the direct debit transaction. You may use the invoice to do this for example. The pre-notification must contain the due date and the exact amount of the transaction.

The payer needs to receive the pre-notification at least 14 calendar days before the transaction is effected to give the payer enough time to ensure that the required funds are available on the respective account. The end customer must agree to any period shorter than these fourteen days. This is usually stated in the general terms and conditions, which the customer has to acknowledge.

The pre-notification data may be incorporated in the invoice. If you are using the PAYONE Invoicing module, your invoices contain all the necessary data for a pre-notification.

I am a PPS merchant. What do I have to do now?

PPS uses a business identifier of PAYONE's creditor ID – this means that you do not need to apply for your own creditor ID.

PAYONE will also automatically generate and assign the mandate reference.

You need to obtain a valid mandate from the end customer and save it as a PDF file on the PAYONE Platform. Use the request "managemandate" to do this.

In the future, you should transmit IBAN/BIC instead of the sort code/account number combination used previously. Alternatively, PAYONE can convert German sort codes/account numbers automatically into the IBAN/BIC format and use them for the mandate and the direct debit.

I am a merchant using my own bank account. What do I have to do now?

You must use your own creditor ID and have this stored by PAYONE for future direct debit transactions. You must apply for the creditor ID in the country of your company's headquarters. This creditor ID can also be used for accounts in other countries, provided these accounts are run under your company's name.

Ask your bank if it supports COR1, the curtailed period for direct debits, if you want to use this service.

You should obtain a valid mandate from the end customer and save it as a PDF file on the PAYONE Platform. Use the request "managemandate" to do this.

In the future, you should transmit IBAN/BIC instead of the sort code/account number combination used previously. Alternatively, PAYONE can convert German sort codes/account numbers automatically into the IBAN/BIC format and use them for the mandate and the direct debit.

Why do I need to obtain a mandate and use "managemandate" to do this?

The mandate is the end customer's consent allowing you to collect the direct debit from his or her account. This mandate needs to contain specific information.

Using the "managemandate" request serves several purposes:

- Conversion of sort code/account number into an IBAN (only for accounts held in Germany)
- Verification of the IBAN/BIC

- Verification of the sort code/account number
- Submission of the mandate text
From the subsequent request, which triggers the payment (preauthorization/authorization/createaccess), this mandate will be activated and stored permanently.

If you have commissioned the product "Mandate as PDF", you can now download the generated mandate and archive and/or dispatch it to the end customer.

Appendix: Default mandate texts
Mandate text German
SEPA-Lastschriftmandat

Zahlungsempfänger: [creditorname] [creditor_city], [creditor_country]

Gläubiger-Identifikationsnummer: [creditor_identifier]

Mandatsreferenz: [mandate_identification]

Ich ermächtige den Zahlungsempfänger, Zahlungen von meinem Konto mittels Lastschrift einzuziehen. Zugleich weise ich mein Kreditinstitut an, die von dem Zahlungsempfänger auf mein Konto gezogenen Lastschriften einzulösen.

Hinweis: Ich kann innerhalb von acht Wochen, beginnend mit dem Belastungsdatum, die Erstattung des belasteten Betrages verlangen. Es gelten dabei die mit meinem Kreditinstitut vereinbarten Bedingungen.

Name des Zahlungspflichtigen: [firstname] [lastname]

Firma: [company]

Straße und Hausnummer: [street]

Postleitzahl:  [zip]

Ort:  [city]

Land: [country]

E-Mail: [email]

Swift BIC:  [bic]

Bankkontonummer - IBAN: [iban]


[city], [date], [firstname] [lastname]

 Mandate text English
SEPA Direct Debit Mandate

Creditor: [creditorname] [creditor_city], [creditor_country]

Identifier of the Creditor: [creditor_identifier]

Mandate Reference: [mandate_identification]

By signing this mandate form, you authorise the Creditor to send instructions to your bank to debit your account and your bank to debit your account in accordance with the instructions from the Creditor.

As part of your rights, you are entitled to a refund from your bank under the terms and conditions of your agreement with your bank. A refund must be claimed within 8 weeks starting from the date on which your account was debited. Your rights are explained in a statement that you can obtain from your bank.

Name of the debtor: [firstname] [lastname]

Company: [company]

Street name and number: [street]

Postal code:  [zip]

City/town: [city]

Country: [country]

E-mail: [email]

Swift BIC:  [bic]

Account number - IBAN: [iban]


[city], [date], [firstname] [lastname]

Sequence diagrams

Integrations

POST Request - managemandate
Account Parameters
request
required
Fixed Value: managemandate
mid
required
your merchant ID, 5-digit numeric
aid
required
your subaccount ID, 5-digit numeric
portalId
required
your Portal ID, 7-digit numeric
key
required
your key value, alpha-numeric
mode
required
Fixed Value: test/live
PERSONAL DATA Parameters
customerid
optional
Format CHAR(1..20)
Permitted Symbols [0-9, a-z, A-Z, .,-,_,/]

Merchant's customer ID, defined by you / merchant to refer to the customer record.

"customerid" can be used to identify a customer record. 
If "customerid" is used then stored customer data are loaded automatically.
userid
optional
Format NUMERIC(6..12)

PAYONE User ID, defined by PAYONE

salutation
optional
Format CHAR(1..10)

The customer's salutation

title
optional
Format CHAR(1..20)
Samples

Dr.

Prof.

Dr.-Ing.

Title of the customer

firstname
optional
Format CHAR(1..50)

First name of customer; optional if company is used, i.e.: you may use "company" or "lastname" or "firstname" plus "lastname"

lastname
required
Format CHAR(2..50)

Last name of customer; optional if company is used, i.e.: you may use "company" or "lastname" or "firstname" plus "lastname"

company
optional
Format CHAR(2..50)

Comany name of customer; optional if company is used, i.e.: you may use "company" or "lastname" or "firstname" plus "lastname"

street
optional
Format CHAR(1..50)

Street number and name (required: at least one character)

addressaddition
optional
Format CHAR(1..50)
Samples

7th floor

c/o Maier

Specifies an additional address line for the invoice address of the customer.

zip
optional
Format CHAR(2..50)
Permitted Symbols [0-9][A-Z][a-z][_.-/ ]

Postcode

city
optional
Format CHAR(2..50)

City of customer

country
required
Fixed Value DE
email
optional
Format CHAR(5..254)

Mandatory if "add_paydata[shopping_cart_type]=DIGITAL"

Permitted Symbols RFC 5322

Special Remark email validation:

Max. length for email is 254 characters. Validation is set up in the following way:

Username = Max. 63 characters

Domain Name = Max. 63 characters
Domain Suffixes = Max. 4 suffixes with max. 124 characters 
Example: username[63]@domain_name[63].suffix[60].suffix[60].suffix[4]

"@" and "." is counted as a character as well; in case of a total of three suffixes, this would allow a total of 254 characters.

email-address of customer

telephonenumber
optional
Format CHAR(1..30)

Phone number of customer

birthday
optional
Format DATE(8), YYYYMMDD
Samples

20190101

19991231

Date of birth of customer

language
optional
Format LIST
Permitted values ISO 639-1 (Language)2-letter-codes

Language indicator (ISO 639) to specify the language that should be presented to the customer (e.g. for error messages, frontend display).

If the language is not transferred, the browser language will be used. For a non-supported language English will be used.

vatid
optional
Format CHAR(1..50)

VAT identification number. Used for b2b transactions to indicate VAT number of customer.

gender
optional
Format LIST
Permitted values f / m / d

Gender of customer (female / male / diverse* )

* currently not in use

personalid
optional
Format CHAR(1..32)
Permitted Symbols [0-9][A-Z][a-z][+-./()]

Person specific numbers or characters, e.g. number of passport / ID card

ip
optional
Format CHAR(1..39)

Customer's IP-V4-address (123.123.123.123) or IP-V6-address

BANK Transfer PARAMETERS
clearingtype
required
Fixed Value ELV
currency
required
Format List
Permitted values ISO 4217 (currencies) 3-letter-codes
Sample

EUR

bankcountry
required
Format LIST

Account type/ country for use with BBAN (i.e. bankcode, bankaccount): DE

DE: Mandatory with bankcode, bankaccount, optional with IBAN

For other countries than DE please use IBAN or IBAN/BIC

iban
required
Format CHAR(10..34) Only capital letters and digits, no spaces
Permitted Symbols [0-9][A-Z]

Bank Identifier Code to be used for payment or to be checked

bic
optional
Format CHAR(8 or 11) Only capital letters and digits, no spaces
Permitted Symbols [0-9][A-Z]

BIC is optional for all Bank transfers within SEPA. For Accounts from Banks outside of SEPA, BIC is still required.

bankaccount
optional
Format Numeric (1..10)

Account number (BBAN)

DE: bankcountry, bankcode and bankaccount may be used. Then IBAN will be generated by PAYONE platform and used for SEPA transactions.

Not DE: Please use IBAN or IBAN / BIC.

bankcode
optional
Format Numeric (1..8)

Sort code (BBAN) (only in DE)

DE: bankcountry, bankcode and bankaccount may be used. Then IBAN will be generated by PAYONE platform and used for SEPA transactions.

Not DE: Please use IBAN or IBAN / BIC.

Response Parameters
status
required
Permitted Values
APPROVED
ERROR
Response Parameter (redirect)
 mandate_identification
Format NUMERIC(9..12)

The txid specifies the payment process within the PAYONE platform

 mandate_status
Format LIST

Status of SEPA mandate 

 mandate_text
Format TEXT

Content of mandate text

HTML-formatted, URL-encoded

 creditor_identifier
Format CHAR(1..35)

Creditor identifier as recorded at PAYONE 

 iban
Format CHAR(10..34)

IBAN to be used for payment or to be checked 

 bic
Format CHAR(8 or 11)

Bank Identifier Code to be used for payment or to be checked 

ReSponse Parameter (Error)
Format NUMERIC(1..6)

In case of error the PAYONE Platform returns an error code for your internal usage.

Format CHAR(1..1024)

In case of error the PAYONE Platform returns an error message for your internal usage.

Format CHAR(1..1024)

The customermessage is returned to your system in order to be displayed to the customer.

(Language selection is based on the end customer's language, parameter "language")

Host: api.pay1.de
Content-Type: application/x-www-form-urlencoded
Payload

request=managemandate
mid=23456
aid=12345
portalid=12345123
key=abcdefghijklmn123456789
mode=test
customerid=140
firstname=Testperson-de
lastname=Approved
street=Fraunhofer Str. 2-4
zip=24118
city=Kiel
country=DE
email=test@payone.com
clearingtype=elv
currency=EUR
bankcountry=DE
iban=DE26300209000211691049
bic=
bankaccount=
bankcode=
encoding=UTF-8
language=de
RESPONSE

status=APPROVED
mandate_identification=TM-46120646
mandate_status=active
mandate_text=
creditor_identifier=TESTTESTTEST
iban=DE26300209000211691049
bic=CMCIDEDDXXX                
POST Request - Pre-/ Authorization
Account Parameters
request
required
Fixed Value: preauthorization / authorization
mid
required
your merchant ID, 5-digit numeric
aid
required
your subaccount ID, 5-digit numeric
portalId
required
your Portal ID, 7-digit numeric
key
required
your key value, alpha-numeric
mode
required
Fixed Value: test/live
PERSONAL DATA Parameters
customerid
optional
Format CHAR(1..20)
Permitted Symbols [0-9, a-z, A-Z, .,-,_,/]

Merchant's customer ID, defined by you / merchant to refer to the customer record.

"customerid" can be used to identify a customer record. 
If "customerid" is used then stored customer data are loaded automatically.
userid
optional
Format NUMERIC(6..12)

PAYONE User ID, defined by PAYONE

salutation
optional
Format CHAR(1..10)

The customer's salutation

title
optional
Format CHAR(1..20)
Samples

Dr

Prof.

Dr.-Ing.

Title of the customer

firstname
optional
Format CHAR(1..50)

First name of customer; optional if company is used, i.e.: you may use "company" or "lastname" or "firstname" plus "lastname"

lastname
required
Format CHAR(2..50)

Last name of customer; optional if company is used, i.e.: you may use "company" or "lastname" or "firstname" plus "lastname"

company
optional
Format CHAR(2..50)

Comany name of customer; optional if company is used, i.e.: you may use "company" or "lastname" or "firstname" plus "lastname"

street
optional
Format CHAR(1..50)

Street number and name (required: at least one character)

addressaddition
optional
Format CHAR(1..50)
Samples

7th floor

c/o Maier

Specifies an additional address line for the invoice address of the customer.

zip
optional
Format CHAR(2..50)
Permitted Symbols [0-9][A-Z][a-z][_.-/ ]

Postcode

city
optional
Format CHAR(2..50)

City of customer

country
required
Fixed Value DE
email
optional
Format CHAR(5..254)

Mandatory if "add_paydata[shopping_cart_type]=DIGITAL"

Permitted Symbols RFC 5322

Special Remark email validation:

Max. length for email is 254 characters. Validation is set up in the following way:

Username = Max. 63 characters

Domain Name = Max. 63 characters
Domain Suffixes = Max. 4 suffixes with max. 124 characters 
Example: username[63]@domain_name[63].suffix[60].suffix[60].suffix[4]

"@" and "." is counted as a character as well; in case of a total of three suffixes, this would allow a total of 254 characters.

email-address of customer

telephonenumber
optional
Format CHAR(1..30)

Phone number of customer

birthday
optional
Format DATE(8), YYYYMMDD
Samples

20190101

19991231

Date of birth of customer

language
optional
Format LIST

Permitted values ISO 639-1 (Language)2-letter-codes

Language indicator (ISO 639) to specify the language that should be presented to the customer (e.g. for error messages, frontend display).

If the language is not transferred, the browser language will be used. For a non-supported language English will be used.

vatid
optional
Format CHAR(1..50)

VAT identification number. Used for b2b transactions to indicate VAT number of customer.

gender
optional
Format LIST
Permitted values f / m / d

Gender of customer (female / male / diverse* )

* currently not in use

personalid
optional
Format CHAR(1..32)
Permitted Symbols [0-9][A-Z][a-z][+-./()]

Person specific numbers or characters, e.g. number of passport / ID card

ip
optional
Format CHAR(1..39)

Customer's IP-V4-address (123.123.123.123) or IP-V6-address

BANk Transfer PARAMETERS
clearingtype
required
Fixed Value ELV
amount
required
Format NUMERIC(1..10)
Permitted values max. +/- 19 999 999 99
Specifies the total gross amount of a payment transaction.

Value is given in smallest currency unit, e.g. Cent of Euro.

The amount must be less than or equal to the amount of the corresponding booking.

currency
required
Format List
Permitted values ISO 4217 (currencies) 3-letter-codes
Sample

EUR

bankcountry
required
Format LIST

Account type/ country for use with BBAN (i.e. bankcode, bankaccount): DE

DE: Mandatory with bankcode, bankaccount, optional with IBAN

For other countries than DE please use IBAN or IBAN/BIC

iban
optional
Format CHAR(10..34) Only capital letters and digits, no spaces
Permitted Symbols [0-9][A-Z]

Bank Identifier Code to be used for payment or to be checked

bic
optional
Format CHAR(8 or 11) Only capital letters and digits, no spaces
Permitted Symbols [0-9][A-Z]

BIC is optional for all Bank transfers within SEPA. For Accounts from Banks outside of SEPA, BIC is still required.

bankaccount
optional
Format Numeric (1..10)

Account number (BBAN)

DE: bankcountry, bankcode and bankaccount may be used. Then IBAN will be generated by PAYONE platform and used for SEPA transactions.

Not DE: Please use IBAN or IBAN / BIC.

bankcode
optional
Format Numeric (1..8)

Sort code (BBAN) (only in DE)

DE: bankcountry, bankcode and bankaccount may be used. Then IBAN will be generated by PAYONE platform and used for SEPA transactions.

Not DE: Please use IBAN or IBAN / BIC.

Response Parameters
status
required
Permitted Values
APPROVED
ERROR
Response Parameter (redirect)
Format NUMERIC(9..12)

The txid specifies the payment process within the PAYONE platform

Format NUMERIC(6..12)

PAYONE User ID, defined by PAYONE

 mandate_identification
Format CHAR(1..35)
Permitted Symbols [A-Z,a-z,0-9,+,-,.,(,)]

A SEPA mandate can be created if a payment is initiated (amount > 0). Can be used to enforce a merchant specific mandate identification. The mandate_identification has to be unique. 

 mandate_dateofsignature
Format NUMERIC(8)

Date when mandate has been created (format YYYYMMDD)

 creditor_identifier
Format CHAR(1..35)

Creditor identifier as recorded at PAYONE 

 creditor_name
Format CHAR(2..50)

Creditor name of customer; optional if company is used, i.e.: you may use "company" or "lastname" or "firstname" plus "lastname"

 creditor_street
Format CHAR(1..50)

Street number and name (required: at least one character)

 creditor_zip
Format CHAR(2..50)
Permitted Symbols [0-9][A-Z][a-z][_.-/ ]

Postcode

 creditor_city
Format CHAR(2..50)

City of creditor

 creditor_country
Format Fixed Value DE
 creditor_email
Format CHAR(5..254)

Email-address of customer

ReSponse Parameter (Error)
Format NUMERIC(1..6)

In case of error the PAYONE Platform returns an error code for your internal usage.

Format CHAR(1..1024)

In case of error the PAYONE Platform returns an error message for your internal usage.

Format CHAR(1..1024)

The customermessage is returned to your system in order to be displayed to the customer.

(Language selection is based on the end customer's language, parameter "language")

Host: api.pay1.de
Content-Type: application/x-www-form-urlencoded
Payload

https://api.pay1.de/post-gateway/
aid=54400
amount=2000
api_version=3.10
bankaccountholder=Maximilian Testerei
city=Dresden
clearingtype=elv
country=DE
currency=EUR
email=test@payone.com
encoding=UTF-8
firstname=Maximillian
hash=0123456789abcdefghilk
iban=DE74500105173158518489
key=19539eb4b369b29f314b51368076475a
language=de
lastname=Testerei
mid=54399
mode=test
portalid=2039743
reference=1240300401
request=preauthorization
salutation=Frau
street=Wegeweg 25
zip=01234
RESPONSE

status=APPROVED
txid=988063012
userid=657637098
mandate_identification=TM-78419334
mandate_dateofsignature=20230228
creditor_identifier=TESTTESTTEST
creditor_name=Payone Test
creditor_street=Fraunhoferstr. 2 - 4
creditor_zip=24118
creditor_city=Kiel
creditor_country=DE
creditor_email=test@payone.com