Menu

User Tools

Create PDF

Site Tools


Differences

This shows you the differences between two versions of the page.

Go

Link to this comparison view

payment_methods:installment:ratepay [2016-05-25 09:57]
trh created
payment_methods:installment:ratepay [2020-09-15 12:54] (current)
Line 1: Line 1:
-====== RatePAY: Installment ======+====== Installment: RatePAY ======
  
 ===== General information ===== ===== General information =====
- 
- 
- 
  
 To integrate and offer the payment method installment for your consumers in your online shop you need to fulfill some important requirements: To integrate and offer the payment method installment for your consumers in your online shop you need to fulfill some important requirements:
Line 19: Line 16:
 ===== Order flow diagram ===== ===== 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 [[payment_methods:ratepay:state_diagram|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 [[payment_methods:invoice:ratepay:state_diagram|order flow diagram]].
  
  
 ===== Required request parameters ===== ===== 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 [[:request_parameters#Consumer_billing_data|Consumer billing data]] and [[:request_parameters#Shopping_basket_data|Shopping basket data]].+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 [[:request_parameters#Consumer_billing_data|Consumer billing data]] and [[:request_parameters#Shopping_basket_data|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**.
 +
 +^    [[:request_parameters#shopping_basket_data|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.
 +
 +<code java>
 +
 +$timestamp = microtime();
 +$customerId = "YOUR-CUSTOMER-ID";
 +$consumerDeviceId = md5($customerId . "_" . $timestamp);
 +</code>
 +
 +''"YOUR-CUSTOMER-ID"'' refers to your unique [[:request_parameters#customerid|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):
 +
 +<code java>
 +<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> 
 +</code>
  
 ===== Optional request parameters ===== ===== Optional request parameters =====
Line 39: Line 93:
 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. 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 operation ===== 
  
-The following information is valid for the back-end operation:+===== Back-end operations ===== 
 + 
 +The following information is valid for back-end operations: 
 + 
 +  * [[:back-end_operations:transaction-based:approvereversal|approveReversal]] 
 +  * [[:back-end_operations:transaction-based:deposit|deposit]] 
 +  * [[:back-end_operations:transaction-based:refund|refund]] 
 +  * [[:back-end_operations:transaction-based:transferfund|transferFund]] 
 + 
 +For [[:back-end_operations:transaction-based:deposit|deposit]] and [[:back-end_operations:transaction-based:refund|refund]] the parameters for the **''basket'' data are required**. Please refer to the parameter description in table [[:request_parameters#Shopping_basket_data|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 [[:request_parameters#Shopping_basket_data|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. 
 + 
 +<note>The total refunded amount, including previous refunds, must be less or equal to the deposited amount.</note>  
 + 
 +==== 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 **''[[#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 ''CREDIT'' to refund your consumer a certain amount without having returned any articles. | 
 + 
 + 
 +==== 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.         | 
 + 
 + 
 +<note important>The information in the following chapters is valid ONLY for **merchants using RatePAY v1.6**</note> 
 + 
 +===== Deprecated back-end operation ===== 
 + 
 +The following information is valid ONLY for **merchants using RatePAY v1.6** and back-end operation:
  
   * [[:back-end_operations:functional_wcp_wcs:transaction-based_operations:deposit|deposit]]   * [[:back-end_operations:functional_wcp_wcs:transaction-based_operations:deposit|deposit]]

This website uses cookies to deliver the best service to you. By continuing to browse the site, you are agreeing to our use of cookies.