These methods are invoked when processing payments. A module that implements these methods should also implement IsModuleType() in order to identify itself as a “payment” module, and also as a “collection” module if appropriate.
AdminFinance_Collect (deprecated)
Called when an administrator clicks the Collect button on the Finance page.
Method
int AdminFinance_Collect(string orderID)
Parameters
■ orderID — Internal order ID number for the order.
Returns
The module can perform any external operations associated with manual collection and should return eSuccess.
Remarks
This method is deprecated and may not be supported in future versions. In any case this is not the event to use when collecting funds via a Payment module. That should be done via the DelayedCapture event below, which is fired in response to calling the CollectPayment SINI method.
AuthorizeTransaction (deprecated)
Called to authorize a payment transaction.
Method
int AuthorizeTransaction(PaymentRequest request,
out PaymentResponse response)
Parameters
■ request — PaymentRequest object, defined in the Shared Classes section.
■ response — PaymentResponse object, defined in the Shared Classes section.
Returns
The module should return eDoNotCall if it is not a Payment module, eFailure if after examining the request it decides that some other payment module should decide whether to authorize, and eSuccess if it chooses to make the decision, and return the result in the response field. The result can be one of ccSUCCESS, ccDECLINE, ccUNAVAILABLE, etc. See the specification of the PaymentResponse class in the Shared Classes section.
Note that the return value for the method and the result field in the response object come from different value spaces.
The return values may be eSuccess, eFailure or eDoNotCall, which are interpreted as follows:
eSuccess | This module is a payment module and assumes control over authorization for this order; response should be an appropriate non-null value, whether the answer is to accept or decline the transaction. |
eFailure | This is the wrong kind of payment module for this order; response should be null. Do not return eFailure to indicate a Declined authorization. Return eSuccess with a response.result field equal to ccDECLINE. |
eDoNotCall | This isn’t a payment module and the module can be ignored in subsequent AuthorizeTransaction events. |
The response.result field is one of ccOKCAPTURE, ccSUCCESS, ccDECLINE, ccUNAVAILABLE, ccUNIMPLEMENTED, ccINVALID ccINTERNALERROR, or ccPENDING, which are interpreted according to the following table:
ccSUCCESS | The request is approved and authorized, and the requested amount is reserved against the account specified in the request. |
ccDECLINE | The request is declined for one of a number of reasons, including wrong account number, wrong address, wrong security code, etc. Do not return eFailure to indicate a Declined authorization. Return eSuccess with a response.result field equal to ccDECLINE. |
ccOKCAPTURE | The request is approved and authorized, and the requested amount has already been captured. Storefront will note this in the ledger and will not call DelayedCapture later. |
ccUNAVAILABLE | Some external service required by the module is not available (e.g. Internet connection is down). |
ccUNIMPLEMENTED | The particular type of request is not one that the module is designed to handle (e.g. this is the result of submitting request.methodOfPayment = “EFT” to the Verisign module, which only handles “Credit Card”). |
ccINVALID | The module is misconfigured in some way, which might be remedied by an administrator. |
ccINTERNALERROR | Some other error has occurred internal to the module. |
ccPENDING | The extension will call DelayedAuthorizationComplete2() later with the final result. |
Remarks
For this call, we depart from the usual processing sequence; the Extensions are called in order until one returns eSuccess, and then processing ends. Thus only one module gets to make the decision about authorizing.
Called to authorize a payment transaction.
Method
int AuthorizeTransaction2(string orderId, string paymentId, PaymentRequest
request, out PaymentResponse response)
Parameters
■ orderId — The internal ID of the order being processed.
■ paymentId — The internal ID of the current payment being processed.
■ request — PaymentRequest object, defined in the Shared Classes section.
■ response — PaymentResponse object, defined in the Shared Classes section.
Returns
The module should return eDoNotCall if it is not a Payment module, eFailure if after examining the request it decides that some other payment module should decide whether to authorize, and eSuccess if it chooses to make the decision, and return the result in the response field. The result can be one of ccSUCCESS, ccDECLINE, ccUNAVAILABLE, etc. See the specification of the PaymentResponse class in the Shared Classes section.
Note that the return value for the method and the result field in the response object come from different value spaces.
The return values may be eSuccess, eFailure or eDoNotCall, which are interpreted as follows:
eSuccess | This module is a payment module and assumes control over authorization for this order; response should be an appropriate non-null value, whether the answer is to accept or decline the transaction. |
eFailure | This is the wrong kind of payment module for this order; response should be null. Do not return eFailure to indicate a Declined authorization. Return eSuccess with a response.result field equal to ccDECLINE. |
eDoNotCall | This isn’t a payment module and the module can be ignored in subsequent AuthorizeTransaction2 events. |
The response.result field is one of ccOKCAPTURE, ccSUCCESS, ccDECLINE, ccUNAVAILABLE, ccUNIMPLEMENTED, ccINVALID ccINTERNALERROR, or ccPENDING, which are interpreted according to the following table:
ccSUCCESS | The request is approved and authorized, and the requested amount is reserved against the account specified in the request. |
ccDECLINE | The request is declined for one of a number of reasons, including wrong account number, wrong address, wrong security code, etc. Do not return eFailure to indicate a Declined authorization. Return eSuccess with a response.result field equal to ccDECLINE. |
ccOKCAPTURE | The request is approved and authorized, and the requested amount has already been captured. Storefront will note this in the ledger and will not call DelayedCapture2() later. |
ccUNAVAILABLE | Some external service required by the module is not available (e.g. Internet connection is down). |
ccUNIMPLEMENTED | The particular type of request is not one that the module is designed to handle (e.g. this is the result of submitting request.methodOfPayment = “EFT” to the Verisign module, which only handles “Credit Card”). |
ccINVALID | The module is misconfigured in some way, which might be remedied by an administrator. |
ccINTERNALERROR | Some other error has occurred internal to the module. |
ccPENDING | The extension will call DelayedAuthorizationComplete2() later with the final result. |
Remarks
If split payment is enabled and there is more than one payment applied to an order then the paymentId may be necessary to get information specific to that payment, such as billing address, transactionID, etc.
For this call, we depart from the usual processing sequence; the Extensions are called in order until one returns eSuccess, and then processing ends. Thus only one module gets to make the decision about authorizing.
If no modules respond to AuthorizeTransaction2() we will call the legacy method AuthorizeTransaction().
CouldCollect (deprecated)
Since version 2.5
Note: This method is deprecated. Use CouldCollect2() instead, below.
Asks the module whether it could collect on the order. This controls enabling of the Collect Payment button in the Orders and Order Details pages on the Storefront Administrator site.
Method
int CouldCollect(string orderID)
Parameters
■ orderID — Internal order ID number for the order.
Returns
A Payment module should return eSuccess if it can collect for this order, otherwise it should return eFailure. For this call, we depart from the usual processing sequence; the Extensions are called in order until one returns eSuccess, and then processing ends.
Asks the module whether it could collect on the order. This controls enabling of the Collect Payment button in the Orders and Order Details pages on the Storefront Administrator site.
Method
int CouldCollect2(string orderID,
string paymentId,
string collectionToken)
Parameters
■ orderID — Internal order ID number for the order.
■ paymentID — Internal payment ID number for the payment transaction.
■ collectionToken — Collection token return from AuthorizeTransaction, if any.
Returns
A Payment module should return eSuccess if it can collect for this order, otherwise it should return eFailure. For this call, we depart from the usual processing sequence; the Extensions are called in order until one returns eSuccess, and then processing ends.
Remarks
If no extensions implement this event, Storefront calls the legacy CouldCollect() instead.
CreditTransaction (deprecated)
Since version 7.6
Note: This method is deprecated. Use CreditTransaction2() instead, below.
Called from Storefront when an administrator wishes to reverse a collected payment.
Method
int CreditTransaction(string orderId,
double amount,
string currency,
string authorizationTransID,
string captureTransID,
string collectionToken,
out PaymentResponse response)
Parameters
■ orderID — Internal order ID of the order to which this credit refers.
■ amount — Amount to refund, in currency units (e.g. 1.00 for one dollar).
■ currency — ISO currency code (e.g. “USD” for dollars).
■ authorizationTransID — The transaction ID of the original authorization to which this credit is associated.
■ captureTransID — The transaction ID of the delayed capture which collected the funds.
■ collectionToken — The collection token used to capture the funds.
■ response — A PaymentResponse object with the result of the credit transaction.
Returns
The module should return eSuccess if the parameters are correct and it is the module with authority over the transaction, or if the transaction ID is null.
It should attempt to credit the amount to the account specified and return a PaymentResponse object with the fields filled out as follows:
response.result ccSUCCESS if the credit succeeded
ccDECLINE if the processor refused the credit
ccINVALID if the capture never happened
(this should not happen)
these values should *not* be set to ccPENDING
response.TransactionID transaction ID of the credit transaction
response.message any relevant message to be stored in the ledger
All other fields should be set to null or false.
If the attempted credit fails it should not return eFailure, but rather should return eSuccess with a PaymentResponse that indicates ccDECLINE as its result.
If the module can't process refunds, then it should always return eDoNotCall.
Remarks
The PaymentResponse object is described in the Shared Classes section. This call is only sent to the unique SXI module which originally replied to the AuthorizeTransaction call. If the authorizationToken is null, the module should do nothing and simply return eSuccess if it can handle this call usefully. We don’t provide the account number since this is normally not stored, e.g. for credit card transactions.
Called from Storefront when an administrator wishes to reverse a collected payment.
Method
int CreditTransaction2(string orderId,
string paymentId,
double amount,
string currency,
string authTransID,
string captureTransID,
string collectionToken,
out PaymentResponse response)
Parameters
■ orderID — Internal order ID of the order to which this credit refers.
■ paymentID — Internal payment ID number for the payment transaction.
■ amount — Amount to refund, in currency units (e.g. 1.00 for one dollar).
■ currency — ISO currency code (e.g. “USD” for dollars).
■ authTransID — The transaction ID of the original authorization to which this credit is associated.
■ captureTransID — The transaction ID of the delayed capture which collected the funds.
■ collectionToken — The collection token used to capture the funds.
■ response — A PaymentResponse object with the result of the credit transaction.
Returns
The module should return eSuccess if the parameters are correct and it is the module with authority over the transaction, or if the transaction ID is null.
It should attempt to credit the amount to the account specified and return a PaymentResponse object with the fields filled out as follows:
response.result ccSUCCESS if the credit succeeded
ccDECLINE if the processor refused the credit
ccINVALID if the capture never happened
(this should not happen)
this field should *not* be set to ccPENDING
response.TransactionID transaction ID of the credit transaction
response.message any relevant message to be stored in the ledger
All other fields should be set to null or false.
If the attempted credit fails it should not return eFailure, but rather should return eSuccess with a PaymentResponse that indicates ccDECLINE as its result.
If the module can't process refunds, then it should always return eDoNotCall.
If no active module implements this method, Storefront calls the legacy CreditTransaction() method instead.
Remarks
The PaymentResponse object is described in the “Classes and Properties” section, below. This call is only sent to the unique SXI module which originally replied to the AuthorizeTransaction call. If the authorizationToken is null, the module should do nothing and simply return eSuccess if it can handle this call usefully. We don’t provide the account number since this is normally not stored, e.g. for credit card transactions.
DelayedCapture (deprecated)
Since version 2.5
Called to capture funds on a payment transaction.
Method
int DelayedCapture(string captureToken,
string amount,
string isoCurrencyCode,
out PaymentResponse ccrsp)
Parameters
■ captureToken — The captureToken argument will be the same as the PaymentResponse.CollectionToken field returned from AuthorizeTransaction().
■ amount — The amount to collect.
■ isoCurrencyCode — The currency of the funds to be captured, represented as 3-letter code according to the ISO 4217 standard; e.g. “USD” for U.S. Dollars.
■ ccrsp — PaymentResponse object to be filled on output. The PaymentResponse class is specified in the Shared Classes section.
Returns
The module should attempt to collect the amount requested and return eSuccess, with the ccrsp parameter containing the result of the transaction. Modules should not call this method themselves to collect payment; instead they should call the SINI method CollectPayment; see “CollectPayment” .
Called to capture funds on a payment transaction.
Method
int DelayedCapture2(string orderId,
string paymentId,
captureToken,
string amount,
string isoCurrencyCode,
out PaymentResponse ccrsp)
Parameters
■ orderID — The internal ID of the order being processed.
■ paymentID — The internal ID of the current payment being processed.
■ captureToken — The captureToken argument will be the same as the PaymentResponse.CollectionToken field returned from AuthorizeTransaction2().
■ amount — The amount to collect.
■ isoCurrencyCode — The currency of the funds to be captured, represented as 3-letter code according to the ISO 4217 standard; e.g. “USD” for U.S. Dollars.
■ ccrsp — PaymentResponse object to be filled on output. The PaymentResponse class is specified in the Shared Classes section.
Returns
The module should attempt to collect the amount requested and return eSuccess, with the ccrsp parameter containing the result of the transaction. Modules should not call this method themselves to collect payment; instead they should call the SINI method CollectPayment; see “CollectPayment” .
Remarks
If split payment is enabled and there is more than one payment applied to an order then the paymentId may be necessary to get information specific to that payment, such as billing address, transactionID, etc.
If no modules respond to DelayedCapture2() we will call the legacy method DelayedCapture().
Called to void an Authorize or DelayedCapture transaction.
Method
int VoidTransaction(string transactionID,
out PaymentResponse ccrsp)
Parameters
■ transactionID — The TransactionID field from the PaymentResponse returned by the call that is being voided.
■ ccrsp — PaymentResponse object to be filled on output. The PaymentResponse class is specified in the Shared Classes section.
Returns
The module should attempt to void the transaction and return eSuccess, with the ccrsp field containing the result of the void transaction.
Note: A VoidTransaction() operation is itself a transaction and has its own TransactionID which is returned in the ccrsp.)
Remarks
The Void transaction cannot itself be voided. In some implementations, an AuthorizeTransaction transaction cannot be voided after any funds have been captured against it using DelayedCapture(). An AuthorizeTransaction transaction cannot have funds captured against it after being voided.
Called to void an AuthorizeTransaction2 or DelayedCapture2 transaction.
Method
int VoidTransaction2(string orderId,
string paymentId,
string transactionID,
out PaymentResponse ccrsp)
Parameters
■ orderID — The internal ID of the order being processed.
■ paymentID — The internal ID of the current payment being processed.
■ transactionID — The TransactionID field from the PaymentResponse returned by the call that is being voided.
■ ccrsp — PaymentResponse object to be filled on output. The PaymentResponse class is specified in the Shared Classes section.
Returns
The module should attempt to void the transaction and return eSuccess, with the ccrsp field containing the result of the void transaction.
Note: A VoidTransaction2() operation is itself a transaction and has its own TransactionID which is returned in the ccrsp.)
Remarks
The Void transaction cannot itself be voided. In some implementations, an AuthorizeTransaction2 transaction cannot be voided after any funds have been captured against it using DelayedCapture2. An AuthorizeTransaction2 transaction cannot have funds captured against it after being voided.
If split payment is enabled and there is more than one payment applied to an order then the paymentId may be necessary to get information specific to that payment, such as billing address, transactionID, etc.
If no modules respond to VoidTransaction2() we will call the legacy method VoidTransaction().