PAYONE Documentation Platform | PAYONE Direct Debit

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:

Testmandat DE

Test mandate EN

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:

The consumer selects a product in the merchant's online shop.
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.
The SEPA-compatible mandate text is shown to the consumer for him or her to confirm.
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.

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).

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:

The consumer selects a product in the merchant's online shop.
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.

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.

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.

The consumer selects a product in the merchant's online shop.
The consumer enters his or her personal address and payment information.
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.

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:

Bankaccount check: The transmitted account details are validated.
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).

Verification whether a mandate has been stored for these account details in the past.
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]

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]

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)

errorcode	Format NUMERIC(1..6) In case of error the PAYONE Platform returns an error code for your internal usage.
errormessage	Format CHAR(1..1024) In case of error the PAYONE Platform returns an error message for your internal usage.
customermessage	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