Enabling punch-out payment

You can enable punch-out payments in you store by using the SimplePunchout payment plug-in. When shoppers check out, payment is completed through a third-party payment service provider.

About this task

The following procedure includes sample files that set up a payment system called TestPunchoutSystem. You can modify the sample names as needed.
HCL Commerce Version or later
Note: The encryptByMD5 method for PunchoutPaymentUtil is deprecated since IBM Websphere Commerce Version 7 and is now removed. You must customize the code if you are using the same method.


  1. Download and extract the following payments.zip file to the workspace_dir/WC/xml/config/ directory.
    The payments.zip package includes sample files to set up the payment method configuration, payment mapping, and payment system plug-in mapping. This will set up:
    • The sample payment system TestPunchoutSystem, which maps to the payment plug-in CustomizationPlugin.
    • The sample payment method configuration TestPunchout, which maps to the payment system TestPunchoutSystem.
    • Mapping from the payment method TestPunchout to payment method configuration TestPunchout.
    Ensure that after extraction, your environment contains the following directory structure.
    • workspace_dir/WC/xml/config/payments/edp
    • workspace_dir/WC/xml/config/payments/ppc
    You can change the names of the payment system, the payment methods, and the payment method configurations by updating the files in the edp and ppc directories. If you change the name of the payment system, ensure that you also update the names in the sample CSV files in the proceeding steps to match your new payment system.
  2. Enable the punch-out payment option in your store.
    1. Log on to the Management Center.
    2. Select Store Management from the main menu.
    3. Select Stores from the left navigation frame.
    4. Select the store that you want to configure.
    5. In the Checkout page, select the Punch-out payment check box.
  3. Add the punch-out payment method to the database.
    1. Insert the payment policy for TestPunchout into the POLICY table.
      Note: Ensure that you update <UniquePolicyId>> and <StoreIdentifier> in the following statement.
      insert into policy (policy_id, policyname, policytype_id, storeent_id, properties) values (<UniquePolicyId>, 'TestPunchout', 'Payment', (select storeent_id from storeent where IDENTIFIER = '<StoreIdentifier>), 'attrPageName=TestPunchout&paymentConfigurationId=default&display=true&compatibleMode=false&uniqueKey=piId&PIKey=piId&punchoutPayment=true');
    2. Insert the translated descriptions for the payment policy into the POLICYDESC table. You can insert only English descriptions.
      insert into policydesc values(<UniquePolicyId>, -1, 'TestPunchout', 'TestPunchout', null, null, null);
    3. To use the payment plug-in controller, set up the business policy commands for the new policy.
      insert into policycmd values(<UniquePolicyId>, 'com.ibm.commerce.payment.actions.commands.DoPaymentActionsPolicyCmdImpl', null, null);
      insert into policycmd values(<UniquePolicyId>, 'com.ibm.commerce.payment.actions.commands.EditPaymentInstructionPolicyCmdImpl', null, null);
      insert into policycmd values(<UniquePolicyId>, 'com.ibm.commerce.payment.actions.commands.QueryPaymentsInfoPolicyCmdImpl', null, null);
  4. Implement extension code for the following extension points to integrate with the third party payment service provider.
    • approve_payment
    • get_punchout_url
    • process_punchout_response
    For more information about the extension points, see Punch-out payment extension points.
  5. Register the extension code that you created for the three extension points into the database.
    1. Create input files by using the CmdReg and UEConfig keywords.
      The following input files are provided as samples that you can use and edit as needed.
      • TestPunchoutCmdReg.csv

        This file is used to load the data to register the command for the extension. Notice that the InterfaceName column contains the commands that are extended plus the name of the payment method. For example, com.ibm.commerce.payment.task.commands.GetPunchoutURLCmd+TestPunchout. If you changed the name of the payment method from the payments.zip, ensure that you update the CSV file with the new payment method name.

      • TestPunchoutUEConfig.csv
        This file is used to configure the extension, such as to define the URL path and any properties or filters for the extension. The sample defines the following:
        • The sample extension point configuration for approve_payment, which maps to POST extension/payment/approve_payment on the Customization server.
        • The sample extension point configuration for get_punchout_url, which maps to POST extension/payment/get_punchout_url on the Customization server.
        • The sample extension point configuration for process_punchout_response, which maps to POST extension/payment/process_punchout_response on the Customization server.
    2. Save the input files to the WCDE_installdir/samples/DataLoad/xC directory.
    3. Load the CmdReg and UEConfig files to the database.
  6. Test the payment method in your store.
    1. Add an item to the shopping cart in your store.
    2. Select TestPunchout as the payment method when you check out.

      Your extension code for approve_payment is called when the order is submitted. If the state of the financial transaction is set to 1 (pending) by your extension code, a Pay button is displayed.

    3. Click Pay.

      Your extension code for get_punchout_url is called when you click Pay and a pop-up window to the URL (returned by your extension code) is displayed.

    4. Complete the payment method within the pop-up window.

      Your extension code for process_punchout_response is called when POST cart/@self/payment_instruction/callback is called.

What to do next

To enable in your production environment:
  • Enable the Punch-out payment option in the Management Center tool of your production environment.
  • Repeat the SQL statements against your production database.
  • Check in the source code to your source code repository for the CI/CD pipeline to package and deploy the customizations.
  • Load your dataload CSV files to your production environment.