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

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

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

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