Skip to main content
page last edited on 17 January 2023

Payment Module

Version: 5.5.1

To create a payment module, you need to specify payment as the type in main.yaml.

type: payment
authorName: 'X-Cart examples'
moduleName: 'Example "Payment" module'
description: 'Example "Payment" module'
minorRequiredCoreVersion: 0
dependsOn: { }
incompatibleWith: { }
showSettingsForm: false
canDisable: true

You also need to add one or more payment methods to install.yaml.

- service_name: DemoPayment
class: XCExample\Payment\Model\Payment\Processor\DemoPayment
type: C
- code: en
name: Demo Payment
- name: login
- name: password
- name: mode
value: live

Possible types of payment methods:

        public const TYPE_ALLINONE    = 'A';
public const TYPE_CC_GATEWAY = 'C';
public const TYPE_ALTERNATIVE = 'N';
public const TYPE_OFFLINE = 'O';

Depending on the type of payment method being created, you can extend the existing payment processor class or write your own class. Typically, the following classes are extended:

\XLite\Model\Payment\Processor\Offline - offline payment method

\XLite\Model\Payment\Processor\COD - offline payment method “Cash on delivery”

\XLite\Model\Payment\Base\Online - online payment method

\XLite\Model\Payment\Base\WebBased - online payment method that relies on loading a form from an external payment system

\XLite\Model\Payment\Base\Iframe - online payment method that involves loading information in an iframe


The result of using a payment method is a transaction linked to an order. Order payment status is calculated automatically based on the transaction status.

The transaction status is set initially based on the result of the method

\XLite\Model\Payment\Base\Processor::doInitialPayment (see \XLite\Model\Payment\Transaction::handleCheckoutAction)

Further on the status updates are done using the methods





For the processing of returns from the payment system, the following method is used:


Note that a correct return URL must be passed to the payment system; the URL can be generated using the method



For the processing of asynchronous messages from the payment system, the following method is used:


Note that a correct return URL must be passed to the payment system; the URL can be generated using the method


When processing the messages, it should be taken into account that they can be received earlier than the return will be processed in the method processReturn

Multi-stage transaction processing

Depending on the features of the payment service being used, a transaction can be processed in several stages. The following transaction types are supported:

namespace XLite\Model\Payment;

class BackendTransaction extends \XLite\Model\AEntity
public const TRAN_TYPE_AUTH = 'auth';
public const TRAN_TYPE_SALE = 'sale';
public const TRAN_TYPE_CAPTURE = 'capture';
public const TRAN_TYPE_CAPTURE_PART = 'capturePart';
public const TRAN_TYPE_CAPTURE_MULTI = 'captureMulti';
public const TRAN_TYPE_VOID = 'void';
public const TRAN_TYPE_VOID_PART = 'voidPart';
public const TRAN_TYPE_VOID_MULTI = 'voidMulti';
public const TRAN_TYPE_REFUND = 'refund';
public const TRAN_TYPE_REFUND_PART = 'refundPart';
public const TRAN_TYPE_REFUND_MULTI = 'refundMulti';

By default, a transaction is created with the TRAN_TYPE_SALE type. You can change this by returning a different value from the method


In this case, TRAN_TYPE_SALE or TRAN_TYPE_AUTH can be specified as the initial transaction type.

To use other types of transactions, you will need to list them in the \XLite\Model\Payment\Base\Processor::getAllowedTransactions method. As a result, the respective actions will be available in the order management interface of the Admin area.

TRAN_TYPE_CAPTURE - If the initial transaction type was TRAN_TYPE_AUTH, during a capture the payment is completed (the order amount is transferred from the account of the buyer to the account of the merchant)

TRAN_TYPE_CAPTURE_PART - This is similar to TRAN_TYPE_CAPTURE, but only a portion of the amount can be transferred.

TRAN_TYPE_CAPTURE_MULTI - This is similar to TRAN_TYPE_CAPTURE_PART, but a transfer can be done multiple times.

TRAN_TYPE_VOID - If the initial transaction type was TRAN_TYPE_AUTH, this type of transaction cancels the authorization.

TRAN_TYPE_VOID_PART - This is similar to TRAN_TYPE_VOID, but an authorization can be canceled only partially.

TRAN_TYPE_VOID_MULTI - This is similar to TRAN_TYPE_VOID_PART, but a cancellation can be done multiple times per authorization.

TRAN_TYPE_REFUND - If the initial transaction type was TRAN_TYPE_SALE or if the money was transferred to the account of the merchant by a capture previously, this type of transaction returns the money from the merchant to the buyer.

TRAN_TYPE_REFUND_PART - This is similar to TRAN_TYPE_REFUND, but it is possible to return only a portion of the captured amount.

TRAN_TYPE_REFUND_MULTI - This is similar to TRAN_TYPE_REFUND_PART, but a return can be done multiple times.

When using actions based on additional transaction types, the corresponding methods from the method processor class will be called.


Additionally, if the methods are implemented in the processor, then the actions will be performed only if the corresponding method returns TRUE