Ratepay

https://docs.ratepay.com/
Admin
Ratepay is a white-label Buy Now, Pay Later (BNPL) payment solution that provides flexible payment...
Tokens:474,087
Snippets:3,430
Trust Score:9.8
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install ClientSecurityKit pod

Source: https://docs.ratepay.com/docs/developer/device_fingerprinting/ios.md

Run pod install to install the ClientSecurityKit pod. The output shows the installation process and a warning about the missing platform specification.

```bash
$ pod install
Analyzing dependencies
Downloading dependencies
Using ClientSecurityKit (1.2.5)
Generating Pods project
Integrating client project
Sending stats
Pod installation complete! There is 1 dependency from the Podfile and 1 total pod installed.
[!] Automatically assigning platform `ios` with version `11.0` on target `app` because no platform was specified. Please specify a platform for this target in your Podfile. See `https://guides.cocoapods.org/syntax/podfile.html#platform`.
```

--------------------------------

### Install Ratepay via Composer and Enable Module

Source: https://docs.ratepay.com/docs/developer/shop_modules/magento/magento_2/get_started/installation.md

Run these commands from the root of your shop directory to install the package, enable the module, and update the Magento setup.

```bash
composer require ratepay/magento2-payment
php bin/magento module:enable RatePAY_Payment
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento cache:clean
```

--------------------------------

### Example 1: All fields filled in (CSV)

Source: https://docs.ratepay.com/docs/reporting/regular_customers/technical_description.md

CSV example with all fields populated, including order, delivery, payment dates, amounts, and flags. The header row defines the required columns. This example corresponds to the sample rows described in the table above.

```csv
FileRownumber;InterfaceVersion;ShopsOrder_ID;ShopsCustomer_ID;OrderDate;OrderTime;DeliveryDate;PaymentDate;PaymentMethod;Currency;OrderAmount;PaymentAmount;CancellationAmount;ReturnAmount;LoginFlag;NewAddressFlag;ReturningPeriod
1;1;"123456";"sci1234";"2017-12-01";"09:17:24";"2017-12-03";"2017-12-17";"INV1";"EUR";110.00; 90.00;0.00;0.00;1;0;14
2;1;"123467";"sci2345";"2018-01-03";"16:23:27";"2018-01-06";"2018-01-25";"INV2";"EUR";200.00; 100.00;0.00;0.00;1;0;14
3;1;"123457";"sci2345";"2018-01-03";"16:23:27";"2018-01-10";"2018-02-01";"INV2";"EUR";200.00; 75.00;0.00;0.00;1;0;14
4;1;"123457";"sci2345";"2018-01-03";"16:23:27";"2018-01-15";"2018-02-08";"INV2";"EUR";200.00; 25.00;0.00;0.00;1;0;14
5;1;"123896";"sci1234";"2018-04-04";"11:27:05";"2018-04-09";"2018-04-06";"PP1";"EUR";150.00; 150.00;0.00;20.00;1;1;14
6;1;"123411";"sci3231";"2018-11-03";"08:03:43";"2018-11-05";"2018-11-08";"DD1";"EUR";80.00; 50.00;30.00;0.00;0;0;14
7;1;"123411";"sci2273";"2018-07-31";"20:12:59";"2018-08-01";"9999-12-31";"INV1";"EUR";120.00; 0.00;-5.00;0.00;1;0;14
```

--------------------------------

### Install Ratepay Payment Plugin via Composer

Source: https://docs.ratepay.com/docs/developer/shop_modules/oxid/get_started/setup/installation_under_oxid_6/installation_via_composer.md

Run this command in the shop installation directory to install the Ratepay Payment Plugin. Requires SSH access to the server where the shop and its vendor folder are located.

```php
composer require ratepay/oxid6-payment
```

--------------------------------

### CONFIGURATION_REQUEST Response XML Example

Source: https://docs.ratepay.com/docs/developer/api_integration/payment_1.8/payment_api_documentation/the_ratepay_gateway_operations/instalment_calculator/configuration_request.md

Example response XML for the CONFIGURATION_REQUEST operation. It includes the head section with processing status and the content section with installment configuration result parameters.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<response version="1.0" xmlns="urn://www.ratepay.com/payment/1_0">
    <head>
	    <system-id>MyTestsystem</system-id>
	    <operation>CONFIGURATION_REQUEST</operation>
	    <response-type>CONFIGURATION_SETTINGS</response-type>
	    <external/>
	    <processing>
		    <timestamp>2016-01-11T15:50:09.000</timestamp>
		    <status code="OK">Successfully</status>
		    <reason code="306">Calculation configuration read successful</reason>
		    <result code="500">Calculation configuration processed</result>
	    </processing>
    </head>
    <content>
	    <installment-configuration-result name="INTEGRATION_TE_DACH" type="DEFAULT">
		    <interestrate-min>0</interestrate-min>
		    <interestrate-default>0</interestrate-default>
		    <interestrate-max>0</interestrate-max>
		    <interest-rate-merchant-towards-bank>0</interest-rate-merchant-towards-bank>
		    <month-number-min>3</month-number-min>
		    <month-number-max>3</month-number-max>
		    <month-longrun>0</month-longrun>
		    <amount-min-longrun>0</amount-min-longrun>
		    <month-allowed>3</month-allowed>
		    <valid-payment-firstdays>2</valid-payment-firstdays>
		    <payment-firstday>2</payment-firstday>
		    <payment-amount>30</payment-amount>
		    <payment-lastrate>0</payment-lastrate>
		    <rate-min-normal>10</rate-min-normal>
		    <rate-min-longrun>0</rate-min-longrun>
		    <service-charge>0</service-charge>
		    <min-difference-dueday>28</min-difference-dueday>
	    </installment-configuration-result>
    </content>
</response>
```

