Implementation, Transaction Processing: Adjusting and Voiding Transactions

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

Adjust/Void Operations
Adjust (BCP only) Undo (BCP, ECK, SVA)

Important! All parameters in each operation are considered "required" unless otherwise noted.

 


 

Adjust

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

SOAP

Note: In situations where the service configuration does not support Adjust, adjustments can still be made at the time of settlement by setting the new transaction amount on the BankcardCapture object.

In the Adjust differenceData object, the Amount parameter either increases or decreases the original authorized amount by the specified value. TipAmount is simply a reporting field and bears no impact on the amount being passed. For example:

Incremental Authorization (INCAUTH) Reverse Authorization (REVAUTH)
Authorize Amount = 10.00
Adjust Amount = 2.00
Settled Amount = 12.00
Authorize Amount = 10.00
Adjust Amount = (-2.00)
Settled Amount = 8.00

Operation

Response Adjust(string sessionToken, Adjust differenceData, string applicationProfileId, string workflowId);

Parameters

Parameter Data Type Description
sessionToken String The short-lived token used to authenticate to CWS.
differenceData Adjust The adjusted transaction amount (incremental or reversal).
applicationProfileId String A token representing the PTLS Socket ID unique to each Service Key and configuration data combination. Returned by the SaveApplicationData operation.
workflowId String Identifies the workflow to use for the transaction. If not supporting custom workflows, pass the servideId returned by GetServiceInformation.

Return Type

Data Type Description
Response Transaction response data.
Note: For Bankcard (BCP) transactions, the response object is BankcardTransactionResponsePro.
For Electronic Checking (ECK) transactions, the response object is ElectronicCheckingTransactionResponse.
For Stored Value Account (SVA) transactions, the response object is StoredValueTransactionResponse.

Exceptions

CWSFault CWSInvalidOperationFault
AuthenticationFault CWSInvalidServiceInformationFault
ExpiredTokenFault CWSOperationNotSupportedFault
InvalidTokenFault CWSTransactionAlreadySettledFault
CWSConnectionFault CWSTransactionFailedFault
CWSExtendedDataNotSupportedFault CWSTransactionServiceUnavailableFault
CWSInvalidMessageFormatFault CWSValidationResultFault

For additional details about each fault, refer to Transaction Processing Faults in the CWS Developer API Reference.

PHP Code Sample

