Payment processing service

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 (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.

Related reference
Service-oriented outbound integration points
Inbound web services provided

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

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 (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.

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.