--------------------------------

### Project directory listing after Pod init

Source: https://docs.ratepay.com/docs/developer/device_fingerprinting/ios.md

Example output of listing the project directory after running 'Pod init'. Shows the expected files and folders.

```bash
$ ls –ahl
total 24
drwxr-xr-x  6 user staff 204B Jul 28 13:06 .
drwxr-xr-x  6 user staff 204B Jul 28 13:05 ..
-rw-r--r--@ 1 user staff 6.0K Jul 28 13:06 .DS_Store
drwxr-xr-x  7 user staff 238B Jul 28 13:05 New Application
drwxr-xr-x  5 user staff 170B Jul 28 13:05 New Application.xcodeproj
-rw-r--r--  1 user staff 269B Jul 28 13:06 Podfile
```

--------------------------------

### Install module configuration

Source: https://docs.ratepay.com/docs/developer/shop_modules/oxid/get_started/setup/installation_under_oxid_6/manual_installation_via_zip/version_6.2.x.md

Run this command to create the configuration files for the Ratepay extension.

```php
vendor/bin/oe-console oe:module:install-configuration source/modules/pi/ratepay
```

--------------------------------

### CALCULATION_REQUEST XML Request

Source: https://docs.ratepay.com/docs/developer/api_integration/payment_1.8/payment_api_documentation/the_ratepay_gateway_operations/instalment_calculator/calculation_request.md

An example of a calculation request by time, specifying the amount and the number of months for the installment plan.

```xml
<?xml version="1.0"?>
<request version="1.0" xmlns="urn://www.ratepay.com/payment/1_0">
	<head>
		<system-id>MyTestsystem</system-id>
		<operation subtype="calculation-by-time">CALCULATION_REQUEST</operation>
		<credential>
			<profile-id>INTEGRATION_TE_DACH</profile-id>
			<securitycode>4c0a11923fa3433fb168f9c7176429e9</securitycode>
		</credential>
	</head>
	<content>
		<installment-calculation>
			<amount>200.00</amount>
			<calculation-time>
				<month>3</month>
			</calculation-time>
		</installment-calculation>
	</content>
</request>
```

--------------------------------

### PAYMENT_REQUEST XML structure

