Supported Operations

Commerce Web Services

Print Friendly, PDF & Email

Transaction Processing Supported Operations

The Authorize operation is used to authorize transactions by performing a check on cardholder’s funds and reserves the authorization amount if sufficient funds are available. Unlike the AuthorizeAndCapture operation, Authorize transactions must then be flagged for settlement by invoking the Capture operation.

Note: Authorize is not supported when processing PIN Debit transactions on terminal capture systems. For more information, refer to Terminal Capture Operation Flows.
 

Implementation Notes

The following implementation notes are specific to the Authorize operation:

  • Visa and MasterCard support authorizations of $0.00.
  • American Express and Discover do not support authorizations of $0.00.
  • Discover supports the reversal (void) of authorizations, so the reversal will not show on the cardholder’s statement.
  • American Express does not support the reversal (void) of authorizations. Any authorized amount will roll off after 30 days and will show on the cardholder’s statement.
  • Be sure to set a unique OrderNumber in the BankcardTransactionData object. This ensures fast and convenient recovery of transactionIds in the event of communication failures.
  • The BankcardTransactionPro object is required to support BankcardInterchangeData used for recurring, installment, and deferred billing payments.
  • The BankcardTransactionDataPro object is required to support Level 2 and/or Level 3 transaction data.
Note: The HTTP Authorization Header must contain the required sessionToken value.

The following operations are used to adjust and void previously authorized transactions for both SOAP and REST implementations:

 

Adjust

The Adjust operation is used to make adjustments to a previously authorized amount (incremental or reversal) prior to capture and settlement.

 

Undo

The Undo operation is used to release cardholder funds by performing a void (Credit Card) or reversal (PIN Debit) on a previously authorized transaction that has not been captured (flagged) for settlement.

 

The Undo operation differs from the ReturnUnlinked operation in that Undo is used to void or reverse a previously authorized transaction, while ReturnUnlinked can only be used to return funds for a transaction that has been previously flagged for capture.

 

Performing a “force void” (BankcardUndo.ForceVoid) indicates whether an authorized transaction should be removed from the batch regardless of whether the Undo request is approved or declined. Otherwise, authorized transactions will only be removed from the batch if the void is approved.

 
Note: The use of the Undo operation is restricted to transactions that have a TransactionState of “ErrorUnknown”, or any other valid transaction state. Performing an Undo on transactions with a TransactionState of “InProcess”, “ErrorConnecting”, or “ErrorValidation” will not be processed and an error response is returned to the client application.
For more information, refer to Payments Status Messaging in the Transaction Management Developer’s Guide.

Capture

 

The Capture operation is used to capture a single transaction for settlement after it has been successfully authorized by the Authorize operation.

Note: The Capture differenceData object is required when capturing a single transaction with a settlement amount different from the original authorization amount, or when ship date is required in MOTO transactions.
 

In the Capture differenceData object, the Amount parameter should be equal to the new amount being captured. For example:

Authorize Amount = 10.00; Capture Amount = 10.00; Settled Amount = 10.00 Authorize Amount = 10.00; Capture Amount = 14.00 (result of +$4.00 INCAUTH); Settled Amount = 14.00 Authorize Amount = 10.00; Capture Amount = 8.00 (result of -$2.00 REVAUTH); Settled Amount = 8.00
 

CaptureAll

 

The CaptureAll operation is used to flag all transactions for settlement that have been successfully authorized using the Authorize operation. Merchants may wish to invoke this operation to ensure all transactions are included in the batch that is sent for settlement processing by the cut-off times established by the service provider or to transmit smaller batches to the service provider for settlement.

 

In addition, when performing CaptureAll on terminal capture hosts, settlement times of up to 5 minutes or more are not uncommon depending on the number of transactions in the batch. Client applications need to anticipate and account for longer settlement processing times in their time-out management schemes.

Note: The Capture differenceData object is required when capturing a single transaction with a settlement amount different from the original authorization amount or when ship date is required in MOTO transactions.
 

In the Capture differenceData object, the Amount parameter should be equal to the new amount being captured. For example:

Authorize Amount = 10.00; Capture Amount = 10.00; Settled Amount = 10.00 Authorize Amount = 10.00; Capture Amount = 14.00 (result of +$4.00 INCAUTH); Settled Amount = 14.00 Authorize Amount = 10.00; Capture Amount = 8.00 (result of -$2.00 REVAUTH); Settled Amount = 8.00

ReturnById

 

The ReturnById operation is used to perform a linked credit to a cardholder’s account from the merchant’s account based on a previously authorized and settled transaction.

  

ReturnUnlinked

 

The ReturnUnlinked operation is used to perform an “unlinked”, or standalone, credit to a cardholder’s account from the merchant’s account. This operation is useful when a return transaction is not associated with a previously authorized and settled transaction.

 

Best Practices

Below are some recommendations and best practices associated with the integration of the Transaction Processing operations:

  • Support for the operations above is determined based on the Service Information retrieved for the merchant Service Key when invoking the GetServiceInformation operation. When invoked, a Boolean property is returned indicating whether a specific transaction processing operation is supported for an available service.
  • As with Preparing the Application to Transact, serviceId, applicationProfileId, and merchantProfileId should be encrypted and stored locally rather than performing a value lookup for every transaction.
  • As a best practice, the application should track the time duration of the sessionToken. Prior to processing transactions, the application should reference the age of the current sessionToken. If the value is greater than 25 minutes, then a new call to SignOn should be made and the process of tracking the sessionToken repeated.
  • If the application will be supporting custom transaction processing workflows, you will send in the appropriate workflowId in all Transaction Processing operations. If the application is not supporting custom workflows, the application will send in the serviceId returned by the GetServiceInformation operation as the workflowId in each operation.
  • The Adjust, Undo, Capture, and ReturnById operations support differenceData, which allows for updates to transaction amounts in the event of incremental (INCAUTH) and reversal (REVAUTH) authorizations.
  • The following operations are considered optional and their implementation will depend on the specific requirements of the application:
    1. The Acknowledge operation can be invoked after the successful receipt of a transaction response message to flag a transaction as ‘acknowledged’ in the transaction database. This acknowledgement is useful when performing transaction management functions, such as those provided by theTransaction Management Service API.
    2. The RequestTransaction operation allows for the retrieval of any transaction matching the supplied tender data. This is useful in transaction-processing situations when the application does not receive a response from CWS indicating the TransactionState.

 

API Reference

For Supported Operation API reference information, click on the links below: