Skip to content

    Ratepay Direct Debit

    Overview - Ratepay Direct Debit

    Ratepay - Direct Debit is a payment method, which allows the easy and secure processing of SEPA Direct Debit payments.

    By choosing Ratepay - Direct Debit, the customer issues a SEPA Direct Debit mandate, which authorizes Ratepay to collect purchase-related funds directly from the customer's bank account.

    The main advantages for merchants using Ratepay - Direct Debit are:

    • 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 - Direct Debit are:

    • Ratepay - Direct Debit is easy and convenient for customers because they only need to provide their name and IBAN to make a payment.
    • There is no obligation for the customer to create a user account with Ratepay or to provide additional information.

    Activation - Ratepay Direct Debit

    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 Direct Debit

    StepDescriptionImage
    1Choose Lastschrift (Ratepay - Direct Debit)
    2Enter Account Holder and IBAN
    3Click Pay
    4Success or Failure Notification

    Payengine Details - Ratepay Direct Debit

    General

    NameDetails
    ProductRatepay Direct Debit
    Payment Options (for Customer)SEPA Direct Debit
    ChannelsECOM & MOTO
    CurrenciesEUR
    CountriesDE, AT, NL
    Technical FlowSynchronous
    Recurring
    No
    Chargebacks
    No
    B2B applicableYes - only for DE and AT

    Supported Features & Services

    NameDetails
    DebitYes
    PreauthorizationYes
    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

    NameDetails
    APIYes
    WidgetYes
    BridgeNo
    Shop PluginYes
    PaylinkYes

    Integration via API - Ratepay Direct Debit

    Technical Flow

    RatePAY DirectDebit IntegrationviaAPI technicalflow

    Specifications - Ratepay Direct Debit

    Prerequisites for Authorizing Transactions

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

    Customer

    The specific request parameters for creating Customer objects are different when the end-user is individual (B2C cases) or organization (B2B cases).

    Customer in B2C cases

    Create Customer - Request Parameters

    ParameterMandatory/Optional (M/O)DescriptionExample
    EmailMThe email address of the customerjohn@doe.com

    Customer in B2B cases

    Create Customer - Request Parameters

    ParameterMandatory/Optional (M/O)DescriptionExample
    EmailMAn email address from the customer organizationJohn.Doe@organization.com
    Customer TypeMThis parameter has only one possible value - organizationorganization
    Company NameMThe organization's official namePower Group
    Organization Registration IDOThe organization's unique registration ID numberDE1234
    Organization Entity TypeO The organization's legal form. Valid values:
    • for DE - AG, AOR, EG, EINZELUNTERNEHMER, EK ,EV, GBR, GGMBH, GMBH, GMBH-CO-KG, GMBH-I-GR, KG, KOR, OHG, PARTNERSCHAFT, STIFTUNG, UG, UG-I-GR
    • for AT - AG, EINZELUNTERNEHMER, GBR, GMBH, GMBH-CO-KG, KEG, KG, OEG, OG, OHG
    GMBH
    Organization VAT IDOThe organization's unique VAT ID numberDE123456789

    Persona

    Create Persona - Request Parameters

    ParameterMandatory/Optional (M/O)DescriptionExample
    First NameMThe person's first nameJohn
    Last NameMThe person's last nameDoe
    BirthdayM(for B2C)
    O(for B2B)
    The person's birth date.

    Requirement: the person has to be at least 18 years old
    358293600000
    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="https://pp.payengine.de/bridge/1.0/payengine.min.js" 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)DescriptionExample
    termsMThe Additional General Terms and Conditions of Ratepay GmbHnumber (timestamp)1468590412476
    privacyMThe Data Protection Notice of Ratepay GmbHnumber (timestamp)1468590412476
    channelMThe channel of origin for the order. Possible values: ECOM, MOTOstringECOM
    basketMThe default range for the basket value is from EUR 20 to EUR 2,000 but it can vary according to the merchant's contract.data objectsee Samples
    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
    bankNameOThe name of the account holder's bankstringDeutsche Bank
    ibanMThe account holder's IBANstringDE82370502991390006124
    bicOThe BIC of the account holder's bankstringCOKSDE33XXX
    accountHolderMThe account holder's namestringJohn Doe
    riskIdentIdMThe device ident tokenstringrpRiskIdentId_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 attributes.data objectSee Samples

    Request and response samples for update order transaction can be found below.

    Samples

    Preauth transaction

    POST/orders/preauth

    Create Preauth Request

    {
    		"terms": 1468590412476,
    		"privacy": 1468590412476,
    		"description": "RP DD",

    Create Preauth Response

    {
    		"createdAt": 1550850885443,
    		"modifiedAt": 1550850885448,
    		"merchantId": "merchant_remlk0ewja",

    Capture transaction

    POST/orders/{orderId}/transactions/{transactionId}/capture

    Create Capture Request

    {
    		"description": "description for operation.",
    		"currency": "EUR",
    		"initialAmount": 666,

    Create Capture Response

    {
    		"createdAt": 1550853701815,
    		"modifiedAt": 1550853701846,
    		"type": "CAPTURE",

    Cancel transaction

    POST/orders/{orderId}/transactions/{transactionId}/cancel

    Create Cancel Request

    {
    		"initialAmount": 666,
    		"currency": "EUR",
    		"description": "string",

    Create Cancel Response

    {
    		"createdAt": 1550854244696,
    		"modifiedAt": 1550854244715,
    		"type": "CANCEL",

    Debit transaction

    POST/orders/debit

    Create Debit Request

    {
    		"terms": 1468590412476,
    		"privacy": 1468590412476,
    		"description": "RP DD",

    Create Debit Response

    {
    		"createdAt": 1550854733619,
    		"modifiedAt": 1550854733625,
    		"merchantId": "merchant_remlk0ewja",

    Refund transaction

    POST/orders/{orderId}/transactions/{transactionId}/refund

    Create Refund Request

    {
    		"description": "description for operation.",
    		"currency": "EUR",
    		"initialAmount": 666,

    Create Refund Response

    {
    		"createdAt": 1550855045489,
    		"modifiedAt": 1550855045507,
    		"type": "REFUND",

    Testing

    Ratepay - Direct Debit testing can be performed 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:

    Accept:

    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

    Decline:

    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?