6.0.0.2 Add a payment instruction
This service adds a payment instruction to a shopping cart. Only one payment method can be used. Before using the service, the client must have a reference to the order facade client, and a shopping cart must exist on the server side.
Usage scenario
- The client calls the order facade client method addPaymentInstruction() with the following parameters: (payMethodId, piAmount, paymentTCId, billing_address_id, protocol data such as account,expire_year and so on).
- OrderFacadeClient composes an SDO and calls the ChangeOrder service using the action code Create and XPath query /Order/OrderPaymentInfo/PaymentInstruction.
- The payment instruction is added in the WebSphere Commerce Server.
- The order component responds with a RespondOrder BOD with an orderId and the PaymentInstructionID. The marked protocol data is in the PaymentInstructionType Object. The RespondOrder BOD contains the order ID and the payment instruction ID.
Request
Request ChangeOrder business object document (BOD). Schema Order-DataObjects/xsd/OAGIS/9.0/Overlays/IBM/Commerce/BODs/ChangeOrder.xsd Service data object com.ibm.commerce.order.facade.datatypes.ChangeOrderType
Sample request BOD
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soapenv:Header /> <soapenv:Body> <_ord:ChangeOrder xmlns:_ord="http://www.ibm.com/xmlns/prod/commerce/9/order" xmlns:_wcf="http://www.ibm.com/xmlns/prod/commerce/9/foundation" xmlns:oa="http://www.openapplications.org/oagis/9" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <oa:ApplicationArea xsi:type="_wcf:ApplicationAreaType"> <oa:CreationDateTime> 2007-01-26T19:15:10.812Z </oa:CreationDateTime> <oa:BODID> 7c206400-ad2e-11db-832d-831645b86890 </oa:BODID> </oa:ApplicationArea> <_ord:DataArea> <oa:Change> <oa:ActionCriteria> <oa:ActionExpression actionCode="Create" expressionLanguage="wc:XPath"> /Order/OrderPaymentInfo/PaymentInstruction </oa:ActionExpression> </oa:ActionCriteria> </oa:Change> <_ord:Order> <_ord:OrderIdentifier> <_wcf:UniqueID>.</_wcf:UniqueID> </_ord:OrderIdentifier> <_ord:OrderPaymentInfo> <_ord:PaymentInstruction> <_ord:BillingAddress> <_wcf:ContactInfoIdentifier> <_wcf:UniqueID>11301</_wcf:UniqueID> </_wcf:ContactInfoIdentifier> </_ord:BillingAddress> <_ord:Amount>500</_ord:Amount> <_ord:PaymentMethod> <_ord:PaymentMethodName> VISA </_ord:PaymentMethodName> </_ord:PaymentMethod> <_ord:ProtocolData name="expire_year"> 2009 </_ord:ProtocolData> <_ord:ProtocolData name="account"> 4111111111111111 </_ord:ProtocolData> <_ord:ProtocolData name="billing_address_id"> 11301 </_ord:ProtocolData> <_ord:ProtocolData name="expire_month"> 12 </_ord:ProtocolData> <_ord:ProtocolData name="cc_brand"> VISA </_ord:ProtocolData> <_ord:ProtocolData name="payMethodId"> VISA </_ord:ProtocolData> </_ord:PaymentInstruction> </_ord:OrderPaymentInfo> </_ord:Order> </_ord:DataArea> </_ord:ChangeOrder> </soapenv:Body> </soapenv:Envelope>
Response
The response is a RespondOrder BOD with order ID and payment instruction ID, and a payment instruction is added.
Response BOD RespondOrder Schema Order-DataObjects/xsd/OAGIS/9.0/Overlays/IBM/Commerce/BODs/RespondOrder.xsd Service data object com.ibm.commerce.order.facade.datatypes.RespondOrderType The response contains the following information:
/Order/OrderIdentifier/UniqueID /Order/OrderPaymentInfo/PaymentInstruction/UniqueID
Sample response BOD
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <ance "> <soapenv:Header /> <soapenv:Body> <_ord:ChangeOrder xmlns:_ord="http://www.ibm.com/xmlns/prod/commerce/9/order" xmlns:_wcf="http://www.ibm.com/xmlns/prod/commerce/9/foundation" xmlns:oa="http://www.openapplications.org/oagis/9" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <oa:ApplicationArea xsi:type="_wcf:ApplicationAreaType"> <oa:CreationDateTime> 2007-01-26T19:16:14.734Z </oa:CreationDateTime> <oa:BODID> a23a1d20-ad2e-11db-832d-831645b86890 </oa:BODID> </oa:ApplicationArea> <_ord:DataArea> <oa:Change> <oa:ActionCriteria> <oa:ActionExpression actionCode="Update" expressionLanguage="wc:XPath"> /Order/OrderPaymentInfo/PaymentInstruction </oa:ActionExpression> </oa:ActionCriteria> </oa:Change> <_ord:Order> <_ord:OrderIdentifier> <_wcf:UniqueID>.</_wcf:UniqueID> </_ord:OrderIdentifier> <_ord:OrderPaymentInfo> <_ord:PaymentInstruction> <_ord:UniqueID>31535</_ord:UniqueID> </_ord:PaymentInstruction> </_ord:OrderPaymentInfo> </_ord:Order> </_ord:DataArea> </_ord:ChangeOrder> </soapenv:Body> </soapenv:Envelope>;
Exceptions
If there is something wrong with the parameter, the order component does not add the payment instruction. The Order component responds with the RespondOrder BOD with a ChangeStatus, which indicates that the action failed.
The exception conditions are the same as for the PIAdd URL.
Customization
The following extensions are supported:
- Extend the methods buildOrderIdentifier and buildPaymentInstruction of OrderFacadeClient to handle the input parameters.
- Extend the command RespondOrderWithPIBuildCmdImpl to populate information into the response.
- Customize the messaging mapping file ChangeOrderSOIBODMapping.xml by find this section
<Command CommandName="com.ibm.commerce.edp.commands.PIAddCmd" Condition='actionCode="Create" AND actionExpression="/Order/OrderPaymentInfo/PaymentInstruction"'>Replace the RespondOrderWithPIBuildCmdImpl command with the new command that extends RespondOrderWithPIBuildCmdImpl.
Related concepts
Service Data Objects (SDO)
Related Reference
WebSphere Commerce services
Order services