Skip to content

    Ratepay Installment

    Overview - Ratepay Installment

    Ratepay - Installments enables customers to pay for purchases in installments and choose a convenient payback plan.

    Ratepay settles the purchase with the merchant and finances the customer in exchange for interest. The financing amount is usually between EUR200 and EUR2,000 but can vary according to the merchant's contract with Ratepay.

    Customers can choose the number of monthly installments, which are usually 3, 6, 9, 12 or 24. In some cases, Ratepay can authorize a merchant to offer payments in 36 or 48 installments. The longer the payback period, the higher the interest.

    Customers have to meet certain requirements to be entitled to pay with Ratepay - Installments.

    Ratepay charges customers with a small service charge for every purchase.

    Customers can use bank transfer or SEPA direct debit to pay their installments.

    The main advantages for merchants using Ratepay - Installments are:

    • The merchant receives the whole purchase price from Ratepay, which effectively grants a loan to the customer;
    • The entire user experience takes place on the merchant's website, and there is no need to redirect the customer to a third-party webpage to complete payment.
    • As with all Ratepay payment methods, the risk of customer payment default is transferred from the merchant to Ratepay;

    The main advantages for customers using Ratepay - Installments are:

    • Ratepay - Installments provides an easy and quick way for customers to complete their purchases;
    • Flexibility: the customer can choose different finance amounts and different payback periods;
    • There is no need to create a Ratepay user account.

    Activation - Ratepay Installment

    To activate Ratepay as a payment method and to add it to your PayEngine Merchant Center, you need to complete the onboarding journey.

    Please provide our support with the following information:

    • Profile ID
    • Security Code
    • ShopID
    • Device Ident AppID

    If you do not yet have a Rate Pay merchant contract, please contact your sales representative.

    Customer Experience - Ratepay Installment

    1Choose Ratenzahlung (Ratepay Installments)
    2Choose Calculation Type from the drop-down menu (Calculation Rate or Calculation Time)
    2.1.1To use Calculation Rate as Calculation Type - Choose Calculation Rate and enter the desired value
    2.1.2Click Calculate. The installment plan will appear.
    2.2.1To use Calculation Time as Calculation Type - Choose Calculation Time and choose the desired payback duration
    2.2.2Click Calculate. The installment plan will load.
    3Choose Payment Type - Direct Debit or Bank Transfer
    3.1.1To use Direct Debit as Payment Type - Choose Direct Debit, and enter Account Holder and IBAN
    3.1.2Click Declaration of SEPA mandate
    3.1.3Click Pay
    3.2To use Bank Transfer as Payment Type - Choose Bank Transfer and click Pay
    4Success or Failure notification

    Note: Calculation Type and Payment Type are customizable. For more information, check Widget Customization.

    Payengine Details - Ratepay Installment


    Supported Features & Services

    CancellationYes (full and partial)
    CaptureYes (full and partial)
    RefundsYes (full and partial)
    NotificationsYes (webhook and email)
    Settlement Reportingyes, only original Ratepay Settlement Reporting

    Integration Types

    ProductRatepay - Installments
    Payment Options (for Customer)
    • Direct Debit
    • Bank Transfer
    ChannelsECOM & MOTO
    CountriesDE, AT
    Technical FlowSynchronous
    B2B applicable
    Shop PluginYes

    Integration via API - Ratepay Installment

    Technical Flow

    RatePAY Installment IntegrationviaAPI technicalflow

    Specifications - Ratepay Installment

    Prerequisites for Authorizing Transactions

    PrerequisiteMandatory/Optional (M/O)Create Prerequisite
    Billing AddressMPOST/customers/{{customerId}}/addresses
    Shipping AddressMPOST/customers/{{customerId}}/addresses


    The only type of transaction for Ratepay Installments is business to customer (B2C). There is no business to business (B2B) option for this service.

    Create Customer - Request Parameters

    ParameterMandatory/Optional (M/O)DescriptionExample
    EmailMThe email address of the


    Create Persona - Request Parameters

    ParameterMandatory/Optional (M/O)DescriptionExample
    First NameMThe person's first nameJohn
    Last NameMThe person's last nameDoe
    BirthdayMThe person's birth date.

    Requirement: the person has to be at least 18 years old
    TitleOThe person's titleProf. Dr.
    PhoneOThe person's home phone00493012345
    MobileOThe person's mobile phone00493012345
    FaxOThe person's fax number00493012345
    GenderOThe person's genderMALE

    Billing/Shipping Address

    The Billing and Shipping Address must be identical. Exceptions for merchants are possible only through additional agreements with Ratepay GmbH.

    Create Billing/Shipping Address - Request Parameters

    ParameterMandatory/Optional (M/O)DescriptionExample
    First NameMThe customer's or recipient's first nameJohn
    Last NameMThe customer's or recipient's last nameDoe
    StreetMThe customer's or recipient's streetMusterweg
    House NumberMTThe customer's or recipient's home number4313
    CityMThe customer's or recipient's cityMusterhausen
    ZipMThe customer's or recipient's ZIP code55555
    CountryMThe customer's or recipient's countryDE
    PhoneMThe customer's or recipient's home phone number00493012345
    StateOThe customer's or recipient's state/provinceBayern
    FaxOThe customer's or recipient's fax number00493012345
    MobileOThe customer's or recipient's mobile phone number00493012345
    TitleOThe customer's or recipient's titleProf. Dr.

    Device Identification for Ratepay Payment Methods

    In general Device Identification can be defined as a technique used to establish a "fingerprint" of a user's device used to access certain website or application of interest in order to track device activity and determine linkages between other devices.

    The main purpose of Device Identification technique is to support prevention of possible fraudulent operations.

    Device Identification is a mandatory prerequisite for all Ratepay payment methods. It has to be created prior to execution of any authorizing transactions (Preauth or Debit).

    For API integration of Ratepay payment methods it's recommended merchants to follow three steps regarding Device Identification:

    1) Creating Device Ident using POST method

    A POST request with empty body has to be directed to the following endpoints:

    Response of the request will contain the following properties:

    • deviceIdentToken
    • deviceIdentSId
    • sessionToken

    Example response to Create Device request can be found below:

    Create Device Ident Reponse

    		"deviceIdentToken": "a95314a9d82918657fad2b07436602bb",
    		"deviceIdentSId": "ratepay",
    		"sessionToken": "58c93b94b6f01ab057683125a47390fb"

    __2) Loading Payengine Bridge and External Libraries of Ratepay Device Ident __

    Based on the parameters received in the response of POST request in step one, the following has to be executed:

    Loading Payengine Bridge and External Libraries of Ratepay

    <script src="" type="text/javascript"> </script>
          <script type="text/javascript">
            window.onload = function() {

    3) Sending Device Ident Token to Create Transaction Endpoint

    Device Ident Token has to be sent via POST method in the body of Create Authorizing Transaction (Preauth or Debit) request.

    It will be placed within Payment object in the field riskIdentId as shown below:

    Sending Device Ident Token

          payment: {
          riskIdentId: "DEVICE_IDENT_TOKEN"

    Authentication for Ratepay Payment methods has to be Bearer merchantId.

    Input Parameters for Authorizing Transactions

    The following input parameters are required for initiating a payment via Payengine Widget:

    ParameterMandatory/Optional (M/O)DescriptionTypeExample
    termsМThe Additional General Terms and Conditions of Ratepay GmbHnumber (timestamp)1468590412476
    privacyМThe Data Protection Notice of Ratepay GmbHnumber (timestamp)1468590412476
    basketМThe default range for the basket value is from EUR 20 to EUR 2,000 but it can vary according to the merchant's contract.basket data objectsee Samples
    channelMThe channel of origin for the order. Possible values: ECOM, MOTOstringECOM
    ipAddressMThe IP address used to submit the order.string82.120.21.79
    paymentMTop level
    See below table "Payment sub-parameters" for more information.
    data objectsee Samples
    ParameterMandatory/Optional (M/O)DescriptionTypeExample
    accountHolderМThe account holder's namestringJohn Doe
    bankNameOThe name of the account holder's bankstringDeutsche Bank
    bicOThe BIC of the account holder's bankstringCOKSDE33XXX
    ibanMThe account holder's IBANstringDE82370502991390006124
    interest rateMThe annual interest rate on the loannumber13.7
    last rateMThe amount of the last installmentnumber2166
    numberOfRatesMThe number of installmentsnumber10
    rateMThe amount of a regular installmentnumber2177
    totalAmountMThe total amount of the purchasenumber21759
    riskIdentIdM/OThe device ident token. Required for ECOM channel only.stringrpRiskIdentId_1550854753

    Specific Response Parameters for Authorizing Transactions

    Payengine sends the following response parameter, which is used by the merchant to trail customer money transfers:

    ParameterMandatory/Optional (M/O)DescriptionTypeExample
    meta.descriptorMPayengine generates a descriptor element to each response for RatePAY authorizing transactions. The merchant can use this identifier in customer invoices to track payments.UUID85f13a2c-b579-4e7a-b747-4e5b7c5ab4c6

    Input Parameters for Update Order Transaction

    The update order transaction is used to update a preauth transaction that has not been captured yet.

    Preauth transactions can be updated through the PATCH/orders/{orderId}/transactions/{transactionId} endpoint.

    ParameterMandatory/Optional (M/O)DescriptionTypeExample
    nitialAmountMAmount as the smallest currency unit. E.g. 10000 = EUR 100number23000
    currencyMThe currency codestringEUR
    basketMBasket data object with objectSee Samples

    Configuration Request

    A merchant can initiate a configuration request at the following endpoint: GET/installment/config

    With this request, the merchant can read the stored configuration parameters for his merchant profile: the minimal rate, the minimal and maximal number of monthly installments.

    Here is an example of a successful response to a configuration request:

    Configuration Response

        "rateMinNormal": 0,
        "monthNumberMin": 3,
        "monthNumberMax": 48

    This service is not needed in case Payengine Widget is used as it will perform a configuration request automatically.

    Installment calculator

    Ratepay - Installments requires the implementation of an installment calculator by merchants.

    Merchants can either use Payengine's Widget or develop their own calculator.

    Merchants have three options to approach the calculator requirement if they choose to design it on their own:

    Option 1Calculator based on the desired amount of a monthly installment
    Option 2Calculator based on the desired number of monthly installments
    Option 3Offer both calculator types

    Option 1 - Calculator based on the desired amount of a monthly installment

    The merchant can implement a user interface with a field for the desired amount of a monthly installment. For example:


    The customer submits the desired installment amount and the merchant sends the following calculation request to PayEngine Backend:

    Request parameters
    • amount to be financed
    • desired monthly rate

    The response will contain a calculated installment plan with the following structure:

    Structure of Response to Calculation Request

        "totalAmount": 0,
        "amount": 0,
        "interestAmount": 0,

    The installment plan can be displayed to the end-customer as shown below:

    Ratepay Installment Installment calculator 2

    Option 2 - Calculator based on the desired number of monthly installments

    The merchant can implement a calculator interface, in which the user chooses the desired number of monthly installments. For example:

    The interface should include all possible options for the number of monthly installments within the set framework by the merchant.

    RatePAY Installment Installment calculator 3

    The customer submits the desired installment amount and the merchant sends the following calculation request to PayEngine Backend:

    Request parameters
    • amount to be financed
    • desired monthly rate

    The response will contain a calculated installment plan with the following structure:

    Structure of Response to Calculation Request

        "totalAmount": 0,
        "amount": 0,
        "interestAmount": 0,

    The installment plan can be displayed to the end-customer as shown below:

    RatePAY Installment Installment calculator 4

    Option 3 - Offer both calculator types

    The merchant can decide to integrate both calculator types to offer a comprehensive customer experience.

    Widget Customization

    Merchants can customize certain parameters in the Payengine Widget. The following options are available:

    1. BIC input field (optional) a. on b. off
    2. Calculation Types a. Calculation Rate and Calculation Time b. Calculation Rate c. Calculation Time
    3. Payment Types a. Direct Debit and Bank Transfer b. Direct Debit c. Bank Transfer

    Customization takes place via the optionalParameters.paymentDetails.ratepayInstallment data object in the JavaScript widget initialization code:

    RatePAY-Installment Widget customization Sample

    var optionalParameters = {
        "paymentDetails": {
          "ratepayInstallment": {
          "bic": true,

    Note: Information on how to integrate the different Payengine widgets is available here.


    Preauth transaction


    Create Preauth Request

        "terms": 1468590412476,
        "privacy": 1468590412476,
        "product": "ratepay-installment",

    Create Preauth Response

        "createdAt": 1551273366330,
        "modifiedAt": 1551273366344,
        "merchantId": "merchant_nrn3xhgwbx",

    Capture transaction


    Create Capture Request

        "description": "description for operation.",
        "currency": "EUR",
        "initialAmount": 21759,

    Create Capture Response

        "createdAt": 1551277844305,
        "modifiedAt": 1551277845596,
        "type": "CAPTURE",

    Cancel transaction


    Create Cancel Request

        "initialAmount": 21759,
        "currency": "EUR",
        "description": "string",

    Create Cancel Response

        "createdAt": 1551279553385,
        "modifiedAt": 1551279553401,
        "type": "CANCEL",

    Debit transaction


    Create Debit Request

      "terms": 1468590412476,
      "privacy": 1468590412476,
      "product": "ratepay-installment",

    Create Debit Response

        "createdAt": 1551278951059,
        "modifiedAt": 1551278951063,
        "merchantId": "merchant_nrn3xhgwbx",

    Refund transaction


    Create Refund Request

        "description": "description for operation.",
        "currency": "EUR",
        "initialAmount": 21759,

    Create Refund Response

        "createdAt": 1551283016525,
        "modifiedAt": 1551283016546,
        "type": "REFUND",


    Ratepay - Installments can be tested via the Ratepay Sandbox.

    The Ratepay Sandbox is a self-contained virtual testing environment that mimics the live Ratepay production environment.

    Test data for Ratepay Sandbox can be found below:


    City: Testhausen Streetname contains: Nicht Versenden DE : the postal code should be 5 digits CH & AT : the postal code should be 4 digits NL : A postal code in the Netherlands consists of four numbers followed by two capital letters (e.g 1011AB) DE IBAN : DE15111111111111111199 NL IBAN : NL18ABNA0484869868 AT IBAN: AT022050302101023600


    City: Testhausen Surname: Ablehnung DE : the postal code should be 5 digits CH & AT : the postal code should be 4 digits NL : A postal code in the Netherlands consists of four numbers followed by two capital letters (e.g 1011AB)

    Was this helpful?

    What was your feeling about it?