PIAdd URL

This URL adds a new payment method to an order. This command calls the EditCmd task command to add the payment method.

URL

PIAdd

Controller command

com.ibm.commerce.edp.commands.PIAddCmd

Implementation class

com.ibm.commerce.edp.commands.PIAddCmdImpl

Commands called

AddUnboundPITaskCmd

EditCmd

URL structure

http://host_name/path/
The fully qualified name of your HCL Commerce Server and the configuration path.

orderId
Required: The identifier of the order to which the payment method is to be added.
URL
Required: The URL to be redirected when the command completes successfully.
piAmount
Required: The amount in the order currency to be used for this payment method. The format of this number must fit the rules for a java.math.BigDecimal object. The number must use a period for a decimal place.
policyId
The payment policy identifier. It is the primary key of the payment business policy table. (Table POLICY with column policytype_id = 'Payment). See Payment methods for a list of methods supported by HCL Commerce (payment methods are configurable).
  • If this parameter is missing, then payMethodId is required, and this command tries to get the policy identifier from the business policy table via the policy name as payMethodId.
payMethodId
Optional: The payment method name. It is the policy name of the payment business policy table. (Table POLICY with column policytype_id = 'Payment'). If policyId is passed in, this parameter is not required since this command always sets it as the policy name from business policy table via the policyId.
(At least one of the two parameters policyId and payMethodId should be passed in. If both of them are passed in, policyId will have priority over payMethodId.)
purchaseorder_id
Optional: The purchase order number specified to the order. This parameter is optional, if it is set, the value of the purchase order number will send back to the response properties to be displayed in the page.
errorViewName
Optional: The view name which is redirected to when the execution fails. If this parameter is provided, the default error view name is PaymentInstructionErrorView.
billing_address_id
Optional: The billing address identifier.
  • If all of the parameters billto_firstname, billto_lastname, billto_address1, billto_city, billto_stateprovince are passed in, those parameters will be used as the billing address protocol data, and the billing_address_id parameter will not be used. Otherwise, this command will get the billing address protocol data from the address related table(s) in HCL Commerce according to billing_address_id.

paymentTCId
Optional: The payment Term&Condition identifier for this payment instruction. This parameter is used by the business customer.
valueFromPaymentTC
Optional: The flag to indicate whether the payment protocol data should be extracted from the payment Term&Condition identified by paymentTCId parameter and ignore any protocol data passed in the request properties. The values include true and false, the default value is false.
valueFromProfileOrder
Optional: The flag to indicate whether the payment protocol data should be extracted from the user's quick checkout profile and ignore any protocol data passed in the request properties. The values are Y or N. The default value is N.
protocolData
Optional: Additional name-value pairs separated by an ampersand (&) that will be passed to the payment plug-in or payment processor as additional data required by that payment protocol. For example, for a credit card, &cc_brand=AMEX. Note that protocolData is not the parameter directly passed in, instead it just contains the name-value pairs of protocol data of current payment instruction. Any parameters except for purchaseorder_id will be put into protocolData.

Example 1

The following example adds the AMEX credit card payment method to order 112233, for an amount of 105.50 USD, with protocol data values for the credit card account, brand, and expiration. The assumption is that the order already exists and is using USD as the currency.


http://host_name/webapp/wcs/stores/servlet/PIAdd?orderId=112233&piAmount=105.50
&policyId=-9803&URL=/
     &cc_nameoncard=Jane+Smith
     &billto_address1=4911+Sunnybrook+Dr
     &billto_city=Beverly+Hills
     &billto_stateprovide=CA
     &billto_zipcode=90210
     &billto_country=USA
     &account=account_value
     &cc_brand=AMEX
     &expire_month=09
     &expire_year=2005
     &billing_address_id=10001000006363
     &errorViewName=DoPaymentErrorView

Example 2

The following example adds the electronic check payment method to order 112233, for an amount of 300 USD, and supplies the check routing number required by that payment method to perform the transaction. The assumption is that the order already exists and is using USD as the currency.


http://host_name/webapp/wcs/stores/servlet/PIAdd?orderId=112233&piAmount=300
&policyId=-9802&URL=/
     &account=account_value
     &check_number=1159
     &check_routing_number=123456789
     &billing_address_id=10001000006363
     &errorViewName=DoPaymentErrorView

Behavior

Check if the order is locked by the current CSR. If the order is not locked and called by a CSR, or if it is locked by another CSR, an exception is thrown

If the payment instruction to be added is unbound (An unbound payment instruction for the order only has the information for the payment method and the payment policy):
  • Call AddUnboundPITaskCmd (EDP command) to add the unbound payment instruction
Otherwise:
  • Call EditCmd (EDP command) to add the payment instruction
  • Examine the result of EditCmd and throw exception if the result is null or if there is error in the results

Exception conditions

  • ECSystemException
  • ECApplicationException