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:invoice:wirecard [2016-05-25 09:54]
trh created
payment_methods:invoice:wirecard [2020-10-28 07:31] (current)
Line 16: 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:invoice_by_wirecard: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:wirecard:state_diagram|order flow diagram]].
  
 ===== Required request parameters ===== ===== Required request parameters =====
  
-For payment method Invoice by Wirecard 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 ''Invoice by Wirecard'' 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 ''Invoice by Wirecard''.
 +
 +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 30: Line 87:
 | 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. | | 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 50 characters.  | Unique order reference ID sent from merchant to financial institution. | | orderReference    | ASCII with a variable length of up to 50 characters.  | Unique order reference ID sent from merchant to financial institution. |
 +| consumerMerchantCrmId | Alphanumeric with a variable length of up to 50 characters. | Unique ID identifying the consumer of your online shop, e.g. from your CRM system. The parameter must not be a human readable e-mail address. |
 +
 +==== Parameter consumerMerchantCrmId ====
 +
 +The parameter is understood as unique ID identifying the consumer in your online shop, e.g. using data from your Customer Relationship Management (CRM) system. However, ''Invoice by Wirecard'' must not receive any data or information that allow to draw any conclusions on the final consumer. 
 +
 +Please note that Invoice by Wirecard refers to the new parameter as ''Merchant-Consumer-ID'' which is an internal customer identifier of the
 +merchant system. In Wirecard interfaces and documentation ''consumerMerchantCrmId'' is used.
 +
 +The parameter ''consumerMerchantCrmId'' may be set by the merchant using **Wirecard Checkout Page** or **Wirecard Checkout Seamless** for initiations via WCP, WCP server-to-server initiations and WCS front-end initiation. 
 +
 +Also, the parameter ''consumerMerchantCrmId'' is part of the fingerprint. 
 +
  
  