Source: https://docs.ratepay.com/docs/developer/api_integration/payment_1.8/payment_api_documentation/how_to_integrate_ratepay/pay_in_3.md

A complete example of the PAYMENT_REQUEST XML payload for a Pay in 3 transaction, including customer, basket, and installment details.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<request version="1.0" xmlns="urn://www.ratepay.com/payment/1_0">
  <head>
    <system-id>MyTestsystem</system-id>
    <transaction-id>xx-xxxxxxxxxxxxxx</transaction-id>
    <operation>PAYMENT_REQUEST</operation>
    <credential>
      <profile-id>INTEGRATION_TE_DACH</profile-id>
      <securitycode>4c0a11923fa3433fb168f9c7176429e9</securitycode>
    </credential>
    <external>
      <order-id>O-1234-HDZ</order-id>
      <merchant-consumer-id>12345</merchant-consumer-id>
    </external>
    <customer-device>
      <device-token>xxxxxxxxxxxxxxxxxxxxxxxx</device-token>
    </customer-device>
  </head>
  <content>
    <customer>
      <first-name>Max</first-name>
      <last-name>Mustermann</last-name>
      <gender>M</gender>
      <date-of-birth>1982-10-31</date-of-birth>
      <ip-address>127.0.0.1</ip-address>
      <contacts>
        <email>test@test.de</email>
        <phone>
          <direct-dial>030123456</direct-dial>
        </phone>
      </contacts>
      <addresses>
        <address type="BILLING">
          <street>Nicht-Versenden-Strasse</street>
          <street-number>1</street-number>
          <zip-code>12345</zip-code>
          <city>Testhausen</city>
          <country-code>DE</country-code>
        </address>
        <address type="DELIVERY">
          <street>Strasse der Lieferadresse</street>
          <street-number>2</street-number>
          <zip-code>54321</zip-code>
          <city>Testhausen</city>
          <country-code>DE</country-code>
        </address>
      </addresses>
      <bank-account>
        <owner>Max Mustermann</owner>
        <iban>DE44100500001654698497</iban>
        <bic-swift>BELADEBEXXX</bic-swift>
      </bank-account>
      <nationality>DE</nationality>
      <customer-allow-credit-inquiry>yes</customer-allow-credit-inquiry>
    </customer>

    <shopping-basket amount="200.00" currency="EUR">
      <items>
        <item article-number="A001" quantity="1" unit-price-gross="200.00" tax-rate="19">Example Product</item>
      </items>
      <shipping unit-price-gross="0.00" tax-rate="19">Versandkosten</shipping>
    </shopping-basket>

    <payment currency="EUR" method="INSTALLMENT">
      <amount>200.00</amount>
      <installment-details>
        <installment-number>3</installment-number>
        <installment-amount>66.67</installment-amount>
        <last-installment-amount>66.66</last-installment-amount>
        <interest-rate>0</interest-rate>
        <payment-firstday>2</payment-firstday>
      </installment-details>
      <debit-pay-type>DIRECT-DEBIT</debit-pay-type>
    </payment>
  </content>
</request>
```

--------------------------------

### Create MainApplication.java

Source: https://docs.ratepay.com/docs/developer/device_fingerprinting/android.md

Example of a main application class that extends Application. This is needed if you don't already have one.

```java
MainApplication.java

public class MainApplication extends Application 
	{
	@Override public void onCreate() 
		{
		super.onCreate();
		}
	}
