Docdata

Configure a Test Docdata Payment Module

In order to add the Docdata payment module to a project, please undertake the following steps:

Step 1: Request a test account from Docdata.

Step 2: Copy the 'Sana.Commerce.Payment.DocData.OrderApi.dll', 'Sana.Commerce.Payment.DocData.OrderApi.pdb' and 'Sana.Commerce.Payment.DocData.OrderApi.xml' files from the 'bin' folder of the Docdata add-on package to the 'Frontend/bin' folder of Sana Commerce.

Step 3: Configure the Sana Commerce frontend to use the Docdata payment module. This configuration is performed in the 'web.config' file of the Sana Commerce frontend:

• Locate the 'DocData configuration section.txt' file in the 'configuration' folder, which contains the Docdata payment module configuration;
• There are several configuration sections in this file which should be copied to the 'web.config' file of the frontend. Locate the <module name="DocData"...> section. Copy this section into the <payment-configuration> section of the 'web.config' file, so it will look as follows:

<module name="DocData" type="Sana.Commerce.Payment.DocData.OrderApi.DocDataPaymentModule, Sana.Commerce.Payment.DocData.OrderApi">
 <settings>
  <clear/>
  <add name="ResponseUseXml" value="false" isRequestParameter="false"/>
  <add name="ResponseUsePost" value="false" isRequestParameter="false"/>
  <add name="merchant_name" value="[MERCHANTNAME]" isRequestParameter="true"/>
  <add name="merchant_password" value="[MERCHANTPASSWORD]" isRequestParameter="false"/>
  <add name="days_pay_period" value="14" isRequestParameter="false"/>
  <!-- paid_status_check_mode: "quick", "safe" or "custom". Default is "quick". -->
  <add name="paid_status_check_mode" value="quick" isRequestParameter="false"/>
  <!-- maximum_orderlines_to_send: Leave empty to always send all order lines to DocData. Put some number to limit the count of order lines that are sent to DocData - this can be important when large orders will be paid using DocData. -->
  <add name="maximum_orderlines_to_send" value="100" isRequestParameter="false"/> 
  <add name="endpoint_name" value="DocData_OrderApi_test" isRequestParameter="false"/>
  <!-- PaymentPage: for production environment use 'https://secure.docdatapayments.com/ps/menu?'; otherwise, for test environment use 'https://test.docdatapayments.com/ps/menu?'. -->
  <add name="PaymentPage" value="https://test.docdatapayments.com/ps/menu?" isRequestParameter="true"/> 
  <add name="DebugDomains" value="localhost" isRequestParameter="false"/>
 </settings>
</module>

For an explanation of the configuration values, please read this chapter and the chapter 'Docdata specific configuration values' below and also 'General External Payment Method Configuration Values'.

• Locate the <binding name="DocData_OrderApi"> configuration section in the 'DocData configuration section.txt' file. Copy and paste it as a child section of the <basicHttpBinding> section which is inside the system.serviceModel/bindings node of the 'web.config' file. If this node is not present in 'web.config' file then it should be added.
  
  
• Locate two <endpoint .../> sections in the 'DocData configuration section.txt' file. These two sections are related to the binding section described above and should be copied as the child nodes to the system.serviceModel/client node.

The configuration of the binding and endpoints should look as follows:

<system.serviceModel>
  <bindings>
    <basicHttpBinding>
      <binding name="DocData_OrderApi">
        <security mode="Transport" />
      </binding>
    </basicHttpBinding>
  </bindings>
  <client>            
    <endpoint name="DocData_OrderApi_test" address="https://test.docdatapayments.com/ps/services/paymentservice/1_1" binding="basicHttpBinding" bindingConfiguration="DocData_OrderApi" contract="PaymentServiceSOAP" />
    <endpoint name="DocData_OrderApi_production" address="https://secure.docdatapayments.com/ps/services/paymentservice/1_1" binding="basicHttpBinding" bindingConfiguration="DocData_OrderApi" contract="PaymentServiceSOAP" />
  </client>
</system.serviceModel>

• Note, that these settings in the example above are the standard WCF configuration settings. Some other settings may be already present in the system.serviceModel section of the 'web.config' file. Therefore, the Docdata add-on settings should be added to the existing settings in the 'web.config' file. For more information on how WCF services are configured, see 'Configuring Services' in the MSDN Library.

