Payment API 1.8 Documentation

Open invoice, instalments and direct debit - Ratepay is your partner for easy and secure payments!

We are experts in individual payment solutions!

We handle the entire payment process and carry the risk for payment default. Our products with immediate online approval include instalment payment, open invoice, direct debit and payment in advance.

Hello World!

If you are not familiar with our Payment API, we recommend to start with our Introduction.

Quick Links

For those who don't like to use the Search field, here some links related to FAQ.

Gateway URL

Ratepay Gateway URLs

Sequence Flows

How to integrate Ratepay

XSD Files

XML schema files (XSD)


You won't start from scratch? Try the PHP SDK.

GitHub: Ratepay PHP SDK


GitHub: Ratepay GmbH

Version History

Version Date Changes
1.8.12 September 2020 - Updated XML schema files (XSDs)
1.8.11 May 2019 - Added XML examples for Payment Initialization, Payment Query, Payment Request, Payment Confirmation, Confirmation Deliver, Payment Change, Configuration Request and Calculation Request
1.8.10 February 2019 - Published documentation online
- Registry Address for companies is no longer supported
- Editorial changes
1.8.9 December 2018 - Added <shop-id> for partners
1.8.8 October 2018 - <payment-firstday> now supports Instalments with direct debit
1.8.7 August 2018 - Added new Reason Codes
1.8.6 March 2018 - Payment Confirm is now optional
- Company types: Added mandatory and optional fields
1.8.5 March 2018 - Editorial changes
- Small changes in 7.1.2 List of Reason Codes and corresponding Result Codes
- Added 7.1.3 Calculation Request: Reason Codes and Description
1.8.4 October 2017 - Editorial changes
1.8.3 August 2017 - Added language of the customer
- Included Customer Language Appendix 4
1.8.2 June 2016 - Korrektur der Erklärung zum Feld reference-id im External Block
1.8.1 February 2016 - Editorial changes
1.8 November 2015 - Introducing API 1.8 logic
- Added calulcation-start to Calculation Request parameters
- Added special items shipping and discount
- Added item attribute discount
- Added reference-id and api-version October 2015 - Added Tracking-ID list
- new B2B parameters
1.7.5 June 2015 - Added note about the new feature “Extended Response”
- Added section about sending special characters
- and parameters are optional for all Payment Change subtypes
- is not needed anymore (deprecated)
- now is mandatory for Payment Request and Payment Query
- payment@currency not mandatory anymore
1.7.1 August 2018 - Removed deprecated and backward elements
1.7 April 2014 - Simplified Payment Changes sub-types
-Removed deprecated device fingerprinting elements and added new elements
- Set Payment Query response parameters limits and classification to deprecated
- Enhanced Ratepay responses July 2013 - Updated referenced documents
1.6.3 June 2013 - Revised Shopping basket item - split the old and new way of handling the shopping basket and added explanation
1.6.2 March 2013 - Reworked chapter about Payment Changes and added further explanantion to the XML examples