```

--------------------------------

### CALCULATION_REQUEST XML Response

Source: https://docs.ratepay.com/docs/developer/api_integration/payment_1.8/payment_api_documentation/the_ratepay_gateway_operations/instalment_calculator/calculation_request.md

An example of a successful calculation response containing the installment plan details such as total amount, interest, and rate breakdown.

```xml
<response xmlns="urn://www.ratepay.com/payment/1_0" version="1.0">
  <head>
	<system-id>MyTestsystem</system-id>
	<operation subtype="calculation-by-time">CALCULATION_REQUEST</operation>
	<response-type>INSTALLMENT_PLAN</response-type>
	<external />
	<processing>
	  <timestamp>2016-03-29T13:37:08.000</timestamp>
	  <status code="OK">Successfully</status>
	  <reason code="603">Calculation reason: FULFILLED_CONDITION: The payment plan fulfilled the conditions.</reason>
	  <result code="502">Calculation successful</result>
	</processing>
  </head>
  <content>
	<installment-calculation-result>
	  <total-amount>200</total-amount>
	  <amount>200</amount>
	  <interest-amount>0</interest-amount>
	  <service-charge>0</service-charge>
	  <interest-rate>0</interest-rate>
	  <annual-percentage-rate>0</annual-percentage-rate>
	  <monthly-debit-interest>0</monthly-debit-interest>
	  <number-of-rates>3</number-of-rates>
	  <rate>66.67</rate>
	  <last-rate>66.66</last-rate>
	  <payment-firstday>2</payment-firstday>
	</installment-calculation-result>
  </content>