Line 36: Line 106:
 If the consumer in your online shop redeems a voucher or coupon during the payment process, a basket item must be added. This item **contains 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, a basket item must be added. This item **contains 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.
  
 +===== Additional response parameters =====
  
 +When using this payment method in your online shop, we will return additional parameters to your online shop. These parameters are specific to this payment method and are only returned when your consumer selects this payment method in your online shop.
 +
 +^ Parameter ^ State ^ Data type ^ Short description ^
 +| [[:response_parameters#additionally_for_successful_payments|gatewayReferenceNumber]] |  Success | Alphanumeric with special characters and a variable length of up to 255. \\ E.g. ''440208fa-6057-4c1f-8034-732d6050395c''. | Technical reference number of the payment processing at Wirecard. |
 +| [[:response_parameters#additionally_for_successful_payments|providerReferenceNumber]] |  Success | Alphanumeric with special characters and a variable length of up to 255. \\ E.g. ''DG0511345U8''. | Reference number of the invoice.   |
 ===== Back-end operations ===== ===== Back-end operations =====
  
-If you make **partial shipments** of the ordered items you can only [[:back-end_operations:transaction-based:deposit|deposit]] the amount for the shipped items and need to specify these items via the [[:request_parameters#Shopping_basket_data|shopping basket parameters]].+The following information is valid for back-end operations:
  
-If you make a **[[:back-end_operations:transaction-based:refund|partial refund]]** because one or several articles were sent back to you, you need to specify in the basket parameters those items your consumer sent back to you.  +  * [[:back-end_operations:transaction-based:approvereversal|approveReversal]] 
- +  [[:back-end_operations:transaction-based:deposit|deposit]] 
-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. +  * [[: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. 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>  <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 ==== ==== Optional request parameter ====
Line 64: Line 151:
  
 ^ Quantity  ^ Description  ^ Number ^ Price per unit ^ Tax per unit ^ ^ Quantity  ^ Description  ^ Number ^ Price per unit ^ Tax per unit ^
-| 1         | Product A1   | A001   | EUR 10,80      | EUR 1,80     | +| 1         | Item A1      | A001   | EUR 10,80      | EUR 1,80     | 
-| 2         | Product A2   | A002   | EUR 14,94      | EUR 2,49     |+| 2         | Item A2      | A002   | EUR 14,94      | EUR 2,49     |
 | 1         | Shipping     | S001   | EUR 5,90       | EUR 0,00     | | 1         | Shipping     | S001   | EUR 5,90       | EUR 0,00     |
  
Line 72: Line 159:
 The parameters for making a **full deposit** of all items in the shopping basket of your consumer would be: The parameters for making a **full deposit** of all items in the shopping basket of your consumer would be:
  
-^Parameter name            ^  Value       ^Description                                    +^Parameter name            ^  Value     ^Description                          
-|basketItems               |  3           |3 different products in shopping basket.       +|basketItems               |  3         |3 different items in shopping basket.| 
-|basketItem1ArticleNumber  |  A001                                                      +|basketItem1ArticleNumber  |  A001                                          
-|basketItem1Quantity       |  1                                                         +|basketItem1Quantity       |  1                                             
-|basketItem1Name           |  Product A1                                                +|basketItem1Name           |  Item A1                                       
-|basketItem1UnitGrossAmount|  10,80       |Gross price per item 1.                        +|basketItem1UnitGrossAmount|  10,80     |Gross price per item 1.              
-|basketItem1UnitNetAmount  |  9,00        |Net price per item 1.                          +|basketItem1UnitNetAmount  |  9,00      |Net price per item 1.                
-|basketItem1UnitTaxAmount  |  1,80        |Tax for item 1.                                +|basketItem1UnitTaxAmount  |  1,80      |Tax for item 1.                      
-|basketItem1UnitTaxRate    |  20,000      |Tax rate for item 1.                           +|basketItem1UnitTaxRate    |  20,000    |Tax rate for item 1.                 
-|basketItem2ArticleNumber  |  A002                                                      +|basketItem2ArticleNumber  |  A002                                          
-|basketItem2Quantity       |  2                                                         +|basketItem2Quantity       |  2                                             
-|basketItem2Name           |  Product A2                                                +|basketItem2Name           |  Item A2                                       
-|basketItem2UnitGrossAmount|  14,94       |Gross price per item 2.                        +|basketItem2UnitGrossAmount|  14,94     |Gross price per item 2.              
-|basketItem2UnitNetAmount  |  12,45       |Net price per item 2.                          +|basketItem2UnitNetAmount  |  12,45     |Net price per item 2.                
-|basketItem2UnitTaxAmount  |  2,49        |Tax for item 2.                                +|basketItem2UnitTaxAmount  |  2,49      |Tax for item 2.                      
-|basketItem2UnitTaxRate    |  20,000      |Tax rate for item 2.                           +|basketItem2UnitTaxRate    |  20,000    |Tax rate for item 2.                 
-|basketItem3ArticleNumber  |  S001                                                      +|basketItem3ArticleNumber  |  S001                                          
-|basketItem3Quantity       |  1                                                         +|basketItem3Quantity       |  1                                             
-|basketItem3Name           |  Shipping                                                  +|basketItem3Name           |  Shipping                                      
-|basketItem3UnitGrossAmount|  5,90        |Gross price per item 3.                        +|basketItem3UnitGrossAmount|  5,90      |Gross price per item 3.              
-|basketItem3UnitNetAmount  |  5,90        |Net price per item 3.                          +|basketItem3UnitNetAmount  |  5,90      |Net price per item 3.                
-|basketItem3UnitTaxAmount  |  0,00        |Tax for item 3.                                +|basketItem3UnitTaxAmount  |  0,00      |Tax for item 3.                      
-|basketItem3UnitTaxRate    |  0,000       |Tax rate for item 3.                           |+|basketItem3UnitTaxRate    |  0,000     |Tax rate for item 3.                 |
  
  
Line 101: Line 188:
 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: 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 ^ +^ Parameter name             ^  Parameter value  ^ Description                
-| basketItems                |  3           3 different products in shopping basket. | +| basketItems                |  1                1 item in shopping basket. | 
-| basketItem1ArticleNumber   |  A001                                                 +| basketItem1ArticleNumber   |  A001                                        
-| basketItem1Quantity        |  1                                                    +| basketItem1Quantity        |  1                                           
-| basketItem1Name            |  Product A1                                           +| basketItem1Name            |  Item A1                                     
-| basketItem1UnitGrossAmount |  10,80       | Gross price per item 1.                  +| basketItem1UnitGrossAmount |  10,80            | Gross price per item 1.    
-| basketItem1UnitNetAmount   |  9,00        | Net price per item 1.                    +| basketItem1UnitNetAmount   |  9,00             | Net price per item 1.      
-| basketItem1UnitTaxAmount   |  1,80        | Tax for item 1.                          +| basketItem1UnitTaxAmount   |  1,80             | Tax for item 1.            
-| basketItem1UnitTaxRate     |  20,000      | Tax rate for item 1.                     |+| basketItem1UnitTaxRate     |  20,000           | Tax rate for item 1.       | 
  
 === Examples for back-end operation "refund" === === Examples for back-end operation "refund" ===
  
-The examples for a **full or partial refund** are the same as for the back-end operation ''deposit'', e.g. when making a full refund, you have to specify all items. When making a partial refund, you only have to specify the items for which you make a 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 === === Example for using the parameter transactionIdentifier ===
Line 119: Line 217:
 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. 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      +^ Parameter name            ^  Parameter value  ^ Description                   
-basketItem1ArticleNumber  |  A001             | +transactionIdentifier      |  CREDIT           |                              | 
-| basketItem1Quantity       |  1                |  +| basketItems                |  1                | 1 item as credit.            | 
-basketItem1UnitPrice      |  14,00            | Refunded amount. | +| basketItem1ArticleNumber   |  C001             |                              
-basketItem1Description    |  Credit           |+| 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.         |
  

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.