Payment processing service

The payment processing service is an inbound Web service responsible for processing online financial transactions such as payment authorizations and payment captures. This inbound Web service is typically called by an external system in integrated solutions where the external system has no direct integration with payment service providers, but relies on the WebSphere Commerce payment processing system and its payment plug-ins to process online financial transactions.

Typical use cases

Payment authorization against a credit card not yet captured as a payment instruction
Payment capture with payment already authorized in a prior financial transaction

Endpoint URL and operation

The default endpoint URL of this inbound Web service is https:// hostname:8000/webapp/wcs/services/PaymentServices. The operation of this inbound Web service is ProcessFinancialTransaction, with the ProcessFinancialTransaction BOD as request and the AcknowledgeFinancialTransaction BOD as response.

Request

Requests to this inbound Web service are in the form of ProcessFinancialTransaction BODs. They will be mapped to the PaymentProcessFinancialTransaction command and should contain the following information:


XPath*	Type	Maps to the following command parameter	Description	Required
`DataArea/Process/ActionCriteria/` `ActionExpression/@actionCode`	string	`actionCode`	The action code. Must be " `Approve`", "Deposit", "ApproveAndDeposit", "Credit", "ReverseApproval", "ReverseDeposit" or "ReverseCredit".	Y
`DataArea/FinancialTransaction@type`	string	`actionCode`	Must be the same as the action code.	Y
`DataArea/FinancialTransaction/` `RequestedAmount`	decimal	`amount`	The requested amount.	Y
`DataArea/FinancialTransaction/` `RequestedAmount@currency`	string	`currency`	Currency of the requested amount.	Y
`DataArea/FinancialTransaction/Payment/` `PaymentIdentifier/PaymentID`	long	`paymentId`	Payment ID of the WebSphere Commerce payment to be associated with the financial transaction. A new payment will be created if paymentID is not specified. Optional for action codes " `Approve`" and " `ApproveAndDeposit`", required for " `Deposit`", " `ReverseApproval`" and " `ReverseDeposit`".	N
`DataArea/FinancialTransaction/Credit/` `CreditIdentifier/CreditID`	long	`creditId`	Credit ID of the WebSphere Commerce credit to be associated with the financial transaction. A new credit will be created if creditID is not specified. Optional for action codes " `Credit`", required for " `ReverseCredit`".	N
`DataArea/FinancialTransaction/*/` `PaymentInstruction/PaymentInstructionIdentifier/` `PaymentInstructionID`	long	`paymentInstructionId`	ID of the WebSphere Commerce payment instruction to be associated with the financial transaction and payment (or credit). A new payment and payment instruction will be created from the information provided if neither payment ID (or credit ID) nor payment instruction ID is specified.	N
`DataArea/FinancialTransaction/*/` `PaymentInstruction/StoreID`	int	`storeId`	WebSphere Commerce store ID of the payment instruction. Required if creating a new payment instruction.	N
`DataArea/FinancialTransaction/*/` `PaymentInstruction/OrderIdentifier/OrderID`	long	`orderId`	WebSphere Commerce order ID of the payment instruction, if applicable. Used if creating a new payment instruction.	N
`DataArea/FinancialTransaction/*/` `PaymentInstruction/PaymentConfigurationID`	string	`paymentConfigurationGroupId`	The WebSphere Commerce payment configuration ID. Should be set to "default" unless otherwise indicated. Required if creating a new payment instruction.	N
`DataArea/FinancialTransaction/*/` `PaymentInstruction/PaymentSystemName`	string	`paymentSystemName`	Name of the WebSphere Commerce payment system to be associated with the payment instruction, for example, "SimpleOffline". Required if creating a new payment instruction and the payment method name is not specified.	N
`DataArea/FinancialTransaction/*/` `PaymentInstruction/PaymentMethodName`	string	`paymentMethodName`	Name of the WebSphere Commerce payment method to be associated with the payment instruction, for example, "VISA". Required if creating a new payment instruction and the payment system name is not specified.	N
`DataArea/FinancialTransaction/*/` `PaymentInstruction/ExtendedData[i]/@name`	string	`extendedDataName_i`	Name of the i-th extended data of the payment instruction. Required if creating a new payment instruction. Some payment plug-ins might require additional plugin-specific extended data; refer to their documentations for details.	N
`DataArea/FinancialTransaction/*/` `PaymentInstruction/ExtendedData[i]`	string	`extendedDataValue_j`	Value of the i-th extended data of the payment instruction. Required if creating a new payment instruction.	N