</response>
```

--------------------------------

### Apply module configuration

Source: https://docs.ratepay.com/docs/developer/shop_modules/oxid/get_started/setup/installation_under_oxid_6/manual_installation_via_zip/version_6.2.x.md

Run this command to apply the recently created configuration.

```php
vendor/bin/oe-console oe:module:apply-configuration
```

--------------------------------

### Example of correspondence_settings.payment_method_specific array

Source: https://docs.ratepay.com/docs/developer/psps_and_marketplaces/interfaces/merchant_registration_api/operations/other/retrieveshop

Example of the payment_method_specific array, showing configuration for two payment methods. The first entry uses OPEN_INVOICE with BANK_TRANSFER and includes deposit_confirmation; the second uses INSTALMENT with DIRECT_DEBIT and omits deposit_confirmation. Note that dunning_1, dunning_2, and dunning_3 in the second entry omit skip_sending, which defaults to false.

```json
[{"payment_method":{"payment_option":"OPEN_INVOICE","transfer_type":"BANK_TRANSFER"},"invoice":{"skip_sending":false,"shop_branding":true},"deposit_confirmation":{"skip_sending":false,"shop_branding":true},"dunning_1":{"skip_sending":false,"shop_branding":true},"dunning_2":{"skip_sending":false,"shop_branding":true},"dunning_3":{"skip_sending":false,"shop_branding":true}},{"payment_method":{"payment_option":"INSTALMENT","transfer_type":"DIRECT_DEBIT"},"invoice":{"skip_sending":true,"shop_branding":true},"dunning_1":{"shop_branding":true},"dunning_2":{"shop_branding":true},"dunning_3":{"shop_branding":true}}]
```

--------------------------------

### Apply configuration and install Ratepay plugin

Source: https://docs.ratepay.com/docs/developer/shop_modules/oxid/get_started/update/update_oxid_6/update_process_with_composer/version_6.2.0-6.2.2.md

First command applies the updated configuration after removing Ratepay entries from yaml-files. Second command installs the Ratepay Payment Plugin via Composer.

```php
vendor/bin/oe-console oe:module:apply-configuration
```

```php
composer require ratepay/oxid6-payment
```

--------------------------------

### Create global ClientSecurityModule reference

Source: https://docs.ratepay.com/docs/developer/device_fingerprinting/ios.md

Create a global reference to the ClientSecurityModule.

```bash
var module : ClientSecurityModule?
```

--------------------------------

### Calculate Pay in 3 installments in JavaScript

Source: https://docs.ratepay.com/docs/developer/api_integration/payment_1.8/payment_api_documentation/how_to_integrate_ratepay/pay_in_3.md

This function calculates the installment schedule for a Pay in 3 product. It handles rounding remainders by assigning them to the final installment and determines the first due date based on the shipment date.

```javascript
function calculatePayIn3(amount, shipmentDate) {
  // --- Configuration: Pay in 3 is a 0% interest, 0-fee product ---
  const NUMBER_OF_INSTALLMENTS = 3;
  const DURATION_UNIT = "months";
  const INTEREST_RATE = 0;
  const INTEREST_AMOUNT = 0;
  const FEES_AMOUNT = 0;
  const HAS_INTEREST = false;
  const HAS_FEES = false;

  // --- Calculate installment amounts ---
  // Split evenly; any rounding remainder goes to the final installment
  const regularAmount = Math.round((amount / NUMBER_OF_INSTALLMENTS) * 100) / 100;
  const finalAmount = Math.round((amount - regularAmount * (NUMBER_OF_INSTALLMENTS - 1)) * 100) / 100;

  // --- Determine the first due date ---
  // First instalment is due on the 2nd of the month following shipment,
  // provided there are at least 28 days between shipment and that date.
  // Otherwise, it is pushed to the 2nd of the subsequent month.
  function getFirstDueDate(shipment) {
    let next2nd = new Date(Date.UTC(shipment.getUTCFullYear(), shipment.getUTCMonth() + 1, 2));
    const shipmentUTC = Date.UTC(shipment.getUTCFullYear(), shipment.getUTCMonth(), shipment.getUTCDate());
    const next2ndUTC = Date.UTC(next2nd.getUTCFullYear(), next2nd.getUTCMonth(), next2nd.getUTCDate());
    const diffDays = Math.floor((next2ndUTC - shipmentUTC) / (1000 * 60 * 60 * 24));
    if (diffDays >= 28) return next2nd;
    return new Date(Date.UTC(shipment.getUTCFullYear(), shipment.getUTCMonth() + 2, 2));
  }

  // Parse shipmentDate string (YYYY-MM-DD) or default to today, using UTC for consistency
  let shipment;
  if (shipmentDate) {
    const parts = shipmentDate.split("-");
    shipment = new Date(Date.UTC(+parts[0], +parts[1] - 1, +parts[2]));
  } else {
    const today = new Date();
    shipment = new Date(Date.UTC(today.getFullYear(), today.getMonth(), today.getDate()));
  }
  const firstDue = getFirstDueDate(shipment);

  // --- Build the installment schedule ---
  const schedule = [];
  let remaining = amount;
  for (let i = 1; i <= NUMBER_OF_INSTALLMENTS; i++) {
    const dueDate = new Date(Date.UTC(firstDue.getUTCFullYear(), firstDue.getUTCMonth() + (i - 1), 2));
    const payment = i < NUMBER_OF_INSTALLMENTS ? regularAmount : finalAmount;
    remaining = Math.round((remaining - payment) * 100) / 100;
    schedule.push({
      installmentNumber: i,
      estimatedDueDate:
        dueDate.getUTCFullYear() + "-" +
        String(dueDate.getUTCMonth() + 1).padStart(2, "0") + "-" +
        String(dueDate.getUTCDate()).padStart(2, "0"),
      paymentAmount: payment,
      principalAmount: payment,
      interestAmount: INTEREST_AMOUNT,
      feesAmount: FEES_AMOUNT,
      remainingPrincipalBalanceAmount: remaining,
    });
  }

  // --- Return the complete plan object ---
  return {
    planMetadata: { hasInterest: HAS_INTEREST, hasFees: HAS_FEES },
    repaymentPlan: {
      numberOfInstallments: NUMBER_OF_INSTALLMENTS,
      durationOfInstallments: DURATION_UNIT,
      regularInstallmentAmount: regularAmount,
      finalInstallmentAmount: finalAmount,
    },
    creditTerms: {
      totalPayableAmount: amount,
      totalCostOfCreditAmount: INTEREST_AMOUNT + FEES_AMOUNT,
      totalInterestAmount: INTEREST_AMOUNT,
      totalFeesAmount: FEES_AMOUNT,
      nominalInterestRatePercentage: INTEREST_RATE,
      annualPercentageRate: INTEREST_RATE,
    },
    fees: { serviceFeeAmount: FEES_AMOUNT },
    installmentSchedule: schedule,
  };
}
```
Tokens:
Raw