<?php
		require_once(dirname(__FILE__) . '/AuthOnlyTC.php');
		
		class Adjust {
		   public $Addendum;
		   public $Amount;
		   public $TipAmount;
		   public $TransactionId;
		}
		var_dump($response);
		$adjust = new Adjust();
		$adjust->TransactionId = $response[2];
		$adjust->Amount = "14.00";
		
		$adjustParam = '<ns8:Amount xmlns:ns8="http://schemas.ipcommerce.com/CWS/v2.0/Transactions">'. $adjust->Amount . '</ns8:Amount>
						<ns2:TransactionId xmlns:ns2="http://schemas.ipcommerce.com/CWS/v2.0/Transactions">'.$adjust->TransactionId.'</ns2:TransactionId>';
		
			$transactionAdjust = '<?xml version="1.0" encoding="UTF-8"?>
							<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">'
							. '<SOAP-ENV:Body>
								<Adjust xmlns="http://schemas.ipcommerce.com/CWS/v2.0/TransactionProcessing">
								  <sessionToken>'.$sessionTokenString.'</sessionToken>
								  <differenceData>'
									.$adjustParam.
							      '</differenceData>'
								  .'<applicationProfileId>'.$applicationIdString.'</applicationProfileId>'
								  .'<workflowId>'.$serviceId.'</workflowId>'
								.'</Adjust>
							   </SOAP-ENV:Body>
							</SOAP-ENV:Envelope>';
		
		$call = 'Adjust';
		$xmlRequest = $transactionAdjust;
		$response = curl_call($xmlRequest, $sessionTokenString, $call);
		
		echo nl2br("<h1>Adjust Transaction Results</h1>
					<h3>StatusMessage: " . $response[0] . "</h3> 
					<h3>StatusCode: "    . $response[1] . "</h3> 
					<h3>TransactionId: " . $response[2] . "</h3>
					");
?>

C# Code Sample

public Response Adjust(string sessionToken, Adjust adjust, string applicationProfileId, string workflowId)
{
	using (var client = new CwsTransactionProcessingClient(ConfigurationManager.AppSettings["Bindings.TxnSoap"]))
	{
		try
		{
			return client.Adjust(sessionToken, adjust, applicationProfileId, workflowId);
		}
		catch (FaultException ex)
		{
			SoapFaultHandler.HandleFaultException(ex);
		}
	}
}

REST

Note: In situations where the service configuration does not support Adjust, adjustments can still be made at the time of settlement by setting the new transaction amount on the Rest.Capture DifferenceData object.

Note: The HTTP Authorization Header must contain the required sessionToken value.

Operation

URL https://api.cert.nabcommerce.com/REST/2.0.18/Txn/{workflowId}/{transactionId}
UMP URL https://api.cert.nabcommerce.com/REST/2.0.18UMP/Txn/{workflowId}/{transactionId}
Action PUT

Parameters

Parameter Data Type Description
workflowId String Identifies the workflow to use for the transaction. If not supporting custom workflows, pass the servideId returned by GetServiceInformation.
transactionId String The transaction ID to be adjusted.

Message Body Type

Data Type Description
Rest.Adjust The message body containing transaction data.

Return Type

Data Type Description
Response Transaction response data.
Note: For Bankcard (BCP) transactions, the response object is BankcardTransactionResponsePro.
For Electronic Checking (ECK) transactions, the response object is ElectronicCheckingTransactionResponse.
For Stored Value Account (SVA) transactions, the response object is StoredValueTransactionResponse.

Exceptions

CWSFault CWSInvalidOperationFault
AuthenticationFault CWSInvalidServiceInformationFault
ExpiredTokenFault CWSOperationNotSupportedFault
InvalidTokenFault CWSTransactionAlreadySettledFault
CWSConnectionFault CWSTransactionFailedFault
CWSExtendedDataNotSupportedFault CWSTransactionServiceUnavailableFault
CWSInvalidMessageFormatFault CWSValidationResultFault

For additional details about each fault, refer to Transaction Processing Faults in the CWS Developer API Reference.

C# Code Sample

public Response Adjust(string sessionToken, Adjust adjust, string applicationProfileId, string workflowId)
{
	var isJson = string.Equals(_msgFormat, MessageFormat.JSON.ToString());
	var requestString = RestBaseUri + "/" + workflowId + "/" + adjust.TransactionId;
	var restAdjust = new schemas.nabcommerce.com.CWS.v2._0.Transactions.Rest.Adjust();
	restAdjust.ApplicationProfileId = applicationProfileId;
	restAdjust.DifferenceData = Utilities.SwapObjectsNamespace(adjust);
 
	var request = RestHelper.CreateRestRequest(restAdjust, requestString, HttpMethod.PUT, sessionToken, isJson);
	try
	{
		if (isJson)
			return RestHelper.GetResponse(request, isJson);
		// For XML and Adjust we do not know the specific type we will be getting back from the server. 
		// For this we can get the string response back determine what type it is from this response 
		// and then turn it into the desired object. 
		var strResponse = RestHelper.GetResponse(request, isJson, false);
		if (strResponse.Contains("BankcardTransactionResponsePro"))
			return RestHelper.GetCWSObjectFromXml(strResponse);
		if (strResponse.Contains("ElectronicCheckingTransactionResponse"))
			return RestHelper.GetCWSObjectFromXml(strResponse);
		if (strResponse.Contains("StoredValueTransactionResponse"))
			return RestHelper.GetCWSObjectFromXml(strResponse);
	}
	catch (Exception ex)
	{

		RestFaultHandler.HandleFaultException(ex, isJson); 
	}
}

 


 

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.

SOAP

Operation

Response Undo(string sessionToken, Undo differenceData, string applicationProfileId, string workflowId);

Parameters

Parameter Data Type Description
sessionToken String The short-lived token used to authenticate to CWS.
differenceData Undo The transactionId of the transaction to void.
Note:You must send in BankcardUndo for Bankcard transactions.
applicationProfileId String A token representing the PTLS Socket ID unique to each Service Key and configuration data combination. Returned by the SaveApplicationData operation.
workflowId String Identifies the workflow to use for the transaction. If not supporting custom workflows, pass the servideId returned by GetServiceInformation.

Return Type

Data Type Description
Response Transaction response data.
Note: For Bankcard (BCP) transactions, the response object is BankcardTransactionResponsePro.
For Electronic Checking (ECK) transactions, the response object is ElectronicCheckingTransactionResponse.
For Stored Value Account (SVA) transactions, the response object is StoredValueTransactionResponse.

Exceptions

CWSFault CWSInvalidOperationFault
AuthenticationFault CWSInvalidServiceInformationFault
ExpiredTokenFault CWSOperationNotSupportedFault
InvalidTokenFault CWSTransactionAlreadySettledFault
CWSConnectionFault CWSTransactionFailedFault
CWSExtendedDataNotSupportedFault CWSTransactionServiceUnavailableFault
CWSInvalidMessageFormatFault CWSValidationResultFault

For additional details about each fault, refer to Transaction Processing Faults in the CWS Developer API Reference.

PHP Code Sample


<?php
		
		require_once(dirname(__FILE__) . '/AuthOnly.php');
		
		class Undo {
		   public $TransactionId;
		   public $Addendum;
		}
		
		$undo = new Undo();
		$undo->TransactionId = $response[2];
		$undo->ChargeType = 'NotSet';
		
		$undoParam = '<ns2:TransactionId xmlns:ns2="http://schemas.ipcommerce.com/CWS/v2.0/Transactions">'.$undo->TransactionId.'</ns2:TransactionId>
							<ns1:ChargeType>'.$undo->ChargeType.'</ns1:ChargeType>';
		
		
			$transactionUndo = '<?xml version="1.0" encoding="UTF-8"?>
							<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">'
							. '<SOAP-ENV:Body>
								<Undo xmlns="http://schemas.ipcommerce.com/CWS/v2.0/TransactionProcessing">
								  <sessionToken>'.$sessionTokenString.'</sessionToken>
								  <differenceData xsi:type="ns1:BankcardUndo" xmlns:ns1="http://schemas.ipcommerce.com/CWS/v2.0/Transactions/Bankcard">'
									.$undoParam.
							      '</differenceData>'
								  .'<applicationProfileId>'.$applicationIdString.'</applicationProfileId>'
								  .'<workflowId>'.$serviceId.'</workflowId>'
								.'</Undo>
							   </SOAP-ENV:Body>
							</SOAP-ENV:Envelope>';
		 
		
		$call = 'Undo';
		$xmlRequest = $transactionUndo;
		$response = curl_call($xmlRequest, $sessionTokenString, $call);
		
		echo nl2br("<h1>Undo Transaction Results</h1> \r\n 
					<h3>StatusMessage: " . $response[0] . "</h3> 
					<h3>StatusCode: "    . $response[1] . "</h3> 
					<h3>TransactionId: " . $response[2] . "</h3> \r\n\r\n
					<h1>That's great...now you get no $$$$!!</h1>
					");
		
		
?>

C# Code Sample

public Response Undo(string sessionToken, Undo undo, string applicationProfileId, string workflowId)
{
	using (var client = new CwsTransactionProcessingClient(ConfigurationManager.AppSettings["Bindings.TxnSoap"]))
	{
		try
		{
			return client.Undo(sessionToken, undo, applicationProfileId, workflowId);
		}
		catch (FaultException ex)
		{
			SoapFaultHandler.HandleFaultException(ex);
		}
	}
}

REST

Note:The HTTP Authorization Header must contain the required sessionToken value.

Operation

URL https://api.cert.nabcommerce.com/REST/2.0.18/Txn/{workflowId}/{transactionId}
UMP URL https://api.cert.nabcommerce.com/REST/2.0.18UMP/Txn/{workflowId}/{transactionId}
Action PUT

Parameters

Parameter Data Type Description
workflowId String Identifies the workflow to use for the transaction. If not supporting custom workflows, pass the servideId returned by GetServiceInformation .
transactionId String The transaction ID to be voided or reversed.

Message Body Type

Data Type Description
Rest.Undo The message body containing transaction data.

Return Type

Data Type Description
Response Transaction response data.
Note: For Bankcard (BCP) transactions, the response object is BankcardTransactionResponsePro.
For Electronic Checking (ECK) transactions, the response object is ElectronicCheckingTransactionResponse.
For Stored Value Account (SVA) transactions, the response object is StoredValueTransactionResponse.

Exceptions

CWSFault CWSInvalidOperationFault
AuthenticationFault CWSInvalidServiceInformationFault
ExpiredTokenFault CWSOperationNotSupportedFault
InvalidTokenFault CWSTransactionAlreadySettledFault
CWSConnectionFault CWSTransactionFailedFault
CWSExtendedDataNotSupportedFault CWSTransactionServiceUnavailableFault
CWSInvalidMessageFormatFault CWSValidationResultFault

For additional details about each fault, refer to Transaction Processing Faults in the CWS Developer API Reference.

PHP Code Sample

/* NOTE: Use this function to void an authorized transaction
 * $transactionID is the known transaction ID of a previous transaction*/
 
public function undo( $transactionID, $creds = null, $txnType = null )
{
	if (! $this->signOn ())
		return false;
 
	$UndoType = '"$type":"Undo,http://schemas.nabcommerce.com/CWS/v2.0/Transactions/Rest",';
 
	if ($this->svc instanceof BankcardService || $txnType == "BCP")
	{
		$DifferenceData = new BankcardUndo();
		$DifferenceData->PINDebitReason = 'NotSet';
		$DifferenceData->ForceVoid = false;
		$DiffType = '"$type":"BankcardUndo,http://schemas.nabcommerce.com/CWS/v2.0/Transactions/Bankcard",';
	}
	if ($this->svc instanceof ElectronicCheckingService || $txnType == "ECK")
	{
		$DifferenceData = new UndoDifferenceData();
		$DiffType = '"$type":"DifferenceData,http://schemas.nabcommerce.com/CWS/v2.0/Transactions",';
	}
 
	$DifferenceData->TransactionId = $transactionID;
	if ($creds != null)
	{
		$DifferenceData->Addendum = new Addendum ();
		$DifferenceData->Addendum->Unmanaged = new Unmanaged ();
		$DifferenceData->Addendum->Unmanaged->Any = new Any ();
		$DifferenceData->Addendum->Unmanaged->Any->string = $creds;
	}
 
	// Build Capture
	$msgBody = new Rest_Undo ();
	$msgBody->ApplicationProfileId = $this->appProfileID;
	$msgBody->DifferenceData = $DifferenceData;
 
	$action = 'PUT';
	$url = $this->txn.'/'.$this->workflowId.'/'.$transactionID;
 
	// Format the message
	$diffString = '"DifferenceData":{';
	$msgBody = (string)json_encode($msgBody);
	$msgBody = str_replace('{"ApplicationProfileId"', '{'.$UndoType.'"ApplicationProfileId"', $msgBody);
	$msgBody = str_replace($diffString, $diffString.$DiffType, $msgBody);
	$msgBody = str_replace(' ', '', $msgBody); // Make sure no spaces remain in the body.
	$response = curl_json($msgBody, $url, $action, $this->session_token);
	if(isset($response->body->ErrorId))
	{
		handleRestFault($response);
		return false;
	}
	if(isset($response[2]))
		return $response[2];
}

C# Code Sample

public Response Undo(string sessionToken, Undo undo, string applicationProfileId, string workflowId)
{
	var isJson = string.Equals(_msgFormat, MessageFormat.JSON.ToString());
	var requestString = RestBaseUri + "/" + workflowId + "/" + undo.TransactionId;
	var restUndo = new schemas.nabcommerce.com.CWS.v2._0.Transactions.Rest.Undo();
	restUndo.ApplicationProfileId = applicationProfileId;
 
	if(undo.GetType() == typeof(BankcardUndo))
		restUndo.DifferenceData = Utilities.SwapObjectsNamespace(undo);
	else
		restUndo.DifferenceData = Utilities.SwapObjectsNamespace(undo);
 
	var request = RestHelper.CreateRestRequest(restUndo, requestString, HttpMethod.PUT, sessionToken, isJson);
	try
	{
		if (isJson)
			return RestHelper.GetResponse(request, isJson);
		// For XML and Undo we do not know the specific type we will be getting back from the server. 
		// For this we can get the string response back determine what type it is from this response 
		// and then turn it into the desired object. 
		var strResponse = RestHelper.GetResponse(request, isJson, false);
		if (strResponse.Contains("BankcardTransactionResponsePro"))
			return RestHelper.GetCWSObjectFromXml(strResponse);
		if (strResponse.Contains("ElectronicCheckingTransactionResponse"))
			return RestHelper.GetCWSObjectFromXml(strResponse);
		if (strResponse.Contains("StoredValueTransactionResponse"))
			return RestHelper.GetCWSObjectFromXml(strResponse);
	}
	catch (Exception ex)
	{
		RestFaultHandler.HandleFaultException(ex, isJson);
	}
}

Comments