* Namespace prefixes ignored for simplicity.

Examples

Sample ProcessFinancialTransaction BOD 1 - approve request
Sample ProcessFinancialTransaction BOD 2 - deposit request
Sample ProcessFinancialTransaction BOD 3 - approve and deposit request
Sample ProcessFinancialTransaction BOD 4 - credit request

Response

Responses of this inbound Web service are in the form of AcknowledgeFinancialTransaction BODs. They will contain the following information:


XPath*	Type	Description
`DataArea/FinancialTransaction/FinancialTransactionIdentifier/` `FinancialTransactionID`	long	ID of the WebSphere Commerce financial transaction.
`DataArea/FinancialTransaction/RequestedAmount`	decimal	The requested amount.
`DataArea/FinancialTransaction/RequestedAmount`/@currency	string	Currency of the requested amount.
`DataArea/FinancialTransaction/ProcessedAmount`	decimal	The amount actually processed (for example, approved). 0 if the financial transaction is pending.
`DataArea/FinancialTransaction/ProcessedAmount`/@currency	string	Currency of the processed amount.
`DataArea/FinancialTransaction/State`	string	State of the financial transaction. The state can be: "Pending" - the financial transaction is pending, typically the case for an offline financial transaction. "Success" - the financial transaction is successful. "Failed" - the financial transaction has failed. "Canceled" - the financial transaction has been canceled before it completes.
`DataArea/FinancialTransaction/ReferenceNumber`	string	Reference number of the financial transaction returned by the payment service provider.
DataArea/FinancialTransaction/ResponseCode	string	Response code returned by the payment service provider. Typically set to 0 if the financial transaction is successful or a non-zero value if not; otherwise payment plug-in-specific. See the Payment plug-in specification for more information.
DataArea/FinancialTransaction/ReasonCode	string	Reason code (a.k.a. secondary response code) returned by the payment service provider. Typically set to 0 if the financial transaction is successful or a non-zero value if not; otherwise payment plug-in-specific. See the Payment plug-in specification for more information.
DataArea/FinancialTransaction/ReasonMessage	string	Reason message returned by the payment service provider. Typically only set if the financial transaction has failed, otherwise payment plug-in-specific. See the Payment plug-in specification for more information.
DataArea/FinancialTransaction/TrackingID	string	Tracking ID returned by the payment plugin. See the Payment plug-in specification for more information.
DataArea/FinancialTransaction/TimeCreated	dateTime	Time the financial transaction was created.
DataArea/FinancialTransaction/TimeUpdated	dateTime	Time the financial transaction was last updated.
DataArea/FinancialTransaction/Payment/PaymentIdentifier/PaymentID	long	ID of the WebSphere Commerce payment associated with the financial transaction. Should be stored for future financial transactions on the same payment, for example, the payment capture request following a payment authorization request.

* Namespace prefixes ignored for simplicity.

Examples

Sample AcknowledgeFinancialTransaction BOD 1 - response of a successful approve request
Sample AcknowledgeFinancialTransaction BOD 2 - response of a successful deposit request
Sample AcknowledgeFinancialTransaction BOD 3 - response of a successful approve and deposit request
Sample AcknowledgeFinancialTransaction BOD 4 - response of a successful credit request

Exceptions

All exceptions will be returned in the form of AcknowledgeFinancialTransaction BODs with a ResponseCriteria element under the Acknowledge verb. They will contain the following information:


XPath*	Type	Description
`DataArea/Acknowledge/ResponseCriteria/ChangeStatus/Code`	string	The correlation identifier. Can be used to uniquely identified an exception in the server logs.
`DataArea/Acknowledge/ResponseCriteria/ChangeStatus/ReasonCode`	string	The reason code, which is either a WebSphere Commerce system error code WebSphere Commerce system error code plus an optional secondary error code if the WebSphere Commerce system error code is unavailable (usually in the case of application exceptions).
`DataArea/Acknowledge/ResponseCriteria/ChangeStatus/Reason`	string	The exception message.

* Namespace prefixes ignored for simplicity.

Examples

Sample AcknowledgeFinancialTransaction BOD 5 - exception response when the credit card has expired
Sample AcknowledgeFinancialTransaction BOD 6 - exception response when missing a required parameter

Note: releaseID and versionID attributes should be blank when calling the payment processing service and ignore the attributes returned in response BOD.