Installment: RatePAY
Installment: RatePAY
General information
To integrate and offer the payment method installment for your consumers in your online shop you need to fulfill some important requirements:
-
By default only German consumers are allowed to use installment as payment method. Please contact RatePAY to extend the list of supported countries.
-
Check your individual conditions with RatePAY regarding minimum and maximum amount of orders, minimum age of your consumer, address of your consumer and accepted currencies.
-
Submit additional parameters which are required by RatePAY for checking the credit reliability of your consumer.
Do not offer these payment methods to your consumer in your online shop unless these requirements are met.
Please visit RatePAY for further information and details.
Order flow diagram
For a visual representation of the order flow behavior and associated transaction-based operations of this payment method we invite you to have a look at the respective order flow diagram.
Required request parameters
For payment method Installment the otherwise optional request parameters for consumer billing data and shopping basket data are required. For further information on these parameters go to Consumer billing data and Shopping basket data.
Also, the parameter consumerDeviceId is required for payment method Installment by RatePAY.
Please note the length restrictions that apply for this payment method and the following shopping basket parameters.
| Shopping basket data | |||
|---|---|---|---|
Parameter |
Within fingerprint |
Data type |
Short description |
basketItem(n)ArticleNumber |
Required if used. |
Alphanumeric with special characters and with a variable length of up to 254 characters. |
Unique ID of article n in shopping basket. |
basketItem(n)Description |
Required if used. |
Alphanumeric with special characters and with a variable length of up to 50 characters. |
Product description of article n in shopping basket. |
Device fingerprinting
The required request parameter consumerDeviceId is a security parameter used in terms of a Device Fingerprinting (DFP) which is a method of fraud protection and allows to identify technical devices used by the consumer.
| Security parameter | |||
|---|---|---|---|
Parameter |
Within fingerprint |
Data type |
Short description |
consumerDeviceId |
Optional |
Alphanumeric with special characters and a variable length of up to 255 characters. |
Unique token which serves as a method of fraud protection. |
In order to use the parameter consumerDeviceId you first need to generate a unique token and run a JavaScript as described in the following sections.
The request parameter consumerDeviceId is transmitted to Wirecard at the initiation of Wirecard Checkout Page or Wirecard Checkout Seamless front-end. The value of the parameter needs to be the unique token.
The unique token, identifying your consumer during the process of ordering, is thus transmitted via Javascript and via the request parameter consumerDeviceId.
Generating a unique token
To ensure that the token is really unique, it is suggested to use a hashed combination of customerId and timestamp, using for instance MD5 as hash function.
$timestamp = microtime();
$customerId = "YOUR-CUSTOMER-ID";
$consumerDeviceId = md5($customerId . "_" . $timestamp);"YOUR-CUSTOMER-ID" refers to your unique customer ID which is used to identify your online shop with the Wirecard Checkout Server.
Running JavaScript
It is recommended to output the JavaScript code as early as possible, i.e. when the consumer has entered the checkout process in the online shop or when a first item is put into the cart.
Please ensure that this script is executed one-time only per session (per customer + checkout + device).
JavaScript (example):
<script language="JavaScript">
var di = {t:'<?php echo $consumerDeviceId ?>',v:'WDWL',l:'Checkout'};
</script>
<script type="text/javascript" src="//d.ratepay.com/<?php echo $consumerDeviceId?>/di.js"></script>
<noscript>
<link rel="stylesheet" type="text/css" href="//d.ratepay.com/di.css?t=<?php echo $consumerDeviceId ?>&v=WDWL&l=Checkout">
</noscript>
<object type="application/x-shockwave-flash" data="//d.ratepay.com/WDWL/c.swf" width="0" height="0">
<param name="movie" value="//d.ratepay.com/WDWL/c.swf" />
<param name="flashvars" value="t=<?php echo $consumerDeviceId ?>&v=WDWL"/>
<param name="AllowScriptAccess" value="always"/>
</object>Optional request parameters
The optional request parameters customerStatement and orderReference are more restricted with regard to their length and allowed characters than are other general request parameters.
| Parameter | Data type | Short description |
|---|---|---|
customerStatement |
ASCII with a variable length of up to 254 characters. |
Text displayed on bank statement issued to your consumer by the financial service provider. |
orderReference |
ASCII with a variable length of up to 128 characters. |
Unique order reference ID sent from merchant to financial institution. |
Parameter basketItem to reedem vouchers
If the consumer in your online shop redeems a voucher or coupon during the payment process, the optional request parameter basketItem must be used. This parameter must contain the negative amount corresponding to the voucher or coupon value. For vouchers with percentage discount, the percentage to be deducted must first be converted into an absolute value. The total basket amount displayed to the consumer in your online shop will then show both the voucher amount and the total basket amount reduced by this voucher amount.
Back-end operations
The following information is valid for back-end operations:
For deposit and refund the parameters for the basket data are required. Please refer to the parameter description in table shopping basket parameters for further details.
Deposit
If you make partial shipments of the ordered items you can only deposit the amount for the shipped items and need to specify these items via the shopping basket parameters.
Refund
If you make a partial refund because one or several articles were sent back to you, you need to specify in the basket parameters those items that are sent back to you by your consumer. Therefore the basket amount corresponds to the refunded amount.
| The total refunded amount, including previous refunds, must be less or equal to the deposited amount. |
TransferFund
If you want to refund a certain amount to your consumer although no items are sent back to you, e.g. in case an article arrived damaged, or redeem a certain voucher value after payment was made, you have to send the optional request parameter transactionIdentifier. This special refund can only be carried out after the full amount was deposited and a day-end closing was performed.
Optional request parameter
The following request parameter needs to be specified at refunds with empty basket data.
| Parameter | Data type | Short description |
|---|---|---|
transactionIdentifier |
Enumeration |
Set to |
Examples
The following examples are intended to contribute to a better understanding of how to make a full or partial deposit and full or partial refund and using the optional request parameter transactionIdentifier.
In all examples the shopping basket of your consumer in your online shop is assumed to contain the following items:
| Quantity | Description | Number | Price per unit | Tax per unit |
|---|---|---|---|---|
1 |
Item A1 |
A001 |
EUR 10,80 |
EUR 1,80 |
2 |
Item A2 |
A002 |
EUR 14,94 |
EUR 2,49 |
1 |
Shipping |
S001 |
EUR 5,90 |
EUR 0,00 |
Examples for back-end operation "deposit"
The parameters for making a full deposit of all items in the shopping basket of your consumer would be:
| Parameter name | Value | Description |
|---|---|---|
basketItems |
3 |
3 different items in shopping basket. |
basketItem1ArticleNumber |
A001 |
|
basketItem1Quantity |
1 |
|
basketItem1Name |
Item A1 |
|
basketItem1UnitGrossAmount |
10,80 |
Gross price per item 1. |
basketItem1UnitNetAmount |
9,00 |
Net price per item 1. |
basketItem1UnitTaxAmount |
1,80 |
Tax for item 1. |
basketItem1UnitTaxRate |
20,000 |
Tax rate for item 1. |
basketItem2ArticleNumber |
A002 |
|
basketItem2Quantity |
2 |
|
basketItem2Name |
Item A2 |
|
basketItem2UnitGrossAmount |
14,94 |
Gross price per item 2. |
basketItem2UnitNetAmount |
12,45 |
Net price per item 2. |
basketItem2UnitTaxAmount |
2,49 |
Tax for item 2. |
basketItem2UnitTaxRate |
20,000 |
Tax rate for item 2. |
basketItem3ArticleNumber |
S001 |
|
basketItem3Quantity |
1 |
|
basketItem3Name |
Shipping |
|
basketItem3UnitGrossAmount |
5,90 |
Gross price per item 3. |
basketItem3UnitNetAmount |
5,90 |
Net price per item 3. |
basketItem3UnitTaxAmount |
0,00 |
Tax for item 3. |
basketItem3UnitTaxRate |
0,000 |
Tax rate for item 3. |
If you make partial shipments of the ordered items you need to make partial deposits, i.e. deposit only the amount for the shipped items specified in the basket parameters.
Based on the above information, the following example assumes that only item 1 is shipped and deposited. The shipping costs are deposited with the final shipment. The parameters for making a partial deposit of this item would be:
| Parameter name | Parameter value | Description |
|---|---|---|
basketItems |
1 |
1 item in shopping basket. |
basketItem1ArticleNumber |
A001 |
|
basketItem1Quantity |
1 |
|
basketItem1Name |
Item A1 |
|
basketItem1UnitGrossAmount |
10,80 |
Gross price per item 1. |
basketItem1UnitNetAmount |
9,00 |
Net price per item 1. |
basketItem1UnitTaxAmount |
1,80 |
Tax for item 1. |
basketItem1UnitTaxRate |
20,000 |
Tax rate for item 1. |
Examples for back-end operation "refund"
The examples for a full or partial refund are the same as for the back-end operation deposit, when making a full refund, the basket amount corresponds to the full refunded amount and when making a partial refund, you specify the items which are sent back to you by your consumer. If item number 1 is refunded and you do not refund the shipping costs, the basket is:
| Parameter name | Parameter value | Description |
|---|---|---|
basketItems |
1 |
1 item in shopping basket. |
basketItem1ArticleNumber |
A001 |
|
basketItem1Quantity |
1 |
|
basketItem1Name |
Item A1 |
|
basketItem1UnitGrossAmount |
10,80 |
Gross price per item 1. |
basketItem1UnitNetAmount |
9,00 |
Net price per item 1. |
basketItem1UnitTaxAmount |
1,80 |
Tax for item 1. |
basketItem1UnitTaxRate |
20,000 |
Tax rate for item 1. |
Example for using the parameter transactionIdentifier
If you make a refund of a certain amount without your consumer having returned any articles and after day-end closing was performed, you need to send the parameter transactionIdentifier with the value CREDIT and specify an arbitrary item with the amount to be refunded. The refunded amount does not need to correspond to any actual item price in the original basket.
| Parameter name | Parameter value | Description |
|---|---|---|
transactionIdentifier |
CREDIT |
|
basketItems |
1 |
1 item as credit. |
basketItem1ArticleNumber |
C001 |
|
basketItem1Quantity |
1 |
|
basketItem1Name |
Credit for delayed delivery. |
Credit description. |
basketItem1UnitGrossAmount |
12,00 |
Gross price per item 1. |
basketItem1UnitNetAmount |
10,00 |
Net price per item 1. |
basketItem1UnitTaxAmount |
2,00 |
Tax for item 1. |
basketItem1UnitTaxRate |
20,000 |
Tax rate for item 1. |
| The information in the following chapters is valid ONLY for merchants using RatePAY v1.6 |
Deprecated back-end operation
The following information is valid ONLY for merchants using RatePAY v1.6 and back-end operation:
For deposit the parameters for the basket information are required. If you make partial shipments of the ordered items you can only deposit the amount for the shipped items and need to specify these items via the shopping basket parameters.
Examples
The following examples are intended to contribute to a better understanding of how to make a full or partial deposit.
In all examples the shopping basket of your consumer in your online shop is assumed to contain the following items:
| Number of items | Description | Number | Price per unit | Tax per unit |
|---|---|---|---|---|
1 |
Product A1 |
A001 |
EUR 10,05 |
EUR 1,50 |
2 |
Product A2 |
A002 |
EUR 20,80 |
EUR 2,40 |
1 |
Shipping |
S001 |
EUR 5,90 |
EUR 0,00 |
Examples for back-end operation "deposit"
1. The parameters for making a full deposit of all items in the shopping basket of your consumer would be:
| Parameter name | Parameter value | Description |
|---|---|---|
basketAmount |
63,85 |
= 1 x EUR 10,05 + 1 x EUR 1,50 + 2 x EUR 20,80 + 2 x EUR 2,40 + 1 x EUR 5,90 |
basketCurrency |
EUR |
Currency as ISO code. |
basketItems |
3 |
3 different products in shopping basket. |
basketItem1ArticleNumber |
A001 |
|
basketItem1Quantity |
1 |
|
basketItem1UnitPrice |
10,05 |
Price per item. |
basketItem1Tax |
1,50 |
Total amount of tax for item 1. |
basketItem1Description |
Product A1 |
|
basketItem2ArticleNumber |
A002 |
|
basketItem2Quantity |
2 |
|
basketItem2UnitPrice |
20,80 |
Price per item. |
basketItem2Tax |
4,80 |
Total amount of tax for item 2. |
basketItem2Description |
Product A2 |
|
basketItem3ArticleNumber |
S001 |
|
basketItem3Quantity |
1 |
|
basketItem3UnitPrice |
5,90 |
Price per item. |
basketItem3Tax |
0 |
Total amount of tax for item 3. |
basketItem3Description |
Shipping |
When making a full deposit of all items, the values of the parameters basketAmount and amount are the same, in this example EUR 63,85.
2. If you make partial shipments of the ordered items you need to make partial deposits, i.e. deposit only the amount for the shipped items. For this you need to specify the items to be deposited via the basket parameters.
Based on the above information, the following examples assumes that only item 1 is shipped and needs to be deposited. The shipping costs are deposited together with the final shipment. The parameters for making a partial deposit of this item would be:
| Parameter name | Parameter value | Description |
|---|---|---|
basketAmount |
11,55 |
= 1 x EUR 10,05 + 1 x EUR 1,50 |
basketCurrency |
EUR |
Currency as ISO code. |
basketItems |
1 |
1 product in shopping basket. |
basketItem1ArticleNumber |
A001 |
|
basketItem1Quantity |
1 |
|
basketItem1UnitPrice |
10,05 |
Price per item. |
basketItem1Tax |
1,50 |
Total amount of tax for item 1. |
basketItem1Description |
Product A1 |
When making a partial deposit of items, the values of the parameters basketAmount and amount are the same, in this example EUR 10,05.