Skip to main content
page last edited on 17 January 2023

Payment Module

Version: 5.5

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

version: 5.5.0.0
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.

XLite\Model\Payment\Method:
- service_name: DemoPayment
class: XCExample\Payment\Model\Payment\Processor\DemoPayment
type: C
translations:
- code: en
name: Demo Payment
settings:
- 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

Transactions

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

\XLite\Model\Payment\Base\Online::processReturn

and

\XLite\Model\Payment\Base\Online::processCallback

Return

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

\XLite\Model\Payment\Base\Online::processReturn

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

\XLite\Model\Payment\Base\Online::getReturnURL

Callback

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

\XLite\Model\Payment\Base\Online::processCallback

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

\XLite\Model\Payment\Base\Online::getCallbackURL

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

\XLite\Model\Payment\Base\Processor::getInitialTransactionType

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.

TRAN_TYPE_CAPTURE - doCapture()
TRAN_TYPE_CAPTURE_PART - doCapturePart()
TRAN_TYPE_CAPTURE_MULTI - doCaptureMulti()
TRAN_TYPE_VOID - doVoid()
TRAN_TYPE_VOID_PART - doVoidPart()
TRAN_TYPE_VOID_MULTI - doVoidMulti()
TRAN_TYPE_REFUND - doRefund()
TRAN_TYPE_REFUND_PART - doRefundPart()
TRAN_TYPE_REFUND_MULTI - doRefundMulti()

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