Step 4: Configure the Docdata payment methods. To do this execute the 'ConfigureDocDataInDB.sql' SQL script on the Sana Commerce database. You can find the script in the 'scripts' folder of the Docdata package.

Before running the script check the value of the '@siteId' variable and change it if needed to match the appropriate website identifier and check whether the currency is correct.

The 'ConfigureDocDataInDB.sql' SQL script adds the 'VISA', 'Master card' and 'Ideal' payment methods.
These payment methods will be available for all countries configured in the system except 'Ideal' which is available only in the Netherlands. No translations for the payment methods will be set by this script - this should be done manually.

After the script has been executed, all fields should be checked for the correct values. By default the script makes these new payment methods active by setting the 'Active' field value to 'true' in the database. Therefore these payment methods will be immediately available on the frontend.
Keep in mind that this script assigns all three payment methods to the same payment profile. In the Sana Commerce database check that the name of the payment profile in the 'PaymentMethods' table matches the name of the payment profile as configured in the Docdata backoffice.

When the script has been executed, the Docdata payment methods can be seen in the Sana Commerce backoffice > Settings > Payment methods. Here you can manage the payment methods: edit or remove the existing payment methods or create and configure any other payment methods. If you need to use any other payment methods that are supported by the installed payment provider you can create and configure them on the 'Payment methods' page in the Sana Commerce backoffice. For more information about management of the payment methods in the Sana Commerce backoffice, see 'Payment methods'.

Step 5: In the 'web.config' file of the Sana Commerce frontend modify the merchant_name and merchant_password to the merchant name and password you have received from Docdata. (Note that the password differs from the password used for logging into the Docdata backoffice.)

Step 6: Log into the Docdata backoffice and configure or verify payment profiles. This can be done under 'Settings > Payment method names'. Each payment method must be configured with a profile. You can find the configured profiles in the following place in the Docdata backoffice (marked by the red box):

Configuring Payment Methods in the Docdata Backoffice

Step 7: Check in the Sana Commerce backoffice (Settings > Payment methods) that the correct values are set in the 'PSP code' and 'PSP profile name' fields for the Docdata payment methods. On the screenshot below you can see an example of the 'Visa' Docdata payment method configured:

The 'Visa' Docdata Payment Method in the Sana Commerce Backoffice

Note, that the values of the 'PSP code' field should match the identifiers of the appropriate payment methods in the Docdata backoffice. Also, the values of the 'PSP profile name' field should match the names of the appropriate payment profiles in the Docdata backoffice (see previous screenshot also).

In order to test the payment flow in the development environment, there are two possible scenarios:

• The development machine/server cannot be accessed externally by the Docdata server (most common scenario): in this case add all domains used by the development server to the 'DebugDomains' setting in the 'web.config' file. Multiple domains can be separated by the ',' character. This will make possible to test the whole flow of a test payment, when the confirm page cannot be reached by Docdata. This setting is for debugging purposes only and should not be used in a production environment.
  
  
• The development machine/server can be accessed. In this case you can configure Docdata to test the payment flow. Remove the 'DebugDomains' setting from the payment module configuration. In the Docdata backoffice configure the correct URLs under 'Settings > View/Edit Merchant Profile > URL':
  
  
  Configuring URL Settings

Configure URLs in the following way:

Step 8: Find the 'files' folder, where the Docdata payment method icons are stored. Copy the 'files' folder to 'Frontend\content\'. These icons will be displayed on the frontend in the payment method selection control.

Step 9: When all the changes are made, in the Sana Commerce backoffice click 'Refresh site cache'.

Step 10: Test the payment/checkout flow to see if everything works fine, using the newly configured payment methods and the correct payment statuses that are set.

It may be the case that on the payment menu page of Docdata you will face with the incorrect positioning of product images as shown on the screenshot below:

Payment Menu Page of Docdata

On the screenshot above you can see two incorrectly positioned image placeholders with the 'No image available' text on them. If you have encountered the problem with positioning of product images on the payment menu page of Docdata:

• Open the Docdata backoffice and click: Settings > Edit Look and Feel.
• In the large editable text box add the following lines (this text box may already contain some lines of text - these are the CSS stylesheets which are applied by Docdata to the payment menu page):

productImage {
    height: 50px;
}

• Click 'Store CSS' at the bottom of the page to save your changes.
• Now when this fix has been applied the payment menu page of Docdata should look correctly:

• In this fix the height of images is set to 50 pixels, but you can set it to any value suitable for your project.