Working with payment results

✖
Copy to clipboard

The system stores payment results in XML format. In the API, the results are managed using CMS.Ecommerce.PaymentResultInfo objects. Every XML node of a payment result is represented by a single payment result item, which can be managed using the CMS.Ecommerce.PaymentResultItemInfo object.

By default, the system provides the following payment result items:

  • Payment date – the date and time when the payment result was last updated.
  • Payment method – the payment method that was used for the transaction.
  • Payment is completed – indicates whether the payment was completed successfully.
  • Payment status – the status of the payment, e.g. Completed, Failed, etc. (your custom status).
  • Payment transaction ID – a unique identifier for the payment transaction generated by the payment gateway.
  • Payment description – text describing the result of the payment transaction.

Payment result items have the following properties:

  • Name – represents a unique identifier of the payment result item.
  • Header – represents the name of the payment result item visible to users in the Orders application (simple text or localizable string).
  • Text – determines the outer representation of the payment result item value visible to users in the Orders application (simple text or localizable string).
  • Value – determines the inner representation of the payment result item value used by developers.

Example - Order payment result XML definition

The following example shows an XML definition of an order payment result extended by the authorizationcode item used by Authorize.NET:




<result>
    <item name="date" header="{$PaymentGateway.Result.Date$}" value="1/27/2008 5:01:41 PM" />
    <item name="method" header="{$PaymentGateway.Result.PaymentMethod$}" text="Credit card" value="230" />
    <item name="completed" header="{$PaymentGateway.Result.IsCompleted$}" value="1" text="{$PaymentGateway.Result.PaymentCompleted$}" />
    <item name="status" header="{$PaymentGateway.Result.Status$}" text="{$PaymentGateway.Result.Status.Completed$}" value="completed" />
    <item name="transactionid" header="{$PaymentGateway.Result.TransactionID$}" value="0" />
    <item name="description" header="{$PaymentGateway.Result.Description$}" />
    <item name="authorizationcode" header="{$AuthorizeNet.AuthorizationCode$}" value="000000" />
</result>

The system stores the payment result XML values in the OrderPaymentResult column of order records (COM_Order database table).

Example - Order payment result in the Orders application

The following example shows a payment result visible to your on-line store administrators in the Orders application while editing a selected order on the Billing tab:

Date: 1/27/2008 5:01:41 PM
Method: Credit card
Is completed: YES
Status: Completed
Transaction ID: 0
Authorization code: 000000

The payment result is unavailable (N/A) until the payment gateway processor updates it.

You do not need to specify both item value and item text if they are identical. The system automatically renders payments results as follows:

  1. Render the item text if available.
  2. If not, render the item value.

Customizing payment results

To manage the default payment result items, use the corresponding properties of PaymentResultInfo objects:

  • PaymentDate (DateTime)
  • PaymentMethodID (int)
  • PaymentMethodName (string)
  • PaymentIsCompleted (bool)
  • PaymentStatusName (string)
  • PaymentStatusValue (string
  • PaymentTransactionID (string)
  • PaymentDescription (string)

To get or set custom payment result items, call the GetPaymentResultItemInfo(string itemName) and SetPaymentResultItemInfo(PaymentResultItemInfo itemObj) public methods.

The following examples demonstrate how to work with a custom payment result item (storing an authorization code) in the code of a custom gateway provider class:

Setting the authorization code 



using CMS.Ecommerce;

...

// Prepares a PaymentResultItemInfo object for the authorization code
PaymentResultItemInfo item = new PaymentResultItemInfo();
item.Header = "{$AuthorizeNet.AuthorizationCode$}";
item.Name = "authorizationcode";
item.Value = "00000";

// Saves the custom item into the PaymentResultInfo object processed by the gateway provider
PaymentResult.SetPaymentResultItemInfo(item);
Getting the authorization code 



using CMS.Ecommerce;

...

// Gets the custom item from the PaymentResultInfo object processed by the gateway provider
PaymentResultItemInfo item = PaymentResult.GetPaymentResultItemInfo("authorizationcode");