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:
In order to accept SEPA Direct Debit payments, merchants have to comply with certain rules set by the European Payments Council. |
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.
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 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.
You can use the getfile Request to receive active mandates as PDF to display them to your customers.
|
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.
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.
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/
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 |
file_reference | file_type | file_format | Result |
---|---|---|---|
XX-T0000000 |
SEPA_MANDATE |
|
PDF-stream |
XX-T0006500 |
SEPA_MANDATE |
|
Error 6500 |
XX-T0006502 |
SEPA_MANDATE |
|
Error 6502 |
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 (Single Euro Payments Area) is an area consisting of 34 European countries in which payment transactions denominated in Euro are being standardized.
SEPA provides:In order to accept SEPA Direct Debit payments, merchants have to comply with certain rules set by the European Payments Council.
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).
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.
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 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.
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.
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 provides the following functions for processing SEPA direct debits:
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.
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.
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.
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.
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.
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.
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:You can use the server API as described below, if you prefer to retrieve the mandates yourself:
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.
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".
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: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.
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 sort code/account number 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. |
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]
|
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]
|
POST Request - managemandate
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
|
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 "@" 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 |
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. |
status
required
|
Permitted Values
APPROVED
ERROR
|
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 |
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
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
|
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 "@" 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 |
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. |
status
required
|
Permitted Values
APPROVED
ERROR
|
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 |
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